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

Список операций загрузки

GET /v1/disk/uploads

Возвращает операции загрузки файлов на Диск Битрикс24, созданные в контексте ключа: незавершённые или недавно завершённые. Помогает восстановить потерянный идентификатор операции и найти записи с неизвестным результатом.

Параметры

Параметр Тип Обяз. По умолч. Описание
Параметрfilter (query) Типstring Обяз.да По умолч.— Описаниеpending — операции в работе: phase равен prepared или submitting, либо application равен unknown. recent — завершённые операции с application равным applied или not_applied, созданные не раньше 90 дней назад
Параметрlimit (query) Типnumber Обяз.нет По умолч.50 ОписаниеЗаписей на страницу, целое от 1 до 100
Параметрcursor (query) Типstring Обяз.нет По умолч.— ОписаниеЗначение nextCursor из прошлого ответа. В первом запросе не передаётся

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

Записи идут от старых к новым. Пока в ответе hasMore: true, запрашивайте следующую страницу с cursor, равным nextCursor, и тем же filter.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/disk/uploads?filter=recent&limit=2" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/disk/uploads?filter=recent&limit=2" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const items = []
let cursor
do {
  const params = new URLSearchParams({ filter: 'recent', limit: '2' })
  if (cursor) params.set('cursor', cursor)
  const res = await fetch(`https://vibecode.bitrix24.tech/v1/disk/uploads?${params}`, {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  })
  const { success, data, error } = await res.json()
  if (!success) throw new Error(error.code)
  items.push(...data.items)
  cursor = data.hasMore ? data.nextCursor : undefined
} while (cursor)

console.log(items.map(item => `${item.intentSummary.effectiveFilename}: ${item.application}`))

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/disk/uploads?filter=recent&limit=2', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном чтении
Полеdata.items Типarray ОписаниеОперации страницы. Пустой массив, если под filter ничего не попало
Полеdata.items[].operationId Типstring ОписаниеИдентификатор операции. Подробности: GET /v1/disk/uploads/:operationId
Полеdata.items[].phase Типstring ОписаниеЭтап операции: prepared, submitting или settled
Полеdata.items[].application Типstring ОписаниеРезультат записи: applied, not_applied или unknown
Полеdata.items[].verification Типstring ОписаниеРезультат последней сверки с текущим файлом: matched, superseded или unavailable
Полеdata.items[].intentSummary.mode Типstring ОписаниеРежим из резерва: create или version
Полеdata.items[].intentSummary.targetId Типstring ОписаниеID папки при create или ID файла при version
Полеdata.items[].intentSummary.effectiveFilename Типstring ОписаниеИмя файла из резерва
Полеdata.items[].intentSummary.contentSize Типstring ОписаниеРазмер файла в байтах
Полеdata.items[].intentSummary.intentHash Типstring ОписаниеintentHash операции — нужен для POST /v1/disk/uploads
Полеdata.items[].priorOperationId Типstring ОписаниеПрошлая операция, от которой зарезервирована эта. Приходит у операций с lineage.kind равным successor или retry
Полеdata.hasMore Типboolean Описаниеtrue, если есть следующая страница
Полеdata.nextCursor Типstring ОписаниеКурсор следующей страницы. Приходит при hasMore: true

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

Первая страница filter=recent&limit=2:

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "operationId": "zSTFAm53NusAWc94THbRTOfbe-OIoHwlDIJTQ6E2Z7o",
        "phase": "settled",
        "application": "applied",
        "verification": "matched",
        "intentSummary": {
          "mode": "create",
          "targetId": "1",
          "effectiveFilename": "vibe-disk-docs-check.txt",
          "contentSize": "27",
          "intentHash": "3e55280c097b92721a6c58da586363f1169e7dec15990fe3fa7f44f543b8331a"
        }
      },
      {
        "operationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU",
        "phase": "settled",
        "application": "applied",
        "verification": "superseded",
        "intentSummary": {
          "mode": "create",
          "targetId": "1",
          "effectiveFilename": "vibe-disk-docs-check-2.txt",
          "contentSize": "29",
          "intentHash": "3e10ae1152a0e4b4e89d3b312bfacafc1f3e0cf22d8a5eae3e231fa8bc274498"
        }
      }
    ],
    "hasMore": true,
    "nextCursor": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU"
  }
}

Следующая страница с cursor — операция новой версии файла несёт priorOperationId:

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "operationId": "dlbBsp01PqU2VBXjA8VigHPCXE_T01lBJgCp_gNfypY",
        "phase": "settled",
        "application": "applied",
        "verification": "matched",
        "intentSummary": {
          "mode": "version",
          "targetId": "10901",
          "effectiveFilename": "vibe-disk-docs-check-2.txt",
          "contentSize": "32",
          "intentHash": "07b6444b0eb202f1c7c11b50d5617a86790e80e6bb9d487c0e90776d1a0f0a75"
        },
        "priorOperationId": "xykPPgOlNBiKMTlAV3SfBoGJhG6Hi6AX57Ede4rAFoU"
      },
      {
        "operationId": "QSCV6zB59O811A1pNO9HfekQdMvGifw4_E9-y1OZs48",
        "phase": "settled",
        "application": "not_applied",
        "verification": "unavailable",
        "intentSummary": {
          "mode": "version",
          "targetId": "10901",
          "effectiveFilename": "vibe-disk-docs-check-2.txt",
          "contentSize": "16",
          "intentHash": "76d560e3bf0b2bfabb85152474db537ebb08225558e37537f9ff86fbafebe0ad"
        }
      }
    ],
    "hasMore": false
  }
}

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

400 — limit больше 100:

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

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеНе передан filter или он не pending и не recent, limit не целое от 1 до 100, cursor длиннее 512 символов, передан неизвестный параметр
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 КодDISK_ACCESS_DENIED ОписаниеБитрикс24 отказал в доступе при проверке пользователя
HTTP409 КодDISK_OPERATION_CONFLICT Описаниеcursor не является идентификатором операции в контексте ключа
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 — Ошибки.

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

  • verification в списке не пересчитывается. Поле несёт результат последней сверки. Чтобы сверить операцию с текущим файлом, запросите GET /v1/disk/uploads/:operationId.

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