## 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

```bash
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

```bash
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](/docs/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

- [Get a document](/docs/note/documents/get)
- [Document tree](/docs/note/collections/tree)
- [Documents](/docs/note/documents)