Для AI-агентов: markdown этой страницы — /docs-content/disk/uploads-reserve.md индекс документации — /llms.txt

Зарезервировать загрузку файла на Диск

POST /v1/disk/uploads/reserve

Регистрирует будущую загрузку файла на Диск Битрикс24 — первый шаг записи, содержимое файла передаётся следующим вызовом по идентификатору операции.

Тело плоское, без обёртки fields.

Поля запроса (body)

Поле Тип Обяз. Описание
ПолеreserveRequestId Типstring Обяз.да ОписаниеВаш идентификатор запроса резерва, от 1 до 512 символов. Повтор с тем же значением и тем же телом возвращает уже созданную операцию
Полеintent Типarray Обяз.да ОписаниеНамерение загрузки — массив ровно из восьми элементов в порядке строк ниже. Лишний, пропущенный или переставленный элемент даёт 400 INVALID_PARAMS
Полеintent[0] Типnumber Обяз.да ОписаниеВерсия формата, всегда 1
Полеintent[1] Типstring Обяз.да ОписаниеРежим: create — новый файл в папке, version — новая версия существующего файла
Полеintent[2] Типstring Обяз.да ОписаниеПри create — ID папки, в которую ложится файл. Список: GET /v1/folders, корневая папка хранилища — поле rootFolderId в GET /v1/storages/:id. При version — ID файла objectId из POST /v1/disk/search или fileId из ответа прошлой загрузки. Десятичное число строкой без ведущих нулей
Полеintent[3] Типstring Обяз.да ОписаниеSHA-256 исходных байтов файла — 64 символа в нижнем регистре
Полеintent[4] Типstring Обяз.да ОписаниеРазмер файла в байтах, десятичное число строкой. Не больше 26214400 (25 МиБ)
Полеintent[5] Типnull | array Обяз.да ОписаниеПри create — null. При version — ожидаемое текущее состояние файла: массив из трёх строк [contentFileId, contentGeneration, size]. Значения — из карточки файла в POST /v1/disk/search или из ответа прошлой загрузки
Полеintent[6] Типstring Обяз.да ОписаниеИмя файла на Диске. Не пустое и не из одних пробелов, без управляющих символов и без < > : " | ? * \ /
Полеintent[7] Типstring Обяз.да ОписаниеПолитика записи: createFail для режима create, versionPreflightNoCAS для режима version. Другая пара режима и политики даёт 400 INVALID_PARAMS
Полеlineage Типobject Обяз.да ОписаниеСвязь операции с прошлыми
Полеlineage.kind Типstring Обяз.да Описаниеinitial — первая загрузка с этим intent. successor — следующая версия файла после успешной операции: прошлая операция в состоянии application: "applied", новый intent в режиме version, intent[2] равен fileId прошлой операции. retry — повтор того же intent после операции, завершённой с application: "not_applied"
Полеlineage.priorOperationId Типstring Обяз.нет ОписаниеОбязателен при kind: "successor" и kind: "retry". operationId прошлой операции. Список операций: GET /v1/disk/uploads. При kind: "initial" поле не передаётся

Других полей тело не принимает: неизвестное поле даёт 400 INVALID_PARAMS.

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/disk/uploads/reserve \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reserveRequestId": "docs-check-reserve-2",
    "intent": [1, "create", "1", "6be5cdb4cdbf136301c74adf2fd5a380fe5ceda1e998ce4b62f01cf7d20589a5", "29", null, "vibe-disk-docs-check-2.txt", "createFail"],
    "lineage": { "kind": "initial" }
  }'

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/disk/uploads/reserve \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reserveRequestId": "docs-check-reserve-2",
    "intent": [1, "create", "1", "6be5cdb4cdbf136301c74adf2fd5a380fe5ceda1e998ce4b62f01cf7d20589a5", "29", null, "vibe-disk-docs-check-2.txt", "createFail"],
    "lineage": { "kind": "initial" }
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/disk/uploads/reserve', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    reserveRequestId: 'docs-check-reserve-2',
    intent: [1, 'create', '1', '6be5cdb4cdbf136301c74adf2fd5a380fe5ceda1e998ce4b62f01cf7d20589a5', '29', null, 'vibe-disk-docs-check-2.txt', 'createFail'],
    lineage: { kind: 'initial' },
  }),
})

const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
// Сохраните operationId и intentHash до загрузки содержимого
console.log(data.operationId, data.intentHash)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/disk/uploads/reserve', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    reserveRequestId: 'docs-check-reserve-2',
    intent: [1, 'create', '1', '6be5cdb4cdbf136301c74adf2fd5a380fe5ceda1e998ce4b62f01cf7d20589a5', '29', null, 'vibe-disk-docs-check-2.txt', 'createFail'],
    lineage: { kind: 'initial' },
  }),
})

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

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном резерве
Полеdata.operationId Типstring ОписаниеИдентификатор операции. Передаётся в POST /v1/disk/uploads и GET /v1/disk/uploads/:operationId
Полеdata.phase Типstring ОписаниеЭтап операции: prepared — зарезервирована, submitting — запись передана в Битрикс24, settled — завершена
Полеdata.application Типstring ОписаниеРезультат записи: applied — файл записан, not_applied — запись не выполнялась, unknown — результат неизвестен
Полеdata.verification Типstring ОписаниеСверка с текущим состоянием файла: matched — файл совпадает с записанным, superseded — файл с тех пор изменился, unavailable — сверка не выполнена
Полеdata.intentHash Типstring ОписаниеSHA-256 от intent, записанного компактным JSON в UTF-8. Передаётся в POST /v1/disk/uploads
Полеdata.reservationExpiresAt Типstring ОписаниеДата и время в ISO 8601, до которых операция принимает содержимое. Наступает через 30 дней после создания операции
Полеdata.recovered Типboolean Описаниеtrue — вернулась операция, созданная раньше, false — создана новая

