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
Parameterid (path) Typenumber Requiredyes DescriptionFile ID. Get it: GET /v1/files?folderId=X
Parameterinclude (query) Typestring Requiredno DescriptionLoad 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
Fieldsuccess Typeboolean Read-only DescriptionAlways true on success
Fielddata.id Typenumber Read-only✓ DescriptionFile identifier
Fielddata.name Typestring Read-only DescriptionFile name
Fielddata.code Typestring|null Read-only DescriptionSymbolic file code
Fielddata.storageId Typenumber Read-only✓ DescriptionStorage ID. List: GET /v1/storages
Fielddata.type Typestring Read-only✓ DescriptionObject type: always "file"
Fielddata.folderId Typenumber Read-only DescriptionParent folder ID. List: GET /v1/folders
Fielddata.deletedType Typenumber Read-only✓ DescriptionDeletion status: 0 — active, 3 — in trash, 4 — deleted together with the folder
Fielddata.globalContentVersion Typenumber Read-only✓ DescriptionFile version counter
Fielddata.fileId Typenumber Read-only✓ DescriptionInternal file identifier in Bitrix24
Fielddata.size Typenumber Read-only✓ DescriptionFile size in bytes
Fielddata.createdBy Typenumber Read-only✓ DescriptionCreator user ID. List: GET /v1/users
Fielddata.updatedBy Typenumber Read-only✓ DescriptionID of the last editor. List: GET /v1/users
Fielddata.deletedBy Typenumber|null Read-only✓ DescriptionID of the user who deleted the file; null — file not deleted
Fielddata.createdAt Typedatetime Read-only✓ DescriptionCreation date and time (ISO 8601)
Fielddata.updatedAt Typedatetime Read-only✓ DescriptionDate and time of the last change (ISO 8601)
Fielddata.deletedAt Typedatetime|null Read-only✓ DescriptionDate and time the file was moved to trash; null — file not deleted
Fielddata.downloadUrl Typestring Read-only✓ DescriptionVibecode API address that downloads the file, GET /v1/files/:id/download. Send the X-Api-Key header when you follow it
Fielddata.detailUrl Typestring Read-only✓ DescriptionLink to the file in the Bitrix24 interface
Fielddata.contentProvider Typestring Read-only✓ DescriptionContent 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
HTTP404 CodeENTITY_NOT_FOUND DescriptionFile with the given ID does not exist
HTTP400 CodeINVALID_INCLUDE DescriptionThe include value is not supported. The available value is folder
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the disk scope
HTTP401 CodeTOKEN_MISSING DescriptionKey has no configured authorization tokens
HTTP401 CodeINVALID_API_KEY DescriptionThe 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