Download object

GET /v1/storage/objects/:key

Returns the object's content or a temporary download link. The behavior is determined by the query parameters: by default — a redirect, ?inline=true — content in the response body.

Parameters

Path

Query

Examples

curl — personal key

curl -L "https://vibecode.bitrix24.com/v1/storage/objects/reports%2F2024%2Fannual.pdf" \
  -H "X-Api-Key: YOUR_API_KEY" \
  --output annual.pdf

curl — OAuth application

curl -L "https://vibecode.bitrix24.com/v1/storage/objects/reports%2F2024%2Fannual.pdf" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  --output annual.pdf

JavaScript — personal key

// Get a temporary link (without following the redirect)
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/storage/objects/reports%2F2024%2Fannual.pdf',
  {
    redirect: 'manual',
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const url = res.headers.get('location') // temporary link: 10 minutes requested, the signature may expire earlier

JavaScript — OAuth application

const res = await fetch(
  'https://vibecode.bitrix24.com/v1/storage/objects/reports%2F2024%2Fannual.pdf',
  {
    redirect: 'manual',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const url = res.headers.get('location')

Response

The response format depends on the query parameters.

Default — redirect

Returns 302 Found with a temporary link in the Location header. The requested link lifetime is 10 minutes and the signature may expire earlier: follow it right away instead of storing it. Browsers follow the redirect automatically; in server-side code use redirect: 'manual' and read response.headers.get('location').

HTTP/1.1 302 Found
Location: <temporary link>
Cache-Control: no-store

?inline=true — content in the response body

Returns 200 OK with the object's content directly in the response body. By default the browser saves the file (the Content-Disposition: attachment header). To have the browser display the file instead of downloading it, add &inline_render=true.

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 204800
ETag: "e3b0c44298fc1c149afbf4c8996fb92"
X-Content-Type-Options: nosniff
Content-Disposition: attachment; filename="annual.pdf"

<object content>

?download=<name> — download with a given name

Returns 302 Found. When following the link from the Location header, storage serves the file with the Content-Disposition: attachment; filename="<name>" header, so the browser will prompt to save it with the given name.

HTTP/1.1 302 Found
Location: <temporary link with the given file name>
Cache-Control: no-store

Error response example

404 — object not found:

{
  "success": false,
  "error": {
    "code": "STORAGE_OBJECT_NOT_FOUND",
    "message": "Object reports/2024/annual.pdf not found"
  }
}

Errors

The method is limited to 600 requests per minute per Bitrix24 account. All API keys of the account share this budget, and the limit is divided across active platform replicas. The effective value arrives in x-ratelimit-limit; after a 429, retry after the delay in Retry-After.

The full list of general errors — Errors.

• An app key with no employee session sees only the app-shared file. Employees of an app claim logical names independently of each other, so several objects may hold one name. A request made with an app key and NO Authorization header addresses the app-shared file; if the name is held solely by per-employee files, the response is 404 STORAGE_OBJECT_NOT_FOUND. To reach an employee's file, pass that employee's session in Authorization: Bearer, or address the object by its identifier.

See also

• Objects
• List objects
• Object metadata
• Upload