For AI agents: markdown of this page — /docs-content-en/entities/files/download.md documentation index — /llms.txt

Download file

GET /v1/files/:id/download

Downloads file contents through the Vibecode proxy with automatic authorization. Unlike the downloadUrl field in the GET /v1/files/:id response, this endpoint adds authorization on every call — you do not need to extract and insert the token manually. The response is a binary stream with a Content-Disposition header; browsers offer to save the file automatically.

Parameters

Parameter In Type Required Description
id path number yes File ID. Get it: GET /v1/files or GET /v1/files/:id

The request body is empty.

Examples

curl — personal key

Terminal 
# Save to a file using the original name from the Content-Disposition header
curl -OJ -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/files/205/download

# Specify the file name explicitly
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/files/205/download \
  -o myfile.pdf

curl — OAuth app

Terminal 
curl -OJ \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/files/205/download

JavaScript — personal key

javascript 
const fileId = 205

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/files/${fileId}/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))
}

// Save the blob in the browser
const blob = await res.blob()
const url = URL.createObjectURL(blob)
const a = document.createElement('a')
a.href = url
a.download = res.headers.get('Content-Disposition')?.match(/filename="(.+?)"/)?.[1] ?? 'file'
a.click()
URL.revokeObjectURL(url)

JavaScript — OAuth app

javascript 
const fileId = 205

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/files/${fileId}/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 headers

On success the binary file contents are returned (HTTP 200). There is no ## Response fields section — the response body is not JSON.

Header Example value Description
Content-Type application/pdf Content type. Depends on the file type: text/plain, image/png, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, etc.
Content-Disposition attachment; filename="report.pdf" File name for saving. Browsers use it automatically when downloading
Content-Length 31232 File size in bytes. Sent if known from metadata

Error response example

404 — file not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Could not find entity with id '99999999'."
  }
}

Errors

HTTP Code Description
401 MISSING_API_KEY The X-Api-Key header was not provided
401 INVALID_API_KEY Invalid or expired key
403 SCOPE_DENIED The key lacks the disk scope
404 ENTITY_NOT_FOUND A file with this id does not exist or is not accessible to the key
404 DOWNLOAD_URL_NOT_FOUND The file has no download address
502 DOWNLOAD_FAILED Bitrix24 returned an error during proxying (for example, 403)

Full list of common API errors — Error codes.

Known specifics

  • Authorization is added automatically. For OAuth app keys, Vibecode adds the authorization token to the request on every call. For webhook keys the token is already embedded in the address — Vibecode uses the address as is.
  • The downloadUrl field from GET /v1/files/:id is temporary. This endpoint (/download) is the stable way to download: each time it fetches the current address and adds authorization. Accessing a saved downloadUrl directly may fail once the token expires.

See also