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

Get file

GET /v1/files/:id

Returns a file by ID with all fields, including the download link and the direct URL in the Bitrix24 interface.

Parameters

Parameter Type Required Description
id (path) number yes File ID. Get it: GET /v1/files?folderId=X
include (query) string no Load a related object. The available value is folder. The result is returned in the _included block

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/files/205" \
  -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/files/205', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

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

const { success, data } = await res.json()

Response fields

Field Type Read-only Description
success boolean Always true on success
data.id number ✓ File identifier
data.name string File name
data.code string|null Symbolic file code
data.storageId number ✓ Storage ID. List: GET /v1/storages
data.type string ✓ Object type: always "file"
data.folderId number Parent folder ID. List: GET /v1/folders
data.deletedType number ✓ Deletion status: 0 — active, 3 — in trash, 4 — deleted together with the folder
data.globalContentVersion number ✓ File version counter
data.fileId number ✓ Internal file identifier in Bitrix24
data.size number ✓ File size in bytes
data.createdBy number ✓ Creator user ID. List: GET /v1/users
data.updatedBy number ✓ ID of the last editor. List: GET /v1/users
data.deletedBy number|null ✓ ID of the user who deleted the file; null — file not deleted
data.createdAt datetime ✓ Creation date and time (ISO 8601)
data.updatedAt datetime ✓ Date and time of the last change (ISO 8601)
data.deletedAt datetime|null ✓ Date and time the file was moved to trash; null — file not deleted
data.downloadUrl string ✓ Vibecode API address that downloads the file, GET /v1/files/:id/download. Send the X-Api-Key header when you follow it
data.detailUrl string ✓ Link to the file in the Bitrix24 interface
data.contentProvider string ✓ Content provider (may be absent)

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 205,
    "name": "project-report.pdf",
    "code": null,
    "storageId": 1,
    "type": "file",
    "folderId": 27,
    "deletedType": 0,
    "globalContentVersion": 1,
    "fileId": 363,
    "size": 31232,
    "createdBy": 1,
    "updatedBy": 1,
    "deletedBy": null,
    "createdAt": "2020-05-15T09:29:09.000Z",
    "updatedAt": "2020-05-15T09:29:09.000Z",
    "deletedAt": null,
    "downloadUrl": "https://vibecode.bitrix24.com/v1/files/205/download",
    "detailUrl": "https://example.bitrix24.com/disk/file/project-report.pdf/"
  }
}

With include=folder, the response adds an _included block with the parent folder. The example shows the main file fields:

JSON 
{
  "success": true,
  "data": {
    "id": 205,
    "name": "project-report.pdf",
    "storageId": 1,
    "type": "file",
    "folderId": 27,
    "_included": {
      "folder": {
        "id": 27,
        "name": "Uploaded files",
        "code": "FOR_UPLOADED_FILES",
        "storageId": 1,
        "type": "folder",
        "parentId": 1,
        "createdBy": 1,
        "updatedBy": 1,
        "deletedBy": null
      }
    }
  }
}

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
404 ENTITY_NOT_FOUND File with the given ID does not exist
400 INVALID_INCLUDE The include value is not supported. The available value is folder
403 SCOPE_DENIED API key lacks the disk scope
401 TOKEN_MISSING Key has no configured authorization tokens
401 INVALID_API_KEY The key is not recognized — no such key exists on the platform

Full list of common API errors — Error codes.

Known specifics

downloadUrl points to GET /v1/files/:id/download: the address is permanent and carries no authorization token. Like any API call, following it requires the X-Api-Key header of a key with the disk or crm scope.

The method returns only objects of type "file". To get folder data, use GET /v1/folders/:id.

See also