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 the interface must sanitize this HTML of unsafe constructs before rendering. Otherwise, third-party code could be injected into the page through the document contents (XSS).

See also