# Search a knowledge base as the agent does

`GET https://app.whatsetter.com/api/v1/knowledge-bases/{id}/search`

Returns the passages the agent is handed when a lead writes `query`:
the same search as at reply time, with the same limits (4 passages at
most, only those close enough to the message, and only the last 500
characters of the message count). Use it to see why an agent answered
the way it did, or to check that a new answer is found.

`matched: false` means the agent gets nothing from the base for this
message and answers from its prompt alone. `reason` says why:
`no_match` (nothing close enough), `empty` (the base holds nothing
yet) or `inactive`.

The first message and the follow-ups do not search the base: only
replies do. Requires scope `knowledge:read`.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `query` | query | string | yes | The lead's message, as the agent received it. |

## Example request

```bash
curl --request GET \
  --url 'https://app.whatsetter.com/api/v1/knowledge-bases/{id}/search' \
  --header 'Authorization: Bearer ws_live_…'
```

## Responses

### 200: What the agent finds

```json
{
  "data": {
    "query": "how much is the trial session?",
    "matched": true,
    "reason": null,
    "results": [
      {
        "text": "Q: How much is the trial session?\nA: The trial session is free, with no commitment.",
        "source": "Q&A",
        "score": 0.812
      },
      {
        "text": "Memberships start at 39 EUR per month. The first session is offered to every new member.",
        "source": "tarifs-2026.pdf",
        "score": 0.547
      }
    ]
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 403: The key lacks the required scope (`insufficient_scope`), the plan does not have this part of the API (`not_in_plan`), or Instagram is not enabled on the workspace (`instagram_not_enabled`, Instagram routes)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 404: Resource not found in this workspace

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 422: Invalid parameter or body (also an invalid or expired `cursor`)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 502: The knowledge store did not answer

```json
{
  "error": {
    "code": "upstream_error",
    "message": "The knowledge store did not answer. Try again in a moment."
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/searchknowledgebase/
