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

Полнотекстовый поиск на Диске

POST /v1/files/fulltext-search

Ищет по индексу во всём доступном Диске. Поиск в одной папке передаёт фильтры, а этот маршрут принимает поисковую строку. Скоуп disk. READONLY-ключ разрешён.

Поля запроса

Поле	Тип	Обяз.	Описание
`query`	string	да	Обязательное. Пробелы схлопываются, края обрезаются, затем длина 3..255 символов
`type`	string	нет	`file`, `folder`, `all`. По умолчанию `file`
`filter.storageId`	number	нет	Целое положительное ID из списка хранилищ
`filter.folderId`	number	нет	Целое положительное ID из списка папок
`filter.fileType`	string или array	нет	Только при `type=file`: `document`, `image`, `video`, `audio`, `archive`, `pdf`, `vector_image`, `board`, `known`, `unknown`. Массив непустой
`offset`	number	нет	Целое 0..1000, по умолчанию 0

Лишние поля отклоняются. limit не принимается: размер страницы Битрикс24 фиксирован, 50 записей.

Примеры

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

Terminal

curl -X POST 'https://vibecode.bitrix24.tech/v1/files/fulltext-search' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query":"report","filter":{"fileType":"document"},"offset":0}'

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

Terminal

curl -X POST 'https://vibecode.bitrix24.tech/v1/files/fulltext-search' \
  -H 'X-Api-Key: YOUR_APP_KEY' \
  -H 'Authorization: Bearer USER_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"query":"report","filter":{"fileType":"document"},"offset":0}'

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

javascript

const response = await fetch('https://vibecode.bitrix24.tech/v1/files/fulltext-search', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"query": "report", "filter": {"fileType": "document"}, "offset": 0}),
})
const result = await response.json()
console.log(result)

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

javascript

const response = await fetch('https://vibecode.bitrix24.tech/v1/files/fulltext-search', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"query": "report", "filter": {"fileType": "document"}, "offset": 0}),
})
const result = await response.json()
console.log(result)

Поля ответа

Поле	Тип	Описание
`success`	boolean	Признак успешного запроса
`data.items`	array	Файлы и папки — поля как в Получить файл и Получить папку
`data.meta.nextOffset`	number \| null	Следующее смещение; null в конце
`data.meta.maxOffset`	number	Максимальное смещение: 1000

JSON

{"success":true,"data":{"items":[{"id":42,"type":"file","name":"report.pdf","folderId":9,"downloadUrl":"https://vibecode.bitrix24.tech/v1/files/42/download"}],"meta":{"nextOffset":null,"maxOffset":1000}}}

data.items — файлы в проекции files, папки в проекции folders. Ссылку downloadUrl вызывайте с тем же API-ключом. data.meta.nextOffset — смещение следующей страницы или null, используйте его в следующем запросе. total отсутствует: Битрикс24 не возвращает число совпадений.

Корзина не ищется. Пустая выдача не доказывает отсутствие файла: индекс обновляется асинхронно, содержимое индексируется не у всех форматов. Поиск по имени надёжнее. После смещения 1000 продолжить нельзя, сужайте запрос.

Ошибки

Пример отказа (400):

JSON

{"success":false,"error":{"code":"INVALID_PARAMS","message":"query must contain 3..255 characters after whitespace normalization."}}

HTTP	Код	Описание
400	`INVALID_PARAMS`	Неверные query, type, filter или offset, лишние поля
403	`SCOPE_DENIED`	Нет скоупа disk
403	`BITRIX_ACCESS_DENIED`	Битрикс24 отказал в доступе
404	`ENTITY_NOT_FOUND`	Хранилище или папка не найдены либо недоступны. Эти причины намеренно не различаются
422	`BITRIX_ERROR`	Бизнес-отказ Битрикс24 или ответ без результата
422	`OPERATION_FAILED`	Бизнес-отказ Битрикс24 или ответ без результата

Общие отказы — Ошибки.

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

search
list