## Поиск документов

`GET /v1/note/documents/search`

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

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `query` (query) | string | да | Поисковый запрос. Минимум 3 символа, максимум 200 |
| `limit` (query) | integer | нет | Количество результатов, от 1 до 200 |

## Примеры

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

```bash
curl -G https://vibecode.bitrix24.tech/v1/note/documents/search \
  --data-urlencode "query=договор" \
  --data-urlencode "limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl -G https://vibecode.bitrix24.tech/v1/note/documents/search \
  --data-urlencode "query=договор" \
  --data-urlencode "limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const params = new URLSearchParams({ query: 'договор', limit: '20' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/note/documents/search?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Найдено:', data)
```

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

```javascript
const params = new URLSearchParams({ query: 'договор', limit: '20' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/note/documents/search?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Массив найденных документов |
| `data[].documentId` | number | Идентификатор документа. Получить документ: `GET /v1/note/documents/:id` |
| `data[].collectionId` | number | База знаний документа. Список: `GET /v1/note/collections` |
| `data[].title` | string | Заголовок документа |
| `data[].score` | number | Оценка релевантности совпадения |
| `data[].snippet` | string | Фрагмент документа с подсветкой совпадений в формате HTML |
| `data[].sharedAccess` | boolean | `true`, если документ доступен по прямому доступу, а не через членство в базе знаний |
| `meta.hasMore` | boolean | Есть ли ещё результаты за пределами `limit` |

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

```json
{
  "success": true,
  "data": [
    {
      "documentId": 11,
      "collectionId": 9,
      "title": "Глава 1",
      "score": 0.0984337329864502,
      "snippet": "<mark>Глава</mark> 1\nТекст документа",
      "sharedAccess": false
    },
    {
      "documentId": 5,
      "collectionId": 7,
      "title": "Глава 1 (обновлено)",
      "score": 0.0984337329864502,
      "snippet": "<mark>Глава</mark> 1\nОбновленный текст",
      "sharedAccess": false
    }
  ],
  "meta": {
    "hasMore": false
  }
}
```

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

400 — запрос короче 3 символов:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`query` must be at least 3 characters"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `query` отсутствует или короче 3 символов |
| 400 | `INVALID_PARAMS` | `limit` вне диапазона от 1 до 200 |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `note` |
| 401 | `TOKEN_MISSING` | У API-ключа не настроены токены |

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

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

**Поле `snippet` содержит HTML.** Фрагмент приходит с HTML-разметкой — совпадения обёрнуты в теги `<mark>…</mark>`, а не в разметку Markdown. Приложение, которое выводит `snippet` в интерфейс, обязано очищать этот HTML от небезопасных конструкций перед отображением. Иначе через содержимое документа возможно внедрение стороннего кода в страницу (XSS).

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

- [Получить документ](/docs/note/documents/get)
- [Дерево документов](/docs/note/collections/tree)
- [Документы](/docs/note/documents)