Пример ответа

Новый резерв:

JSON 
{
  "success": true,
  "data": {
    "operationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU",
    "phase": "prepared",
    "application": "not_applied",
    "verification": "unavailable",
    "intentHash": "3e10ae1152a0e4b4e89d3b312bfacafc1f3e0cf22d8a5eae3e231fa8bc274498",
    "reservationExpiresAt": "2026-11-22T10:10:36.591Z",
    "recovered": false
  }
}

Повтор того же запроса после загрузки файла — та же операция в текущем состоянии:

JSON 
{
  "success": true,
  "data": {
    "operationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU",
    "phase": "settled",
    "application": "applied",
    "verification": "matched",
    "intentHash": "3e10ae1152a0e4b4e89d3b312bfacafc1f3e0cf22d8a5eae3e231fa8bc274498",
    "reservationExpiresAt": "2026-11-22T10:10:36.591Z",
    "recovered": true
  }
}

Пример ответа при ошибке

409 — тот же reserveRequestId пришёл с другим intent:

JSON 
{
  "success": false,
  "error": {
    "code": "DISK_OPERATION_CONFLICT",
    "message": "Disk request unavailable",
    "retrySafe": false
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеТело не прошло проверку: неверный состав intent, недопустимое имя файла, lineage без priorOperationId при successor или retry, неизвестное поле
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа нет подключения к Битрикс24
HTTP401 КодDISK_AUTH_UNAVAILABLE ОписаниеНе удалось подтвердить пользователя Битрикс24: ключ приложения передан без Authorization: Bearer, сессия не принадлежит приложению ключа или ключ не поддерживается агентом Диска
HTTP401 КодTOKEN_REFRESH_FAILED ОписаниеНе удалось обновить авторизацию портала для ключа. Повтор не поможет, пока ключ не авторизован заново
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа disk
HTTP403 КодWRITE_BLOCKED_READONLY ОписаниеКлюч в режиме «только чтение»
HTTP403 КодDISK_ACCESS_DENIED ОписаниеБитрикс24 отказал в доступе при проверке пользователя
HTTP409 КодDISK_OPERATION_CONFLICT ОписаниеreserveRequestId уже использован с другим intent или lineage. Либо у операции priorOperationId уже есть продолжение с другим intent или другим lineage.kind
HTTP409 КодDISK_PRIOR_REQUIRED ОписаниеОперация priorOperationId не найдена или ещё не завершена, либо не выполнено условие lineage.kind: для successor — прошлая запись не applied, режим нового intent не version или intent[2] не равен её fileId, для retry — прошлая запись не not_applied или её intent другой
HTTP409 КодDISK_OUTCOME_UNKNOWN ОписаниеРезультат операции priorOperationId неизвестен: application равен unknown. Продолжение и повтор от неё не принимаются
HTTP409 КодDISK_GENERATION_STALE ОписаниеПодключение ключа к Битрикс24 сменилось во время запроса. Повторите резерв
HTTP413 КодDISK_UPLOAD_TOO_LARGE ОписаниеРазмер intent[4] больше 26214400 байт
HTTP502 КодDISK_READ_UNAVAILABLE ОписаниеБитрикс24 вернул ошибку, которую Вайбкод не распознал
HTTP503 КодQUERY_LIMIT_EXCEEDED ОписаниеБитрикс24 ограничил частоту запросов. Повторите позже
HTTP503 КодBITRIX_TIMEOUT ОписаниеБитрикс24 не ответил вовремя
HTTP503 КодQUEUE_OVERFLOW, QUEUE_TIMEOUT ОписаниеОчередь вызовов портала переполнена. Заголовок Retry-After называет паузу перед повтором
HTTP503 КодRATE_LIMITED ОписаниеПортал ответил HTTP 429. Паузу перед повтором называет заголовок Retry-After
HTTP503 КодERROR_LOOP_DETECTED ОписаниеПовторяющиеся ошибки этого ключа на этом методе временно остановили вызовы. Паузу называет заголовок Retry-After
HTTP503 Кодuser_self_deletion_pending ОписаниеВладелец ключа запросил удаление своей учётной записи — обращения к Диску остановлены

Полный список общих ошибок API — Ошибки.

Известные особенности

  • Резерв не передаёт байты и не обращается к папке или файлу. Существование папки, права на запись и свободное имя проверяются только при загрузке содержимого в POST /v1/disk/uploads.
  • Одинаковый intent с lineage.kind: "initial" даёт одну операцию. Новый reserveRequestId с тем же intent возвращает уже существующую операцию с recovered: true, в том числе завершённую.
  • У операции одно продолжение. От одной прошлой операции принимается только одно продолжение successor или retry. Второй запрос с тем же intent и lineage.kind возвращает уже созданное продолжение.
  • Операции привязаны к контексту ключа. Резерв, загрузка и чтение операций работают в рамках одного портала, одного пользователя Битрикс24 и одного источника авторизации: входящего вебхука личного ключа или OAuth-приложения. Из другого контекста операция не видна.

Смотрите также