Export document — Brigg developers

Access & visibility

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

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.

formatstringRequired

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".

revisionstringOptional

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 to choose a supported format. Send this command with an idempotency key, then pass the returned file_id to Get file download. 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 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.

file_idstringRequired

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.

filenamestringRequired

Download filename, including the extension for a rendered output. An original upload retains its filename.

content_typestring or nullRequired

Media type of the downloadable output; null only when an older uploaded original has no recorded media type.

size_bytesnumber or nullRequired

Output byte length; null only when an older original has no recorded size.

sourceobjectRequired

Identity and exact captured state of the source document used for this export.

Nested fields

file_idstringRequired

Stable identity of the source document, distinct from the rendered download's file_id.

kindstringRequired

Source document kind, independent of the chosen output format.

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

revisionstring or nullRequired

Opaque token identifying the captured source content. Null is possible for an older uploaded file. It is not a version selector.

version_idstring or nullRequired

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

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": "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"
    }
  ]
}

Full response JSON schema

{
  "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"
      }
    }
  ]
}

Try the request

Use your API key in a server environment.

Example scenarioAct as a memberRequires administrator-approved delegation.

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

Request

cURL

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

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

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

cURL

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

TypeScript

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

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",
    "Brigg-Act-As": actAs,
    "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

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",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
        "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

200 OK Response example

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

Illustrative values, not a live response.

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

Request

cURL

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

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

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

cURL

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

TypeScript

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

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",
    "Brigg-Act-As": actAs,
    "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

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",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
        "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

200 OK Response example

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

Illustrative values, not a live response.

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

Request

cURL

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

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

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

cURL

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

TypeScript

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

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",
    "Brigg-Act-As": actAs,
    "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

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",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
        "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

200 OK Response example

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

Illustrative values, not a live response.