For AI agents: markdown of this page — /docs-content-en/note/documents/search.md documentation index — /llms.txt

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.

Parameters

Parameter Type Required Description
query (query) string yes Search query. Minimum 3 characters, maximum 200
limit (query) integer no Number of results, from 1 to 200

Examples

curl — personal key

Terminal 
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

Terminal 
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

javascript 
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

javascript 
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

Field Type Description
success boolean Always true on success
data array Array of found documents
data[].documentId number Document identifier. Get the document: GET /v1/note/documents/:id
data[].collectionId number The document's knowledge base. List: GET /v1/note/collections
data[].title string Document title
data[].score number Relevance score of the match
data[].snippet string Document fragment with highlighted matches in HTML
data[].sharedAccess boolean true if the document is available via direct access rather than knowledge base membership
meta.hasMore boolean Whether there are more results beyond limit

Response example

JSON 
{
  "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:

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

Errors

HTTP Code Description
400 INVALID_PARAMS query is missing or shorter than 3 characters
400 INVALID_PARAMS limit is outside the range from 1 to 200
403 SCOPE_DENIED The key lacks the note scope
401 TOKEN_MISSING The API key has no tokens configured

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 }. 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