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

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

GET /v1/note/documents/search

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

Параметры

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

Примеры

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

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

Terminal 
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 — Ошибки.

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

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

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