Для AI-агентов: markdown этой страницы — /docs-content/entities/files/version-restore.md индекс документации — /llms.txt
Восстановление содержимого из версии
POST /v1/files/:id/versions/:versionId/restore
Возвращает файлу содержимое выбранной версии. Более поздние версии остаются в истории, а восстановленное содержимое сохраняется ещё одной версией.
Параметры
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
Параметрid (path) |
Типnumber | Обяз.да | ОписаниеID файла. Получить: GET /v1/files?folderId=X |
ПараметрversionId (path) |
Типnumber | Обяз.да | ОписаниеID версии этого файла, содержимое которой нужно вернуть. Список: GET /v1/files/:id/versions |
Тело запроса пустое.
Примеры
curl — личный ключ
curl -X POST "https://vibecode.bitrix24.tech/v1/files/205/versions/410/restore" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl -X POST "https://vibecode.bitrix24.tech/v1/files/205/versions/410/restore" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/files/205/versions/410/restore', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
},
})
const { data, meta } = await res.json()
console.log('Содержимое восстановлено, новая версия:', meta.newVersionId)
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/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()
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata |
Типobject | ОписаниеФайл после восстановления — те же поля, что в ответе GET /v1/files/:id |
Полеdata.globalContentVersion |
Типnumber | ОписаниеСчётчик версий файла. После восстановления вырастает на единицу |
Полеdata.size |
Типnumber | ОписаниеРазмер восстановленного содержимого в байтах |
Полеdata.updatedAt |
Типdatetime | ОписаниеДата и время восстановления (ISO 8601) |
Полеmeta.newVersionId |
Типnumber|null | ОписаниеID версии, которую создал этот вызов: платформа берёт первую версию истории после восстановления. Если другая версия файла сохранена в ту же секунду, здесь может оказаться её ID — версию этого вызова отличает contentGeneration, равный data.globalContentVersion. null — историю файла после записи прочитать не удалось |
Пример ответа
{
"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.tech/v1/files/205/download",
"detailUrl": "https://example.bitrix24.ru/company/personal/user/1/disk/file/report.txt"
},
"meta": {
"newVersionId": 412
}
}
Пример ответа при ошибке
404 — версии нет у этого файла:
{
"success": false,
"error": {
"code": "ENTITY_NOT_FOUND",
"message": "File version not found."
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP404 | КодENTITY_NOT_FOUND |
ОписаниеВерсии с таким versionId нет, она удалена из истории или принадлежит другому файлу. Файл не меняется |
| HTTP400 | КодINVALID_ID |
Описаниеid или versionId — не целое положительное число |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP401 | КодTOKEN_MISSING |
ОписаниеТокены доступа к порталу Битрикс24 недоступны |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеКлючу не хватает скоупа disk |
| HTTP403 | КодWRITE_BLOCKED_READONLY_KEY |
ОписаниеКлюч в режиме «Только чтение». Где переключить режим — в error.details.switchUrl |
| HTTP403 | КодDISK_HISTORY_UNAVAILABLE |
ОписаниеИстория версий недоступна на тарифе портала |
| HTTP422 | КодDISK_VERSION_REFUSED |
ОписаниеБитрикс24 не подтвердил восстановление. Перед повтором прочитайте файл |
| HTTP502 | КодDISK_OUTCOME_UNKNOWN |
ОписаниеИсход записи неизвестен, платформа запрос не повторяла. Перед повтором прочитайте файл GET /v1/files/:id и сравните globalContentVersion с прежним значением: вырос — восстановление прошло |
Полный список общих ошибок API — Ошибки.
Известные особенности
- Каждый вызов добавляет версию. Восстановление не откатывает историю назад: содержимое выбранной версии сохраняется новой версией поверх последней. Эта версия не склеивается с последней, даже если её минуту назад загрузил тот же пользователь. Повторный вызов с тем же
versionIdдобавит ещё одну версию. Загрузка того же пользователя в течение пяти минут после восстановления перезапишет созданную им версию — см.POST /v1/files/:id/versions. - Новая версия может вытеснить версию-источник. Число версий в истории ограничено тарифом и настройками портала Битрикс24. Если история заполнена, восстановление удаляет самую старую версию — в том числе ту, из которой только что взято содержимое. Повторно восстановить из неё уже нельзя.