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

File metadata

GET /v1/chats/files/:fileId

Returns file metadata: name, size, type, and a link to the file page. An ordinary key requires im and receives downloadUrl, the Vibecode API download address; following it requires the disk or crm scope. A READONLY key additionally requires disk and receives no download link. The user must still have access to the file in Bitrix24. A numeric fileId alone does not establish that the file belongs to a chat the caller can access. Use the fileId from the POST /v1/chats/:chatId/files response.

To download file contents with a READONLY key, use the authenticated GET /v1/files/:fileId/download. Requires disk or crm; im alone is insufficient. Uploading a file to a chat still requires im.

Parameters

Parameter Type Required Description
fileId (path) number yes File ID. Get it: POST /v1/chats/:chatId/files → data.fileId

Examples

curl — personal key

Terminal 
curl https://vibecode.bitrix24.com/v1/chats/files/9265 \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/files/9265', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('File name:', data.name)

JavaScript — OAuth application

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

const { success, data } = await res.json()
console.log('File name:', data.name)

Response fields

Field Type Description
success boolean Always true on success
data.id string File ID
data.name string File name
data.size string File size in bytes
data.type string Object type (file)
data.detailUrl string Link to the file page in Bitrix24
data.createdBy string ID of the user who uploaded the file
data.createdAt string Upload date (ISO 8601)
data.updatedAt string Last modification date (ISO 8601)
data.downloadUrl string Vibecode API download address, GET /v1/files/:id/download, for an ordinary key; following it requires the disk or crm scope. Omitted for a READONLY key

Response example

JSON 
{
  "success": true,
  "data": {
    "id": "9265",
    "name": "report.pdf",
    "size": "24576",
    "type": "file",
    "detailUrl": "https://YOUR_PORTAL.bitrix24.com/file/chat1001/report.pdf",
    "createdBy": "1",
    "createdAt": "2026-06-05T13:48:24+00:00",
    "updatedAt": "2026-06-05T13:48:24+00:00"
  }
}

Error response example

404 — file not found:

JSON 
{
  "success": false,
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "File not found"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS fileId is not a positive integer — checked before the Bitrix24 call
404 FILE_NOT_FOUND A file with the specified fileId was not found
404 ENTITY_NOT_FOUND Bitrix24 returned a NOT_FOUND error — the file does not exist or is not accessible
403 BITRIX_ACCESS_DENIED Bitrix24 refused file access with ACCESS_DENIED
422 BITRIX_ERROR Bitrix24 error while retrieving metadata
403 SCOPE_DENIED The key lacks im, or a key in READONLY mode lacks disk. Checked before any Bitrix24 call
401 TOKEN_MISSING The key has no configured Bitrix24 tokens

Full list of common API errors — Errors.

See also