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

Получить возможности Диска

GET /v1/disk/capabilities

Сообщает, какие операции агента Диска доступны этому ключу на портале: поиск, синхронизация и сохранение файлов. Вызывайте его первым, до поиска, загрузки и синхронизации.

Параметры

Параметров нет. Тело запроса не передаётся.

Примеры

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

Terminal 
curl https://vibecode.bitrix24.tech/v1/disk/capabilities \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl https://vibecode.bitrix24.tech/v1/disk/capabilities \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/disk/capabilities', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
if (!data.sync.available) {
  console.log('Синхронизация недоступна на этом портале:', data.reason)
}
console.log('Поиск:', data.search.available, 'Загрузка:', data.save.create)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/disk/capabilities', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Поиск:', data.search.available, 'Синхронизация:', data.sync.available)

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном ответе
Полеdata.contractVersion Типnumber ОписаниеВерсия контракта агента Диска. Сейчас всегда 1
Полеdata.identity.scopeRef Типstring ОписаниеНепрозрачный идентификатор привязки: портал, пользователь Битрикс24 и ключ или приложение, через которое идёт вызов. Вычисляется сервером, из запроса не берётся
Полеdata.identity.portalId Типstring ОписаниеID портала на платформе Вайбкод
Полеdata.identity.nativeUserId Типstring ОписаниеID пользователя Битрикс24, от имени которого выполняются вызовы. Список сотрудников: GET /v1/users
Полеdata.identity.accountGeneration Типstring ОписаниеПоколение привязки. Растёт, когда меняются учётные данные привязки. После роста выданные раньше курсоры поиска и дескрипторы синхронизации не принимаются
Полеdata.search.available Типboolean ОписаниеДоступен ли поиск по Диску на портале
Полеdata.search.filters Типstring[] ОписаниеПоля фильтра поиска: storageId, folderId, fileType
Полеdata.search.types Типstring[] ОписаниеЗначения поля type поиска: file, folder, all
Полеdata.search.queryMin Типnumber ОписаниеМинимальная длина поисковой строки, 3
Полеdata.search.queryMax Типnumber ОписаниеМаксимальная длина поисковой строки, 255
Полеdata.sync.available Типboolean ОписаниеДоступна ли синхронизация. При false объект sync содержит только три поля: available, statusAvailable, retryAvailable
Полеdata.sync.statusAvailable Типboolean ОписаниеДоступно ли состояние синхронизации. Равно data.sync.available
Полеdata.sync.retryAvailable Типboolean ОписаниеДоступен ли повторный запуск синхронизации. Равно data.sync.available
Полеdata.sync.schemaVersion Типnumber ОписаниеТолько при available: true. Версия схемы синхронизации портала: 1 или 2
Полеdata.sync.cardSections Типobject ОписаниеТолько при available: true. Какие разделы карточки объекта портал отдаёт: metadata, location, access, relations — по признаку true или false на каждый
Полеdata.sync.changeTypes Типstring[] ОписаниеТолько при available: true. Типы изменений в журнале: update, tombstone, accessChanged, indexUpdated
Полеdata.sync.limits.pageSizeMax Типnumber ОписаниеТолько при available: true. Максимум объектов на странице синхронизации
Полеdata.sync.limits.pageSizeMaxHeavy Типnumber ОписаниеТолько при available: true. Максимум объектов на странице, когда запрошены разделы location, access или relations
Полеdata.sync.limits.checkBatchMax Типnumber ОписаниеТолько при available: true. Максимум объектов в сверке видимости внутри сеанса синхронизации, когда запрошен только раздел metadata, равен pageSizeMax. С разделами location, access или relations, в том числе по умолчанию, действует pageSizeMaxHeavy. Проверка видимости по списку objectIds вне синхронизации принимает от 1 до 50 ID при любом значении этого поля. Может отсутствовать
Полеdata.sync.retention.journalRetentionDays Типnumber ОписаниеТолько при available: true. Сколько дней портал хранит журнал изменений
Полеdata.sync.retention.interactionWindowDays Типnumber ОписаниеТолько при available: true. Глубина истории работы пользователя с файлами в днях
Полеdata.sync.retention.safeWindowSeconds Типnumber ОписаниеТолько при available: true. Окно согласованности журнала изменений в секундах по данным портала
Полеdata.sync.pollBounds.minSeconds Типnumber ОписаниеТолько при available: true. Минимальный интервал опроса изменений в секундах
Полеdata.sync.pollBounds.recommendedSeconds Типnumber ОписаниеТолько при available: true. Рекомендованный интервал опроса в секундах
Полеdata.sync.pollBounds.maxSeconds Типnumber ОписаниеТолько при available: true. Максимальный интервал опроса в секундах
Полеdata.sync.executionBudgetMs Типnumber ОписаниеТолько при available: true. Сколько миллисекунд отводится одной попытке синхронизации. Значение задаёт платформа, запросом его не изменить
Полеdata.save.create Типboolean ОписаниеМожно ли загрузить новый файл
Полеdata.save.version Типboolean ОписаниеМожно ли загрузить новую версию существующего файла
Полеdata.save.reserveAvailable Типboolean ОписаниеМожно ли зарезервировать загрузку. true, если доступно create или version
Полеdata.save.maxBytes Типnumber ОписаниеМаксимальный размер загружаемого файла в байтах — 26214400, 25 МиБ
Полеdata.save.atomicConcurrency Типboolean ОписаниеВсегда false: проверка версии файла перед загрузкой новой версии не атомарна, и параллельное изменение между проверкой и записью не исключено
Полеdata.reason Типstring ОписаниеПричина, по которой синхронизация или поиск недоступны: DISK_UNSUPPORTED — портал не поддерживает возможность, DISK_ACCESS_DENIED — Битрикс24 отказал пользователю в доступе к синхронизации. Отсутствует, когда доступно всё

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

