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

`GET /v1/disk/capabilities`

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

## Параметры

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

## Примеры

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

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

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

```bash
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`](/docs/entities/users/list) |
| `data.identity.accountGeneration` | string | Поколение привязки. Растёт, когда меняются учётные данные привязки. После роста выданные раньше курсоры поиска и дескрипторы синхронизации не принимаются |
| `data.search.available` | boolean | Доступен ли [поиск по Диску](/docs/disk/search) на портале |
| `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`. [Проверка видимости](/docs/disk/sync-check) по списку `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 | Можно ли [загрузить](/docs/disk/uploads) новый файл |
| `data.save.version` | boolean | Можно ли загрузить новую версию существующего файла |
| `data.save.reserveAvailable` | boolean | Можно ли [зарезервировать загрузку](/docs/disk/uploads-reserve). `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."
  }
}
```

Конверт ошибок самого агента Диска — в разделе [Коды ошибок](/docs/disk#коды-ошибок).

## Ошибки

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

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

**Недоступная синхронизация не мешает остальному.** При `sync.available: false` [поиск](/docs/disk/search), загрузка файлов и [проверка видимости](/docs/disk/sync-check) по списку `objectIds` работают.

**Ключ в режиме «только чтение».** У ключа с [режимом доступа](/docs/keys-auth/access-mode) «только чтение» поля `save.create`, `save.version` и `save.reserveAvailable` равны `false` на любом портале, а загрузка отвечает `403 WRITE_BLOCKED_READONLY`. Поиск и чтение возможностей таким ключом работают.

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

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

- [Поиск по Диску](/docs/disk/search)
- [Зарезервировать загрузку файла на Диск](/docs/disk/uploads-reserve)
- [Загрузить содержимое файла на Диск](/docs/disk/uploads)
- [Проверить видимость объектов Диска](/docs/disk/sync-check)
- [Режим доступа ключа](/docs/keys-auth/access-mode)
- [Ошибки](/docs/errors)