Search documents

GET /v1/note/documents/search

Runs a full-text search over the titles and contents of documents from knowledge bases available to the key, as well as documents to which direct access has been granted. Use it to find documents by keywords when the identifier is not known in advance.

The generic filter parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds Warning: 299 - "filter is not supported on this endpoint and was ignored", and records unsupported-filter use in the server log. The POST form retains its previous behavior.

Parameters

Next page. If meta.hasMore is true, repeat the same query and limit with the offset increased by the page size: after limit=20&offset=0, request limit=20&offset=20. Search is capped at offset 10000: if hasMore is still true there, another search page is unavailable. Use the document list to traverse all documents.

Examples

curl — personal key

curl -G https://vibecode.bitrix24.com/v1/note/documents/search \
  --data-urlencode "query=contract" \
  --data-urlencode "limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl -G https://vibecode.bitrix24.com/v1/note/documents/search \
  --data-urlencode "query=contract" \
  --data-urlencode "limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const params = new URLSearchParams({ query: 'contract', limit: '20' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/note/documents/search?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Found:', data)

JavaScript — OAuth application

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

Response fields

Response example

{
  "success": true,
  "data": [
    {
      "documentId": 11,
      "collectionId": 9,
      "title": "Chapter 1",
      "score": 0.0984337329864502,
      "snippet": "<mark>Chapter</mark> 1\nDocument text",
      "sharedAccess": false
    },
    {
      "documentId": 5,
      "collectionId": 7,
      "title": "Chapter 1 (updated)",
      "score": 0.0984337329864502,
      "snippet": "<mark>Chapter</mark> 1\nUpdated text",
      "sharedAccess": false
    }
  ],
  "meta": {
    "hasMore": false
  }
}

Error response example

400 — query shorter than 3 characters:

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

Errors

Full list of common API errors — Errors.

Known specifics

The snippet field contains HTML. The fragment arrives with HTML markup — matches are wrapped in <mark>…</mark> tags rather than Markdown. An application that displays snippet in its interface must sanitize this HTML by removing unsafe constructs before rendering it. Otherwise, third-party code could be injected into the page through the document contents (XSS).

POST form of the request. The endpoint also accepts POST /v1/note/documents/search with the same parameters in a JSON body: { "query": "contract", "limit": 20, "offset": 20 }. The response is identical in both forms. The canonical form is GET. If a parameter is passed both in the query string and in the body, the body value takes precedence.

See also

• Get a document
• List documents
• Document tree
• Documents