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

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

Restore content from a version

POST /v1/files/:id/versions/:versionId/restore

Restores the file's content from the selected version. Later versions stay in the history, and the restored content is saved as a new version.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionFile ID. Get it: GET /v1/files?folderId=X
ParameterversionId (path) Typenumber Requiredyes DescriptionID of the version of this file whose content you want to restore. List: GET /v1/files/:id/versions

The request body is empty.

Examples

curl — personal key

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

curl — OAuth application

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

const { data, meta } = await res.json()
console.log('Content restored, new version:', meta.newVersionId)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/files/205/versions/410/restore', {
  method: 'POST',
  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 Typeobject DescriptionThe file after the restore — the same fields as in the GET /v1/files/:id response
Fielddata.globalContentVersion Typenumber DescriptionFile version counter. Increases by one after the restore
Fielddata.size Typenumber DescriptionSize of the restored content in bytes
Fielddata.updatedAt Typedatetime DescriptionDate and time of the restore (ISO 8601)
Fieldmeta.newVersionId Typenumber|null DescriptionID of the version this call created: after the restore, the platform takes the first version in the history. If another version of the file is saved in the same second, this field may hold that version's ID — the version from this call is the one whose contentGeneration equals data.globalContentVersion. null — the file history could not be read after the write

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 205,
    "name": "report.txt",
    "code": null,
    "storageId": 1,
    "type": "file",
    "folderId": 27,
    "deletedType": 0,
    "globalContentVersion": 4,
    "fileId": 371,
    "size": 10,
    "createdAt": "2026-10-15T17:09:58.000Z",
    "updatedAt": "2026-10-15T17:11:25.000Z",
    "deletedAt": null,
    "createdBy": 1,
    "updatedBy": 1,
    "deletedBy": null,
    "downloadUrl": "https://vibecode.bitrix24.com/v1/files/205/download",
    "detailUrl": "https://example.bitrix24.com/company/personal/user/1/disk/file/report.txt"
  },
  "meta": {
    "newVersionId": 412
  }
}

Error response example

404 — this file has no such version:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "File version not found."
  }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe version with this versionId does not exist, was removed from the history, or belongs to another file. The file stays unchanged
HTTP400 CodeINVALID_ID Descriptionid or versionId 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 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode. The address of the page where the mode is changed is in error.details.switchUrl
HTTP403 CodeDISK_HISTORY_UNAVAILABLE DescriptionVersion history is not available on the Bitrix24 account plan
HTTP422 CodeDISK_VERSION_REFUSED DescriptionBitrix24 did not confirm the restore. Read the file before retrying
HTTP502 CodeDISK_OUTCOME_UNKNOWN DescriptionThe outcome of the write is unknown, and the platform did not retry the request. Before retrying, read the file with GET /v1/files/:id and compare globalContentVersion with the previous value: if it grew, the restore went through

Full list of common API errors — Errors.

Known specifics

  • Each call adds a version. A restore does not roll the history back: the content of the selected version is saved as a new version on top of the latest one. This version is not merged into the latest one, even if the same user uploaded the latest version a minute ago. Calling again with the same versionId adds one more version. An upload by the same user within five minutes of the restore overwrites the version the restore created — see POST /v1/files/:id/versions.
  • The new version can push out the source version. The number of versions in the history is limited by the Bitrix24 account plan and settings. If the history is full, the restore deletes the oldest version — even if that is the version whose content was just restored. You can no longer restore from it.

See also