Skip to content
Dashboard

Search a knowledge base as the agent does

GET
/knowledge-bases/{id}/search
curl --request GET \
--url 'https://app.whatsetter.com/api/v1/knowledge-bases/example/search?query=example' \
--header 'Authorization: Bearer <token>'

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.

id
required
string
query
required
string
>= 1 characters <= 2000 characters

The lead’s message, as the agent received it.

What the agent finds

Media typeapplication/json
object
data
object
query

The text actually searched (the last 500 characters of the message).

string
matched
boolean
reason
string | null
Allowed values: no_match empty inactive
results

At most 4, best first.

Array<object>
object
text
string
source

The file, the page or Q&A.

string | null
score

Closeness to the message, from 0 to 1.

number | null
Example
{
"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
}
]
}
}

Missing, unknown or revoked API key

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

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)

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

Resource not found in this workspace

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

Invalid parameter or body (also an invalid or expired cursor)

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

The knowledge store did not answer

Media typeapplication/json
object
error
object
code
string
message
string
Example
{
"error": {
"code": "upstream_error",
"message": "The knowledge store did not answer. Try again in a moment."
}
}