# Export document

Export an accessible document using its file ID. Download an uploaded file unchanged, or render a text or generated document in a supported format. The default is the saved state. The result identifies both the download file and the source revision.

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

## Access & visibility

Allow `documents.ExportDocument` 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 | The source document's stable file_id from GetDocument, ListDocuments, SearchDocuments or CompleteUpload. No internal document or bundle ID is needed. At least 1 character. |
| `format` | string | Yes | Choose from GetDocument.capabilities.export.formats: original returns an upload unchanged; md is available for text documents; pdf and docx render text or generated documents. Allowed: `"original"`, `"md"`, `"pdf"`, `"docx"`. |
| `revision` | string | No | Omit for saved. current includes only the acting member’s own generated draft, otherwise the saved version. For exact historical content, pass an accessible version_id. A read/edit revision token is not a version ID. At least 1 character. At most 200 characters. |

## Export, then download

Inspect [Get document](https://developer.brigg.app/reference/documents/GetDocument) to choose a supported format. Send this command with an idempotency key, then pass the returned `file_id` to [Get file download](https://developer.brigg.app/reference/documents/GetFileDownload). Download from its temporary URL without sending your API key to that URL. Reuse the same acting member throughout.

The source is unchanged. `original` returns the existing uploaded file without copying or converting it. A rendered export is a separate private file; it is not automatically filed into a folder or shared with the source’s audience. A PDF upload cannot be converted to Word or Markdown by this operation.

## Choose the content to export

For a generated document, the default `saved` means its published saved state, never a private draft. If there is no saved state, Brigg returns `no_saved_version`; choose `current` explicitly to export the acting member’s draft. Other members’ drafts are never selected.

Collaborative text has no separate unsaved layer: `saved` and `current` both capture live content and require collaboration to be available. An explicit history `version_id` exports that state without silently falling back to different content. Use [List text document versions](https://developer.brigg.app/reference/documents/ListTextDocumentVersions) to discover text history. Uploaded originals accept `saved` and `current` for the same verified bytes.

An idempotent retry returns the same export. To capture later edits, make a new command with a new idempotency key.

## Response

Returns **200 OK** with a JSON body.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file_id` | string | Yes | File to download with GetFileDownload. For original, this equals the source file_id. Rendered exports create a separate private file owned by the acting member. |
| `filename` | string | Yes | Download filename, including the extension for a rendered output. An original upload retains its filename. |
| `content_type` | string or null | Yes | Media type of the downloadable output; null only when an older uploaded original has no recorded media type. |
| `size_bytes` | number or null | Yes | Output byte length; null only when an older original has no recorded size. |
| `source` | [object](#response-source) | Yes | Identity and exact captured state of the source document used for this export. |

### response.source

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file_id` | string | Yes | Stable identity of the source document, distinct from the rendered download's file_id. |
| `kind` | string | Yes | Source document kind, independent of the chosen output format. Allowed: `"file"`, `"text_document"`, `"generated_document"`. |
| `revision` | string or null | Yes | Opaque token identifying the captured source content. Null is possible for an older uploaded file. It is not a version selector. |
| `version_id` | string or null | Yes | Accessible saved source version, if one was captured. Retain it with source.file_id to export that state later. Null means no historical version was identified. |

## Errors & retries

Set `BRIGG_REQUEST_ID` once for each logical action. The samples send it as `Idempotency-Key`. Reuse the same value and body on retries, including after a timeout; a missing response does not prove the action failed.

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` | Use saved, current or a valid saved version ID, not a read/edit revision token. |
| 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 source does not exist or is not visible to this acting member. |
| 429 | `rate_limited` | Wait for Retry-After before retrying. Reuse the original Idempotency-Key. |
| 422 | `unsupported_format` | Choose a format from details.supported, or inspect GetDocument again. A PDF upload cannot be converted to Word or Markdown. |
| 422 | `unsupported_revision` | Choose a revision selection supported by this document. Uploaded originals have no historical version selector. |
| 409 | `no_saved_version` | The generated document has no saved version. Save it in Brigg or explicitly choose current to export the acting member’s draft. |
| 404 | `version_not_found` | That historical version is absent or inaccessible. Do not fall back to another revision without choosing to do so. |
| 409 | `scan_blocked` | The original file is blocked by its scan result. Retrying unchanged does not unblock it. |
| 409 | `collab_unavailable` | Live collaborative text is unavailable. Retry when collaboration is restored or deliberately select a known history version. |
| 409 | `source_changed` | The source changed during rendering. Read its state again before requesting another export. |
| 409 | `not_renderable` | This generated document has no renderable content. Open and save its content in Brigg before exporting. |

## Next steps

- [Get document](https://developer.brigg.app/reference/documents/GetDocument)
- [Get file download](https://developer.brigg.app/reference/documents/GetFileDownload)
- [List text document versions](https://developer.brigg.app/reference/documents/ListTextDocumentVersions)
- [List documents](https://developer.brigg.app/reference/documents/ListDocuments)

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

## Examples

### Render text as PDF

Export the live saved content, then download the returned file_id.
#### cURL


```sh
curl 'https://api.brigg.app/v1/operations/documents.ExportDocument' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "file_id": "f_project_notes",
  "format": "pdf"
}'
```

#### TypeScript


```typescript
const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/documents.ExportDocument", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "file_id": "f_project_notes",
    "format": "pdf"
  }),
});
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

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "file_id": "f_project_notes",
  "format": "pdf"
}
request = Request(
    "https://api.brigg.app/v1/operations/documents.ExportDocument",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    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_pdf",
  "filename": "Project notes.pdf",
  "content_type": "application/pdf",
  "size_bytes": 18432,
  "source": {
    "file_id": "f_project_notes",
    "kind": "text_document",
    "revision": "tdr_before_edit",
    "version_id": "tdv_a1b2c3d4"
  }
}
```

### Keep an uploaded original

No conversion or copy is made. The download and source IDs are identical.
#### cURL


```sh
curl 'https://api.brigg.app/v1/operations/documents.ExportDocument' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "file_id": "f_agreement",
  "format": "original"
}'
```

#### TypeScript


```typescript
const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/documents.ExportDocument", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "file_id": "f_agreement",
    "format": "original"
  }),
});
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

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "file_id": "f_agreement",
  "format": "original"
}
request = Request(
    "https://api.brigg.app/v1/operations/documents.ExportDocument",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    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_agreement",
  "filename": "Agreement.pdf",
  "content_type": "application/pdf",
  "size_bytes": 48231,
  "source": {
    "file_id": "f_agreement",
    "kind": "file",
    "revision": "original_revision_1",
    "version_id": null
  }
}
```

### Export a saved text version

Use a version_id discovered for this same file_id, not its current revision token.
#### cURL


```sh
curl 'https://api.brigg.app/v1/operations/documents.ExportDocument' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $BRIGG_REQUEST_ID" \
  --data-raw '{
  "file_id": "f_project_notes",
  "format": "md",
  "revision": "tdv_a1b2c3d4"
}'
```

#### TypeScript


```typescript
const requestId = process.env.BRIGG_REQUEST_ID;
if (!requestId) throw new Error("Set BRIGG_REQUEST_ID once per action and reuse it on retries.");

