Skip to content
OrbContext
19 pages

API reference

Knowledge search

Retrieve authorized passages without generating an answer.

Search knowledge passages

POST/v1/bots/{botId}/knowledge/searchscope: knowledge:read

Requires 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

botId
path · stringrequired
—

Request body · application/json

query
stringrequired
Min length: 1 · Max length: 4000
limit
integer
Min: 1 · Max: 20 · Default: 5
location
string
Min length: 1 · Max length: 80
audience
string
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" }'
Response 200
{
  "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.