# Get document

Inspect a document by its file ID: its kind, location and supported reads and exports. Capabilities describe what the acting member can do now; each later call checks access again.

POST https://api.brigg.app/v1/operations/documents.GetDocument

## Access & visibility

Allow `documents.GetDocument` on your API key.

**Workspace access by default.** Private member data requires [approved member delegation](https://developer.brigg.app/authentication#member-delegation) through `Brigg-Act-As`; the key supplies permissions while private ownership and project boundaries remain enforced.

[Set up authentication](https://developer.brigg.app/authentication) · [Choose permissions](https://developer.brigg.app/permissions)

## Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file_id` | string | Yes | 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](https://developer.brigg.app/reference/documents/GetFileDownload) directly or export as `original`. For collaborative text, [Read text document](https://developer.brigg.app/reference/documents/ReadTextDocument) 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.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file_id` | string | Yes | The requested document's stable identity. Exports do not replace this source document. |
| `kind` | string | Yes | file is an uploaded original; text_document is collaborative Markdown; generated_document is a rendered Brigg document. Allowed: `"file"`, `"text_document"`, `"generated_document"`. |
| `filename` | string | Yes | Current document name. Text and generated documents need not have a filename extension. |
| `scope` | string or null | Yes | 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` | string | Yes | Folder path within the collection; empty means its root. |
| `content_type` | string or null | Yes | Original upload media type. Null for text and generated documents, whose export format determines their media type. |
| `size_bytes` | number or null | Yes | Original upload byte length, or null when no original binary exists. Read the export result for its byte length. |
| `scan_status` | string or null | Yes | 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` | number | Yes | Creation time in Unix milliseconds. |
| `created_by` | string or null | Yes | Account that created the record, or null when no account is recorded. |
| `owner_account_id` | string or null | Yes | Member who owns a private document, or null for a shared document. Access is still checked independently of this metadata. |
| `entry_id` | string or null | Yes | Attached record ID, or null when no record is associated. |
| `capabilities` | [object](#response-capabilities) | Yes | Supported public reads and exports under the current credential and selected data scope; these are advisory and never grant permissions. |

### response.capabilities

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `read` | [object](#response-capabilities-read) or null | Yes | Non-null only when current Markdown can be read with ReadTextDocument. Null does not mean the original file cannot be downloaded. |
| `export` | [object](#response-capabilities-export) | Yes | Formats and revision selections that ExportDocument currently supports for this source. |
| `unavailable` | string or null | Yes | 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. |

### response.capabilities.read

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `format` | string | Yes | markdown identifies collaborative text readable through ReadTextDocument. Always `"markdown"`. |

### response.capabilities.export

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `formats` | array of string | Yes | 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"`. |
| `revisions` | array of string | Yes | 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"`. |

## 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](https://developer.brigg.app/http#errors) and [safe retries and limits](https://developer.brigg.app/reliability).

| 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

- [List documents](https://developer.brigg.app/reference/documents/ListDocuments)
- [Export document](https://developer.brigg.app/reference/documents/ExportDocument)
- [Read text document](https://developer.brigg.app/reference/documents/ReadTextDocument)
- [Get file download](https://developer.brigg.app/reference/documents/GetFileDownload)

[Download OpenAPI](https://developer.brigg.app/openapi.json) · [Versioning & retirement](https://developer.brigg.app/versioning)

## Examples

### Inspect a text document

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


```sh
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


```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


```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
```

#### Response example


```json
{
  "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
  }
}
```

## JSON schemas


```json-schema-request
{
  "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"
    }
  ]
}
```


```json-schema-response
{
  "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
      }
    }
  ]
}
```