Search knowledge passages
POST
/v1/bots/{botId}/knowledge/searchscope: knowledge:readRequires the knowledge:read scope and access to the requested bot. `audience` must be allowed for the key; omitted means public knowledge only. `location` narrows results and never grants access.
Parameters
botIdpath · stringrequired | — |
Request body · application/json
querystringrequired | Min length: 1 · Max length: 4000 |
limitinteger | Min: 1 · Max: 20 · Default: 5 |
locationstring | Min length: 1 · Max length: 80 |
audiencestring | Min length: 1 · Max length: 80 |
Example
curl -X POST '$ORBCONTEXT_API_URL/v1/bots/{botId}/knowledge/search' \
-H "Authorization: Bearer $ORBCONTEXT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "query": "string" }'{
"hits": [
{
"chunkId": "k_example",
"documentId": "d_your_document_id",
"text": "Employees receive 12 days of paid sick leave each year.",
"headingPath": "Leave > Sick leave",
"page": null
}
],
"requestId": "req_example"
}Responses
200400401402403404413415429500503
Authorized passages from ready, current documents, best first. An empty `hits` array is a successful no-match. No answer is generated and no conversation is created. Each successful call consumes credits; a failed call is refunded. Not retried automatically by the SDK.
Error responses share one shape; see Errors & limits.