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

GET /v1/note/documents/search

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

Общий параметр filter этим эндпоинтом не применяется. По умолчанию API сохраняет прежний ответ HTTP 200 и прежние данные, добавляет заголовок Warning: 299 - "filter is not supported on this endpoint and was ignored", а сервер фиксирует использование неподдерживаемого фильтра в журнале.

Параметры

Следующая страница. Если meta.hasMore равен true, повторите тот же query и limit, увеличив offset на размер страницы: после limit=20&offset=0 запросите limit=20&offset=20. Поиск ограничен смещением 10000: если hasMore ещё true на этом пределе, следующая страница поиска недоступна. Для полного обхода статей используйте список документов.

Примеры

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

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

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 — личный ключ

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

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": 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 символов:

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

Ошибки

Полный список общих ошибок API — Ошибки.

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

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

POST-форма запроса. Эндпоинт принимает и POST /v1/note/documents/search с теми же параметрами в JSON-теле: { "query": "договор", "limit": 20, "offset": 20 }. Ответ одинаковый в обеих формах. Каноническая форма — GET. Если параметр передан и в строке запроса, и в теле, действует значение из тела.

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

• Получить документ
• Список документов
• Дерево документов
• Документы