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

`POST /v1/files/fulltext-search`

Ищет по индексу во всём доступном Диске. [Поиск в одной папке](/docs/entities/files/search) передаёт фильтры, а этот маршрут принимает поисковую строку. Скоуп `disk`. READONLY-ключ разрешён.

## Поля запроса

| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| `query` | string | да | Обязательное. Пробелы схлопываются, края обрезаются, затем длина 3..255 символов |
| `type` | string | нет | `file`, `folder`, `all`. По умолчанию `file` |
| `filter.storageId` | number | нет | Целое положительное ID из [списка хранилищ](/docs/entities/storages/list) |
| `filter.folderId` | number | нет | Целое положительное ID из [списка папок](/docs/entities/folders/list) |
| `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 — личный ключ

```bash
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-приложение

```bash
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 | Файлы и папки — поля как в [Получить файл](/docs/entities/files/get) и [Получить папку](/docs/entities/folders/get) |
| `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](/docs/entities/files/get), папки в проекции [folders](/docs/entities/folders/get). Ссылку `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 или ответ без результата |

Общие отказы — [Ошибки](/docs/errors).

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

- [search](/docs/entities/files/search)
- [list](/docs/entities/storages/list)