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

Поиск по Диску

POST /v1/disk/search

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

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

Поле	Тип	Обяз.	По умолч.	Описание
Поле`query`	Типstring	Обяз.да	По умолч.—	ОписаниеПоисковая строка. Края обрезаются, пробелы внутри схлопываются в один. Длина — от 3 до 255 символов до и после этой обработки
Поле`type`	Типstring	Обяз.да	По умолч.—	ОписаниеЧто искать: `file`, `folder` или `all`
Поле`filter.storageId`	Типstring	Обяз.нет	По умолч.—	ОписаниеID хранилища, десятичная строка. Список хранилищ: `GET /v1/storages`
Поле`filter.folderId`	Типstring	Обяз.нет	По умолч.—	ОписаниеID папки, десятичная строка. Корневая папка хранилища — поле `rootFolderId` в `GET /v1/storages`, вложенные папки — `GET /v1/folders` или `objectId` карточки с `objectType: "folder"` из этого поиска
Поле`filter.fileType`	Типstring	Обяз.нет	По умолч.—	ОписаниеТип файла, например `document`. Длина от 1 до 64 символов. Только при `type: "file"`, с другим `type` запрос отклоняется `400 INVALID_PARAMS`
Поле`limit`	Типnumber	Обяз.нет	По умолч.`50`	ОписаниеВерхняя граница числа карточек в ответе, от 1 до 1000
Поле`cursor`	Типstring	Обяз.нет	По умолч.—	ОписаниеЗначение `nextCursor` из предыдущего ответа. В первом запросе не передаётся

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

Отправьте первый запрос без cursor.
Если в ответе hasMore: true, повторите запрос с теми же query, type и filter, передав nextCursor целиком в поле cursor.
Продолжайте, пока hasMore не станет false. Страница может прийти короче limit и даже пустой при hasMore: true — это не конец выдачи.

Курсор действует час с момента первого запроса обхода, продолжение срок не продлевает. Курсор привязан к строке поиска, type, filter и к привязке ключа из GET /v1/disk/capabilities. Просроченный курсор, курсор от другого запроса и курсор после роста identity.accountGeneration дают 403 DISK_GENERATION_STALE — начните обход заново без cursor.

Примеры

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

Terminal

curl -X POST https://vibecode.bitrix24.tech/v1/disk/search \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "vibe-disk-docs-check",
    "type": "file",
    "limit": 1
  }'

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

Terminal

curl -X POST https://vibecode.bitrix24.tech/v1/disk/search \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "vibe-disk-docs-check",
    "type": "file",
    "limit": 1
  }'

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

javascript

// Обход всех страниц выдачи курсором
const items = []
let cursor

do {
  const res = await fetch('https://vibecode.bitrix24.tech/v1/disk/search', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: 'vibe-disk-docs-check',
      type: 'file',
      limit: 1,
      ...(cursor ? { cursor } : {}),
    }),
  })
  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.name))

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

javascript

const res = await fetch('https://vibecode.bitrix24.tech/v1/disk/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'vibe-disk-docs-check',
    type: 'file',
    limit: 1,
  }),
})

const { data } = await res.json()
console.log(data.items, data.hasMore)

Поля ответа

Поле	Тип	Описание
Поле`success`	Типboolean	Описание`true` при успешном ответе
Поле`data.items`	Типarray	ОписаниеКарточки найденных объектов, не больше `limit`
Поле`data.items[].objectId`	Типstring	ОписаниеID файла или папки. Для файла подходит в `GET /v1/files/:id`, для папки — в `filter.folderId` следующего поиска
Поле`data.items[].objectType`	Типstring	Описание`file` или `folder`
Поле`data.items[].name`	Типstring	ОписаниеНазвание объекта
Поле`data.items[].storageId`	Типstring	ОписаниеID хранилища, в котором лежит объект
Поле`data.items[].parentId`	Типstring	ОписаниеID родительской папки. Может отсутствовать
Поле`data.items[].size`	Типstring	ОписаниеТолько у файла. Размер в байтах, десятичная строка
Поле`data.items[].contentFileId`	Типstring	ОписаниеТолько у файла. ID текущего содержимого файла
Поле`data.items[].contentGeneration`	Типstring	ОписаниеТолько у файла. Номер текущей версии содержимого. Вместе с `contentFileId` и `size` нужен для загрузки новой версии через `POST /v1/disk/uploads/reserve`
Поле`data.items[].safeLink`	Типstring	ОписаниеАдрес объекта в веб-интерфейсе Битрикс24. Только `https`, без параметров и учётных данных. Ссылкой на скачивание не является. Отсутствует, если портал не отдал такой адрес
Поле`data.items[].source`	Типstring	ОписаниеПроисхождение карточки. В поиске всегда `native-current` — текущие данные портала на момент запроса
Поле`data.hasMore`	Типboolean	ОписаниеЕсть ли продолжение выдачи
Поле`data.nextCursor`	Типstring	ОписаниеКурсор следующей страницы. Только при `hasMore: true`, см. «Навигация»
Поле`data.truncated`	Типboolean	Описание`true`, когда выдача упёрлась в предел 1000 позиций поиска портала: результаты дальше этой границы недоступны, уточните `query` или `filter`
Поле`data.limitations`	Типstring[]	ОписаниеПояснения к выдаче на английском. Первые две строки приходят всегда. Дополнительные строки сообщают, что часть найденных объектов не удалось показать или что страница закончилась раньше из-за ограничения времени или размера ответа — тогда продолжайте обход по `nextCursor`

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

