List documents — Brigg developers

Access & visibility

Allow documents.ListDocuments on your API key.

Workspace access by default. Private member data requires approved member delegation through Brigg-Act-As; the key supplies permissions while private ownership and project boundaries remain enforced.

Set up authentication · Choose permissions

Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.

scopestringRequired

Document collection: org is shared with the workspace; user is private to the calling person; resources contains the workspace's supplied resources. A move changes who can read the document; omit scope when only changing its folder.

Allowed: "org", "user", "resources".

pathstringOptional

Folder path within the selected document collection. An empty string is its root.

Default: "". At most 1024 characters.

Response

Returns 200 OK with a JSON body.

This operation has no continuation cursor. An empty items array means no matching visible results were returned.

pathstringRequired

Folder path within the selected document collection. An empty string is its root.

foldersarray of objectRequired

Immediate subfolders of the requested document location.

Item fields

namestringRequired

Display name.

pathstringRequired

Folder path within the selected document collection. An empty string is its root.

labelstringOptional

Human-readable name for this content or saved version.

itemsarray of DocumentRequired

Documents immediately inside the selected collection and folder; child folders are returned separately in folders. This operation has no cursor pagination.

Item fields

file_idstringRequired

Stable file ID returned by documents.CompleteUpload, documents.ListDocuments or a document creation operation. Use the same ID for downloads, attachments and supported file-based workflows. Do not use a filename or storage path.

filenamestringRequired

Original filename, including its extension.

size_bytesnumber or nullRequired

File size in bytes. Null for a document without a downloadable binary file.

content_typestring or nullRequired

Media type of the file, such as application/pdf. Null when no binary file exists.

pathstringRequired

Folder path within the selected document collection. An empty string is its root.

created_atnumberRequired

Creation time in Unix milliseconds.

owner_account_idstring or nullRequired

Account that owns a private document, or null for a workspace document.

created_bystring or nullRequired

Account that created the record, or null when no account is recorded.

kindstring or nullRequired

Document origin or format: user_upload, agent_generated, signed_document and other file categories; text_document identifies collaborative text, while document identifies a generated Brigg document.

scan_statusstring or nullRequired

Malware scan state. Threats and failed scans block downloads. An unsupported file cannot be processed; only its original uploader can retrieve it as a forced download. Null is not proof of readiness.

document_kindstringRequired

file = an uploaded file (its original bytes); text_document = a collaborative Tekstdokument (markdown); generated_document = a formatted document Brigg generated («Lag dokument»).

Allowed: "file", "text_document", "generated_document".

Errors & retries

This operation reads data. It needs no idempotency key and can be retried after a transient failure.

For rate limits, follow the server’s retry guidance and back off. See HTTP errors and safe retries and limits.

HTTP status	Code	What to do
400	`invalid_json`	Send a JSON object with Content-Type: application/json.
400	`invalid_input`	Check the request fields and types.
401	`invalid_key`	The workspace API key is missing, invalid or revoked.
403	`forbidden`	Check the key’s operation and resource grants. If Brigg-Act-As is supplied, the key must be authorized to delegate to that member.
404	`not_found`	The requested operation or resource is not available to this credential.
429	`rate_limited`	Wait for Retry-After before retrying.

Next steps

Upload and download files

Download OpenAPI · Versioning & retirement

JSON schemas

Use the complete schemas for validation or client generation.

Full request JSON schema

{
  "type": "object",
  "properties": {
    "scope": {
      "type": "string",
      "enum": [
        "org",
        "user",
        "resources"
      ],
      "description": "Document collection: org is shared with the workspace; user is private to the calling person; resources contains the workspace's supplied resources. A move changes who can read the document; omit scope when only changing its folder."
    },
    "path": {
      "type": "string",
      "maxLength": 1024,
      "default": "",
      "description": "Folder path within the selected document collection. An empty string is its root."
    }
  },
  "required": [
    "scope"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "scope": "org"
    }
  ]
}

