Knowledge
Search a knowledge base as the agent does
const url = 'https://app.whatsetter.com/api/v1/knowledge-bases/example/search?query=example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”The lead’s message, as the agent received it.
Responses
Section titled “Responses”What the agent finds
object
object
The text actually searched (the last 500 characters of the message).
At most 4, best first.
object
The file, the page or Q&A.
Closeness to the message, from 0 to 1.
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
object
object
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)
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Resource not found in this workspace
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Invalid parameter or body (also an invalid or expired cursor)
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}The knowledge store did not answer
object
object
Example
{ "error": { "code": "upstream_error", "message": "The knowledge store did not answer. Try again in a moment." }}