Get document — Brigg developers

Access & visibility

Allow documents.GetDocument 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.

file_idstringRequired

Stable file_id from ListDocuments, SearchDocuments, CompleteUpload or a document creation result. The same identity works across all document kinds.

At least 1 character.

Choose the next operation

Use kind and capabilities to choose a supported action. For an uploaded original, use Get file download directly or export as original. For collaborative text, Read text document returns Markdown and a revision for safe editing. Generated documents export as PDF or Word.

These capabilities describe the document under the current credential and selected data scope. Your API key also needs the next operation’s grant; capabilities never grant it. Internal source files and authoring commands are not exposed.

Response

Returns 200 OK with a JSON body.

file_idstringRequired

The requested document's stable identity. Exports do not replace this source document.

kindstringRequired

file is an uploaded original; text_document is collaborative Markdown; generated_document is a rendered Brigg document.

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

filenamestringRequired

Current document name. Text and generated documents need not have a filename extension.

scopestring or nullRequired

Current document collection: org is workspace-shared, user is personal, and resources is the resources collection. Null means no collection is recorded; it does not grant access. This is location metadata, not a request to move the document.

pathstringRequired

Folder path within the collection; empty means its root.

content_typestring or nullRequired

Original upload media type. Null for text and generated documents, whose export format determines their media type.

size_bytesnumber or nullRequired

Original upload byte length, or null when no original binary exists. Read the export result for its byte length.

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.

created_atnumberRequired

Creation time in Unix milliseconds.

created_bystring or nullRequired

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

owner_account_idstring or nullRequired

Member who owns a private document, or null for a shared document. Access is still checked independently of this metadata.

entry_idstring or nullRequired

Attached record ID, or null when no record is associated.

capabilitiesobjectRequired

Supported public reads and exports under the current credential and selected data scope; these are advisory and never grant permissions.

Nested fields

readobject or nullRequired

Non-null only when current Markdown can be read with ReadTextDocument. Null does not mean the original file cannot be downloaded.

Nested fields

format"markdown"Required

markdown identifies collaborative text readable through ReadTextDocument.

Always "markdown".

exportobjectRequired

Formats and revision selections that ExportDocument currently supports for this source.

Nested fields

formatsarray of stringRequired

Formats currently supported by ExportDocument for this document. original preserves uploaded bytes; md, pdf and docx render supported content. An empty list means export is unavailable.

Each item: "original", "md", "pdf", "docx".

revisionsarray of stringRequired

saved selects the saved state; current includes the acting member’s own generated draft; version means an accessible saved version ID can be supplied. These are available selections, not version IDs.

Each item: "saved", "current", "version".

unavailablestring or nullRequired

scan_blocked means the original bytes are blocked; collab_unavailable means live collaborative content is unavailable. Null means neither condition applies. An explicit historical text version may still be exportable without live collaboration.

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 file does not exist or is not visible to this acting member. A known ID does not grant access.
429	`rate_limited`	Wait for Retry-After before retrying.

Next steps

Download OpenAPI · Versioning & retirement

JSON schemas

Use the complete schemas for validation or client generation.

Full request JSON schema

{
  "type": "object",
  "properties": {
    "file_id": {
      "type": "string",
      "minLength": 1,
      "description": "Stable file_id from ListDocuments, SearchDocuments, CompleteUpload or a document creation result. The same identity works across all document kinds."
    }
  },
  "required": [
    "file_id"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "file_id": "f_project_notes"
    }
  ]
}

Full response JSON schema