Первая страница при limit: 1 — найдено два файла, второй придёт по nextCursor:

JSON

{
  "success": true,
  "data": {
    "items": [
      {
        "objectId": "10901",
        "objectType": "file",
        "name": "vibe-disk-docs-check-2.txt",
        "storageId": "1",
        "parentId": "1",
        "size": "29",
        "contentFileId": "39571",
        "contentGeneration": "1",
        "safeLink": "https://example.bitrix24.ru/company/personal/user/1/disk/file/vibe-disk-docs-check-2.txt",
        "source": "native-current"
      }
    ],
    "hasMore": true,
    "nextCursor": "4OI2oJB6n4E0MLK5:ipx34E3vaJmBYDYNX5IKpKEMOJJEocUC2GenIl8JleEm7X1UnoGfWTtf2E1/gDE0aR3Nq+fesCeRRqN3520Gq0hkB2XxI+rSCbg+W3T6NbfMNHYlDWg010aWQOYz2VkxapPddVjEYUT3BUX4Hn5j68DX05BTFZv9gE5F4qUwxcEOTaeW8ReIfBa/dcCR0CzHMaEVxmilisorOtaRWGLDhdtjvYgRmIQpcFSOPuEfYn2JWYTZPRQmcn92Bi8PZx1Y70zRSYXxzw/mrsYgzAuzICojBvE=:LaEM6qPdvLmXkEoPFgtftA==",
    "truncated": false,
    "limitations": [
      "Native search pages contain at most 50 objects and offsets stop at 1000.",
      "The native index and access rights can change between requests; search is not a stable snapshot."
    ]
  }
}

На последней странице hasMore равно false, а поля nextCursor нет.

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

400 — поисковая строка короче трёх символов:

JSON

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

Ошибки

HTTP	Код	Описание
HTTP400	Код`INVALID_PARAMS`	ОписаниеТело нарушает правила полей: не передан `query` или `type`, длина `query` вне 3–255, `filter.fileType` при `type` не `file`, `limit` вне 1–1000, ID не десятичная строка, неизвестное поле
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	Код`DISK_GENERATION_STALE`	ОписаниеКурсор просрочен, выдан для другого запроса или до роста `identity.accountGeneration`. Начните обход без `cursor`
HTTP403	Код`DISK_ACCESS_DENIED`	ОписаниеБитрикс24 отказал пользователю в доступе к поиску
HTTP403	Код`SCOPE_DENIED`	ОписаниеУ ключа нет скоупа `disk`
HTTP501	Код`DISK_UNSUPPORTED`	ОписаниеПортал не поддерживает поиск по Диску — признак `search.available` в `GET /v1/disk/capabilities`
HTTP502	Код`DISK_UNSUPPORTED`	ОписаниеПортал вернул выдачу в неожиданном виде либо первая же карточка превышает предел размера ответа
HTTP502	Код`DISK_READ_UNAVAILABLE`	ОписаниеПоиск не удался по причине, которой нет среди остальных кодов. Повторите запрос позже
HTTP503	Код`BITRIX_TIMEOUT`	ОписаниеОтведённые на запрос 20 секунд истекли до первого обращения к поиску портала, либо портал не ответил вовремя
HTTP503	Код`QUERY_LIMIT_EXCEEDED`	ОписаниеПортал ограничил частоту запросов
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 — Ошибки.

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

Выдача — не снимок Диска. Поисковый индекс портала и права доступа меняются между запросами, поэтому при обходе курсором объект может появиться, исчезнуть или сместиться между страницами.

Один запрос ограничен по времени и объёму. На запрос отводится 20 секунд, включая проверку пользователя. За один запрос читается столько страниц поиска портала по 50 позиций, сколько нужно на limit карточек, а карточки в ответе занимают не больше 2 МиБ. Если время, страницы или размер исчерпаны раньше, чем набралось limit карточек, ответ приходит с тем, что успело набраться, hasMore: true и строкой о причине в limitations.

Ключ «только чтение» ищет. Запрос не изменяет данные и доступен ключу в режиме «только чтение».

Содержимое одной папки. Чтобы получить содержимое известной папки с условиями по полям, а не искать по всему Диску, используйте POST /v1/files/search.