const response = await fetch("https://api.brigg.app/v1/operations/documents.ExportDocument", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": requestId, // Create once per action; reuse on retries.
  },
  body: JSON.stringify({
    "file_id": "f_project_notes",
    "format": "md",
    "revision": "tdv_a1b2c3d4"
  }),
});
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

request_id = os.environ["BRIGG_REQUEST_ID"]  # Reuse for retries of this action.
payload = {
  "file_id": "f_project_notes",
  "format": "md",
  "revision": "tdv_a1b2c3d4"
}
request = Request(
    "https://api.brigg.app/v1/operations/documents.ExportDocument",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": request_id,  # Create once per action; reuse on retries.
    },
    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_md",
  "filename": "Project notes.md",
  "content_type": "text/markdown; charset=utf-8",
  "size_bytes": 45,
  "source": {
    "file_id": "f_project_notes",
    "kind": "text_document",
    "revision": "tdr_before_edit",
    "version_id": "tdv_a1b2c3d4"
  }
}
```

## JSON schemas


```json-schema-request
{
  "type": "object",
  "properties": {
    "file_id": {
      "type": "string",
      "minLength": 1,
      "description": "The source document's stable file_id from GetDocument, ListDocuments, SearchDocuments or CompleteUpload. No internal document or bundle ID is needed."
    },
    "format": {
      "type": "string",
      "enum": [
        "original",
        "md",
        "pdf",
        "docx"
      ],
      "description": "Choose from GetDocument.capabilities.export.formats: original returns an upload unchanged; md is available for text documents; pdf and docx render text or generated documents."
    },
    "revision": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Omit for saved. current includes only the acting member’s own generated draft, otherwise the saved version. For exact historical content, pass an accessible version_id. A read/edit revision token is not a version ID."
    }
  },
  "required": [
    "format",
    "file_id"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "file_id": "f_project_notes",
      "format": "pdf"
    }
  ]
}
```


```json-schema-response
{
  "type": "object",
  "properties": {
    "file_id": {
      "type": "string",
      "description": "File to download with GetFileDownload. For original, this equals the source file_id. Rendered exports create a separate private file owned by the acting member."
    },
    "filename": {
      "type": "string",
      "description": "Download filename, including the extension for a rendered output. An original upload retains its filename."
    },
    "content_type": {
      "type": [
        "string",
        "null"
      ],
      "description": "Media type of the downloadable output; null only when an older uploaded original has no recorded media type."
    },
    "size_bytes": {
      "type": [
        "number",
        "null"
      ],
      "description": "Output byte length; null only when an older original has no recorded size."
    },
    "source": {
      "type": "object",
      "properties": {
        "file_id": {
          "type": "string",
          "description": "Stable identity of the source document, distinct from the rendered download's file_id."
        },
        "kind": {
          "type": "string",
          "enum": [
            "file",
            "text_document",
            "generated_document"
          ],
          "description": "Source document kind, independent of the chosen output format."
        },
        "revision": {
          "type": [
            "string",
            "null"
          ],
          "description": "Opaque token identifying the captured source content. Null is possible for an older uploaded file. It is not a version selector."
        },
        "version_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Accessible saved source version, if one was captured. Retain it with source.file_id to export that state later. Null means no historical version was identified."
        }
      },
      "required": [
        "file_id",
        "kind",
        "revision",
        "version_id"
      ],
      "additionalProperties": false,
      "description": "Identity and exact captured state of the source document used for this export."
    }
  },
  "required": [
    "file_id",
    "filename",
    "content_type",
    "size_bytes",
    "source"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "file_id": "f_project_notes_pdf",
      "filename": "Project notes.pdf",
      "content_type": "application/pdf",
      "size_bytes": 18432,
      "source": {
        "file_id": "f_project_notes",
        "kind": "text_document",
        "revision": "tdr_before_edit",
        "version_id": "tdv_a1b2c3d4"
      }
    }
  ]
}
```