Download document DOCX

GET /v1/documents/:id/download

Downloads the DOCX file of a generated document through Vibecode: the platform adds Bitrix24 authorization to the request automatically. A CRM record document is downloaded the same way through its own route.

Document	Route	Scope
App document	`GET /v1/documents/:id/download`	`documentgenerator`
CRM record document	`GET /v1/crm-documents/:id/download`	`crm`

Parameters

Parameter	Type	Required	Description
`id` (path)	number	yes	Document ID, a positive integer. App documents: `GET /v1/documents`, CRM record documents: `GET /v1/crm-documents`

No request body is sent. The examples below are for an app document. For a CRM record document, replace documents with crm-documents in the URL.

Examples

curl — personal key

Terminal

curl --fail-with-body "https://vibecode.bitrix24.com/v1/documents/2001/download" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o document-2001.docx

curl — OAuth application

Terminal

curl --fail-with-body "https://vibecode.bitrix24.com/v1/documents/2001/download" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -o document-2001.docx

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/documents/2001/download', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

if (!res.ok) {
  const body = await res.json()
  throw new Error(body.error?.code ?? String(res.status))
}

const blob = await res.blob()

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/documents/2001/download', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

if (!res.ok) {
  const body = await res.json()
  throw new Error(body.error?.code ?? String(res.status))
}

const blob = await res.blob()

Response fields

On success the HTTP status is 200 OK and the response body contains the bytes of the DOCX file. File details come in the headers.

Header	Example value	Description
`Content-Type`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	Content type that Bitrix24 returned for the document file
`Content-Disposition`	`attachment; filename="document-2001.docx"`	File name for saving, in the form `document-<id>.docx`. The document title is not included

Response example

http

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="document-2001.docx"
Content-Length: 914

<binary .docx content, 914 bytes, starts with PK>

Error response example

404 — document not found:

JSON

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Document not found."
  }
}

Errors

HTTP	Code	Description
400	`INVALID_PARAMS`	`id` is not a positive integer. Message: `Document ID must be a positive integer.`
404	`ENTITY_NOT_FOUND`	No document with this `id`. Message: `Document not found.`
409	`DOCUMENT_NOT_READY`	CRM record documents only: the document has no DOCX file yet. Retry the request in a few seconds
502	`DOWNLOAD_FAILED`	Bitrix24 did not return the file: it responded with an error code, sent JSON instead of the file, pointed to a URL outside the Bitrix24 account, or the response could not be read in full. For an app document, also when the file is larger than 10 MiB
422	`BITRIX_ERROR`	Bitrix24 rejected the request. The reason is in `error.message`
403	`BITRIX_ACCESS_DENIED`	Bitrix24 denied access to the document. For a CRM record document, also when the record it is attached to does not exist
403	`SCOPE_DENIED`	The key lacks the route scope: `documentgenerator` for an app document, `crm` for a CRM record document
401	`MISSING_API_KEY`	The `X-Api-Key` header is missing
401	`TOKEN_MISSING`	No tokens are mapped to the key — an OAuth application key was called without a user session

Full list of common API errors — Errors.

Known specifics

A read-only key works. Downloading does not count as a write, so a key without write permission gets the file just like a full-access key.

DOCX is ready before PDF and image. In the first seconds after a document is created, the PDF and image routes respond with 409 DOCUMENT_NOT_READY, while this route already returns the file.

The downloadUrlMachine field points to this route. In the responses of GET /v1/documents/:id and GET /v1/crm-documents/:id, the field contains the route URL for the same document. API responses contain no Bitrix24 access secrets.