لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/files/versions.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

File version history

GET /v1/files/:id/versions

Returns the version history of a file on Bitrix24 Drive, newest versions first. Any version from the list can be read, downloaded, or restored by its ID.

Parameters

Parameter Type Required Default Description
Parameterid (path) Typenumber Requiredyes Default— DescriptionFile ID. Get it: GET /v1/files?folderId=X
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionNumber of versions to return, from 1 to 50
Parameteroffset (query) Typenumber Requiredno Default0 DescriptionNumber of versions to skip from the start of the history
Parameterfilter (query) Typeobject Requiredno Default— DescriptionFiltering by the id, size, name, createdAt, createdBy fields.
Filtering syntax. Example: ?filter[size][$gte]=1024

Pagination: one call returns at most 50 versions. To get the next page, repeat the request with offset set to meta.nextOffset from the previous response. When meta.hasMore is false, the whole history has been read.

Examples

curl — personal key

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

curl — OAuth application

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

const { data, meta } = await res.json()
for (const version of data) {
  console.log(version.id, version.createdAt, version.size, 'bytes')
}
console.log('More versions available:', meta.hasMore)

JavaScript — OAuth application

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

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionFile versions, newest first
Fielddata[].id Typenumber DescriptionVersion ID. Used by GET /v1/files/:id/versions/:versionId
Fielddata[].fileId Typenumber DescriptionID of the file the version belongs to
Fielddata[].size Typenumber DescriptionSize of the version content in bytes
Fielddata[].name Typestring DescriptionFile name at the moment the version entered the history. Renaming the file does not change it
Fielddata[].contentGeneration Typenumber DescriptionThe file's globalContentVersion value at the moment the version was saved
Fielddata[].createdAt Typedatetime|null DescriptionDate and time the version was saved (ISO 8601)
Fielddata[].createdBy Typenumber DescriptionID of the version author. List: GET /v1/users
Fielddata[].downloadUrl Typestring DescriptionVersion download path without the domain — GET /v1/files/:id/versions/:versionId/download. Send the X-Api-Key header when you follow it
Fieldmeta.total Typenumber|null DescriptionNumber of versions in the history that match the request
Fieldmeta.limit Typenumber DescriptionPage size from the request
Fieldmeta.offset Typenumber DescriptionOffset from the request
Fieldmeta.hasMore Typeboolean DescriptionWhether there are versions beyond this page
Fieldmeta.nextOffset Typenumber|null Descriptionoffset for the next page. null means there is no next page

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 412,
      "fileId": 205,
      "size": 10,
      "name": "report.txt",
      "contentGeneration": 4,
      "createdAt": "2026-10-15T17:11:25.000Z",
      "createdBy": 1,
      "downloadUrl": "/v1/files/205/versions/412/download"
    },
    {
      "id": 410,
      "fileId": 205,
      "size": 10,
      "name": "report.txt",
      "contentGeneration": 3,
      "createdAt": "2026-10-15T17:10:00.000Z",
      "createdBy": 1,
      "downloadUrl": "/v1/files/205/versions/410/download"
    }
  ],
  "meta": {
    "total": 2,
    "limit": 10,
    "offset": 0,
    "hasMore": false,
    "nextOffset": null
  }
}

Error response example

400 — a filter on a field outside the list:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Use limit 1..50, a non-negative offset and an object filter over id, size, name, createdAt or createdBy."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionlimit is outside the 1–50 range, offset is below zero, the filter uses a field outside the list, or filter is not passed as an object
HTTP400 CodeINVALID_PARAMS DescriptionThe filter condition key could not be parsed: the = sign inside the brackets is not encoded. Send the filter[>=size] key as filter%5B%3E%3Dsize%5D
HTTP400 CodeINVALID_ID Descriptionid is not a positive integer
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionBitrix24 access tokens are unavailable
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the disk scope
HTTP403 CodeDISK_HISTORY_UNAVAILABLE DescriptionVersion history is not available on the Bitrix24 account plan
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo file with this id exists, or the key cannot access it
HTTP422 CodeDISK_VERSION_REFUSED DescriptionBitrix24 did not return the file history
HTTP502 CodeDISK_READ_UNAVAILABLE DescriptionBitrix24 returned versions of a different file in the history; the response was discarded

Full list of common API errors — Errors.

Known specifics

  • The first version appears when the file is created. A freshly uploaded file already has one version in its history, holding the original content.
  • An upload does not always add a version. If the same user changed the file less than five minutes ago, the new content overwrites the latest version: its id stays the same, while size, contentGeneration, and createdAt are updated. The previous content of that version is lost from the history, so there can be fewer versions than uploads. Details — POST /v1/files/:id/versions.
  • Versions are ordered by createdAt with one-second precision. Versions saved within the same second may not appear in the order they were saved. contentGeneration gives the exact order: a version saved later has a higher value.
  • History is limited. How many versions are kept and for how long depends on the plan and settings of the Bitrix24 account. When a new version exceeds the limit, the oldest version is removed from the history.

See also