Full response JSON schema

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Folder path within the selected document collection. An empty string is its root."
    },
    "folders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Display name."
          },
          "path": {
            "type": "string",
            "description": "Folder path within the selected document collection. An empty string is its root."
          },
          "label": {
            "type": "string",
            "description": "Human-readable name for this content or saved version."
          }
        },
        "required": [
          "name",
          "path"
        ],
        "additionalProperties": false
      },
      "description": "Immediate subfolders of the requested document location."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "file_id": {
            "type": "string",
            "description": "Stable file ID returned by documents.CompleteUpload, documents.ListDocuments or a document creation operation. Use the same ID for downloads, attachments and supported file-based workflows. Do not use a filename or storage path.",
            "examples": [
              "file_proposal"
            ]
          },
          "filename": {
            "type": "string",
            "examples": [
              "Proposal.pdf"
            ],
            "description": "Original filename, including its extension."
          },
          "size_bytes": {
            "type": [
              "number",
              "null"
            ],
            "description": "File size in bytes. Null for a document without a downloadable binary file.",
            "examples": [
              48231
            ]
          },
          "content_type": {
            "type": [
              "string",
              "null"
            ],
            "description": "Media type of the file, such as application/pdf. Null when no binary file exists.",
            "examples": [
              "application/pdf"
            ]
          },
          "path": {
            "type": "string",
            "description": "Folder path within the selected document collection. An empty string is its root.",
            "examples": [
              "Proposals"
            ]
          },
          "created_at": {
            "type": "number",
            "description": "Creation time in Unix milliseconds."
          },
          "owner_account_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Account that owns a private document, or null for a workspace document.",
            "examples": [
              null
            ]
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "account_alex"
            ],
            "description": "Account that created the record, or null when no account is recorded."
          },
          "kind": {
            "type": [
              "string",
              "null"
            ],
            "description": "Document origin or format: user_upload, agent_generated, signed_document and other file categories; text_document identifies collaborative text, while document identifies a generated Brigg document.",
            "examples": [
              "user_upload"
            ]
          },
          "scan_status": {
            "type": [
              "string",
              "null"
            ],
            "description": "Malware scan state. Threats and failed scans block downloads. An unsupported file cannot be processed; only its original uploader can retrieve it as a forced download. Null is not proof of readiness.",
            "examples": [
              "clean"
            ]
          },
          "document_kind": {
            "type": "string",
            "enum": [
              "file",
              "text_document",
              "generated_document"
            ],
            "description": "`file` = an uploaded file (its original bytes); `text_document` = a collaborative Tekstdokument (markdown); `generated_document` = a formatted document Brigg generated («Lag dokument»).",
            "examples": [
              "file"
            ]
          }
        },
        "required": [
          "file_id",
          "filename",
          "size_bytes",
          "content_type",
          "path",
          "created_at",
          "owner_account_id",
          "created_by",
          "kind",
          "scan_status",
          "document_kind"
        ],
        "additionalProperties": false,
        "title": "Document"
      },
      "description": "Documents immediately inside the selected collection and folder; child folders are returned separately in folders. This operation has no cursor pagination."
    }
  },
  "required": [
    "path",
    "folders",
    "items"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "path": "Proposals",
      "folders": [],
      "items": [
        {
          "file_id": "file_proposal",
          "filename": "Proposal.pdf",
          "size_bytes": 48231,
          "content_type": "application/pdf",
          "path": "Proposals",
          "created_at": 1794301200000,
          "owner_account_id": null,
          "created_by": "account_alex",
          "kind": "user_upload",
          "scan_status": "clean",
          "document_kind": "file"
        }
      ]
    }
  ]
}

Try the request

Use your API key in a server environment.

Act as a memberRequires administrator-approved delegation.

Fictional values. Replace IDs and business details with values from your workspace.

Request

cURL

curl 'https://api.brigg.app/v1/operations/documents.ListDocuments' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "scope": "org"
}'

TypeScript

const response = await fetch("https://api.brigg.app/v1/operations/documents.ListDocuments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "scope": "org"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {
  "scope": "org"
}
request = Request(
    "https://api.brigg.app/v1/operations/documents.ListDocuments",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

cURL

curl 'https://api.brigg.app/v1/operations/documents.ListDocuments' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  --data-raw '{
  "scope": "org"
}'

TypeScript

const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const response = await fetch("https://api.brigg.app/v1/operations/documents.ListDocuments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
  },
  body: JSON.stringify({
    "scope": "org"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {
  "scope": "org"
}
request = Request(
    "https://api.brigg.app/v1/operations/documents.ListDocuments",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

200 OK Response example

{
  "path": "Proposals",
  "folders": [],
  "items": [
    {
      "file_id": "file_proposal",
      "filename": "Proposal.pdf",
      "size_bytes": 48231,
      "content_type": "application/pdf",
      "path": "Proposals",
      "created_at": 1794301200000,
      "owner_account_id": null,
      "created_by": "account_alex",
      "kind": "user_upload",
      "scan_status": "clean",
      "document_kind": "file"
    }
  ]
}

Illustrative values, not a live response.