{
  "type": "object",
  "properties": {
    "file_id": {
      "type": "string",
      "description": "The requested document's stable identity. Exports do not replace this source document."
    },
    "kind": {
      "type": "string",
      "enum": [
        "file",
        "text_document",
        "generated_document"
      ],
      "description": "file is an uploaded original; text_document is collaborative Markdown; generated_document is a rendered Brigg document."
    },
    "filename": {
      "type": "string",
      "description": "Current document name. Text and generated documents need not have a filename extension."
    },
    "scope": {
      "type": [
        "string",
        "null"
      ],
      "description": "Current document collection: org is workspace-shared, user is personal, and resources is the resources collection. Null means no collection is recorded; it does not grant access. This is location metadata, not a request to move the document."
    },
    "path": {
      "type": "string",
      "description": "Folder path within the collection; empty means its root."
    },
    "content_type": {
      "type": [
        "string",
        "null"
      ],
      "description": "Original upload media type. Null for text and generated documents, whose export format determines their media type."
    },
    "size_bytes": {
      "type": [
        "number",
        "null"
      ],
      "description": "Original upload byte length, or null when no original binary exists. Read the export result for its byte length."
    },
    "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."
    },
    "created_at": {
      "type": "number",
      "description": "Creation time in Unix milliseconds."
    },
    "created_by": {
      "type": [
        "string",
        "null"
      ],
      "description": "Account that created the record, or null when no account is recorded."
    },
    "owner_account_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Member who owns a private document, or null for a shared document. Access is still checked independently of this metadata."
    },
    "entry_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Attached record ID, or null when no record is associated."
    },
    "capabilities": {
      "type": "object",
      "properties": {
        "read": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "format": {
              "type": "string",
              "const": "markdown",
              "description": "markdown identifies collaborative text readable through ReadTextDocument."
            }
          },
          "additionalProperties": false,
          "required": [
            "format"
          ],
          "description": "Non-null only when current Markdown can be read with ReadTextDocument. Null does not mean the original file cannot be downloaded."
        },
        "export": {
          "type": "object",
          "properties": {
            "formats": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "original",
                  "md",
                  "pdf",
                  "docx"
                ]
              },
              "description": "Formats currently supported by ExportDocument for this document. original preserves uploaded bytes; md, pdf and docx render supported content. An empty list means export is unavailable."
            },
            "revisions": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "saved",
                  "current",
                  "version"
                ]
              },
              "description": "saved selects the saved state; current includes the acting member’s own generated draft; version means an accessible saved version ID can be supplied. These are available selections, not version IDs."
            }
          },
          "required": [
            "formats",
            "revisions"
          ],
          "additionalProperties": false,
          "description": "Formats and revision selections that ExportDocument currently supports for this source."
        },
        "unavailable": {
          "type": [
            "string",
            "null"
          ],
          "description": "scan_blocked means the original bytes are blocked; collab_unavailable means live collaborative content is unavailable. Null means neither condition applies. An explicit historical text version may still be exportable without live collaboration."
        }
      },
      "required": [
        "read",
        "export",
        "unavailable"
      ],
      "additionalProperties": false,
      "description": "Supported public reads and exports under the current credential and selected data scope; these are advisory and never grant permissions."
    }
  },
  "required": [
    "file_id",
    "kind",
    "filename",
    "scope",
    "path",
    "content_type",
    "size_bytes",
    "scan_status",
    "created_at",
    "created_by",
    "owner_account_id",
    "entry_id",
    "capabilities"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "file_id": "f_project_notes",
      "kind": "text_document",
      "filename": "Project notes",
      "scope": "org",
      "path": "Projects",
      "content_type": null,
      "size_bytes": null,
      "scan_status": null,
      "created_at": 1794301200000,
      "created_by": "a_alex",
      "owner_account_id": null,
      "entry_id": null,
      "capabilities": {
        "read": {
          "format": "markdown"
        },
        "export": {
          "formats": [
            "md",
            "pdf",
            "docx"
          ],
          "revisions": [
            "saved",
            "current",
            "version"
          ]
        },
        "unavailable": null
      }
    }
  ]
}

Try the request

Use your API key in a server environment.

Act as a memberRequires administrator-approved delegation.

The same file_id is used to read, edit and export this document.

Request

cURL

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

TypeScript

const response = await fetch("https://api.brigg.app/v1/operations/documents.GetDocument", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "file_id": "f_project_notes"
  }),
});
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 = {
  "file_id": "f_project_notes"
}
request = Request(
    "https://api.brigg.app/v1/operations/documents.GetDocument",
    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.GetDocument' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  --data-raw '{
  "file_id": "f_project_notes"
}'

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.GetDocument", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
  },
  body: JSON.stringify({
    "file_id": "f_project_notes"
  }),
});
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 = {
  "file_id": "f_project_notes"
}
request = Request(
    "https://api.brigg.app/v1/operations/documents.GetDocument",
    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

{
  "file_id": "f_project_notes",
  "kind": "text_document",
  "filename": "Project notes",
  "scope": "org",
  "path": "Projects",
  "content_type": null,
  "size_bytes": null,
  "scan_status": null,
  "created_at": 1794301200000,
  "created_by": "a_alex",
  "owner_account_id": null,
  "entry_id": null,
  "capabilities": {
    "read": {
      "format": "markdown"
    },
    "export": {
      "formats": [
        "md",
        "pdf",
        "docx"
      ],
      "revisions": [
        "saved",
        "current",
        "version"
      ]
    },
    "unavailable": null
  }
}

Illustrative values, not a live response.