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
ParameterfileId (path) Typenumber Requiredyes DescriptionFile 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typestring DescriptionFile ID
Fielddata.name Typestring DescriptionFile name
Fielddata.size Typestring DescriptionFile size in bytes
Fielddata.type Typestring DescriptionObject type (file)
Fielddata.detailUrl Typestring DescriptionLink to the file page in Bitrix24
Fielddata.createdBy Typestring DescriptionID of the user who uploaded the file
Fielddata.createdAt Typestring DescriptionUpload date (ISO 8601)
Fielddata.updatedAt Typestring DescriptionLast modification date (ISO 8601)
Fielddata.downloadUrl Typestring DescriptionVibecode 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
HTTP400 CodeINVALID_PARAMS DescriptionfileId is not a positive integer — checked before the Bitrix24 call
HTTP404 CodeFILE_NOT_FOUND DescriptionA file with the specified fileId was not found
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned a NOT_FOUND error — the file does not exist or is not accessible
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 refused file access with ACCESS_DENIED
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 error while retrieving metadata
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks im, or a key in READONLY mode lacks disk. Checked before any Bitrix24 call
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured Bitrix24 tokens

Full list of common API errors — Errors.

See also