Поиск и сохранение доступны, синхронизация недоступна на этом портале:

JSON 
{
  "success": true,
  "data": {
    "contractVersion": 1,
    "identity": {
      "scopeRef": "7073c6856e1b4dde1e1dca88006d87684a3219c7f7becb059abba0989f257e0b",
      "portalId": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
      "nativeUserId": "1",
      "accountGeneration": "1"
    },
    "search": {
      "available": true,
      "filters": ["storageId", "folderId", "fileType"],
      "types": ["file", "folder", "all"],
      "queryMin": 3,
      "queryMax": 255
    },
    "sync": {
      "available": false,
      "statusAvailable": false,
      "retryAvailable": false
    },
    "save": {
      "create": true,
      "version": true,
      "reserveAvailable": true,
      "maxBytes": 26214400,
      "atomicConcurrency": false
    },
    "reason": "DISK_UNSUPPORTED"
  }
}

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

401 — не передан заголовок X-Api-Key:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Конверт ошибок самого агента Диска — в разделе Коды ошибок.

Ошибки

HTTP Код Описание
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа нет настроенной авторизации на портале Битрикс24
HTTP401 КодDISK_AUTH_UNAVAILABLE ОписаниеНе удалось подтвердить пользователя Битрикс24: вебхук ключа не совпадает с порталом или пользователем, ключ OAuth-приложения передан без Authorization: Bearer, токен сессии принадлежит другому приложению или порталу, либо токен Битрикс24 истёк или отозван
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан
HTTP401 КодTOKEN_REFRESH_FAILED ОписаниеНе удалось обновить авторизацию портала для ключа. Повтор не поможет, пока ключ не авторизован заново
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа disk
HTTP403 КодDISK_ACCESS_DENIED ОписаниеБитрикс24 отказал пользователю в доступе при чтении возможностей
HTTP501 КодDISK_UNSUPPORTED ОписаниеПортал не отдал список доступных методов в ожидаемом виде
HTTP502 КодDISK_READ_UNAVAILABLE ОписаниеЧтение не удалось по причине, которой нет среди остальных кодов. Повторите запрос позже
HTTP503 КодQUERY_LIMIT_EXCEEDED ОписаниеПортал ограничил частоту запросов
HTTP503 КодBITRIX_TIMEOUT ОписаниеПортал не ответил вовремя
HTTP503 КодQUEUE_OVERFLOW, QUEUE_TIMEOUT ОписаниеОчередь вызовов портала переполнена. Заголовок Retry-After называет паузу перед повтором
HTTP503 Кодuser_self_deletion_pending ОписаниеВладелец ключа запросил удаление своей учётной записи — обращения к Диску остановлены
HTTP503 КодRATE_LIMITED ОписаниеПортал ответил HTTP 429. Паузу перед повтором называет заголовок Retry-After
HTTP503 КодERROR_LOOP_DETECTED ОписаниеПовторяющиеся ошибки этого ключа на этом методе временно остановили вызовы. Паузу называет заголовок Retry-After

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

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

Недоступная синхронизация не мешает остальному. При sync.available: false поиск, загрузка файлов и проверка видимости по списку objectIds работают.

Ключ в режиме «только чтение». У ключа с режимом доступа «только чтение» поля save.create, save.version и save.reserveAvailable равны false на любом портале, а загрузка отвечает 403 WRITE_BLOCKED_READONLY. Поиск и чтение возможностей таким ключом работают.

Признаки описывают портал, а не гарантию. Ответ собирается из списка методов, которые портал отдаёт этому пользователю, поэтому после обновления портала или смены прав признаки меняются без изменений на стороне приложения. Лимиты и сроки хранения в data.sync — наблюдаемые значения портала, а не обещание полноты выдачи.

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