Download a timeline comment attachment

GET /v1/timelines/:commentId/files/:fileRef/download

Downloads a file attached to a timeline comment. The response is a binary stream with a Content-Disposition header.

The endpoint accepts two different identifiers in fileRef, because a client may hold either one:

• Attachment ID. The account interface shows it, and file user-fields return it. This path computes access through the carrier entity — the comment itself — rather than through personal Disk permissions, so it reaches attachments that Disk file download refuses to serve;
• Disk object ID. This is the object key in the files field of the GET /v1/timelines/:id response. The path goes through personal Disk permissions, so it can be refused where the attachment-ID path would have succeeded.

The comment itself is read first, then the Disk object ID is tried, and the attachment ID only when the comment does not list that reference among its files. You do not have to state which identifier you are passing. This order is cheaper: the documented case costs two Bitrix24 calls instead of three.

Parameters

The request body is empty.

Examples

curl — personal key

# By Disk object ID — the key from the files field of the comment response
curl -OJ -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/timelines/67689/files/9747/download

# By attachment ID — when you have one
curl -OJ -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/timelines/67689/files/551/download

curl — OAuth application

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

JavaScript — personal key

// Take the attachment identifiers from the comment response
const comment = await fetch(
  'https://vibecode.bitrix24.com/v1/timelines/67689',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } },
).then(r => r.json())

for (const objectId of Object.keys(comment.data.files ?? {})) {
  const res = await fetch(
    `https://vibecode.bitrix24.com/v1/timelines/67689/files/${objectId}/download`,
    { headers: { 'X-Api-Key': 'YOUR_API_KEY' } },
  )
  if (!res.ok) {
    const { error } = await res.json()
    console.warn(`${objectId}: ${error.code}`)
    continue
  }
  console.log(objectId, 'bytes:', (await res.arrayBuffer()).byteLength)
}

JavaScript — OAuth application

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

const bytes = await res.arrayBuffer()

Response headers

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

Error response example

404 — the attachment belongs to a different comment:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Attachment 551 does not belong to comment 11111"
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

• The attachment must belong to the named comment. Otherwise 404. Without that check the endpoint would allow enumerating the account's attachments.
• The address is never returned. The download address contains an authorization code, so the endpoint returns bytes only.
• The urlDownload field from the comment response does not work directly. That address points at a Disk page rather than at REST and cannot be authorized with a key: requesting it redirects to the sign-in page. Download through this endpoint instead.
• The two paths grant different access. If the Disk object ID is refused on permissions and you have the attachment ID, try it: it computes access through the comment rather than through personal storage.
• The download address is verified, redirects included. It arrives in the Bitrix24 response, so the endpoint checks it against the account domain and sends no request to a foreign address — an authorization code would otherwise go there. The endpoint walks redirects itself, checking every hop: the chain is bounded in length and in time, and a redirect to an internal address is not followed and answers 502.
• A temporary failure is not disguised as 404. When Bitrix24 answers with a request limit, is unavailable, or the repeated-error guard trips, that is what comes back — 429 or 502/503 with a Retry-After header, not «the file does not belong to the comment». So a 404 here always means the reference itself is wrong: retrying it is pointless, whereas a 429/5xx should be retried with a delay.

See also

• Get a timeline comment
• Download an activity file
• Download a Disk file
• Timelines