Preview what an agent would retrieve, and answer, for a question
Runs the SAME retrieval a live turn runs, so what you see here is what the agent would get. Optionally generates the answer a caller would hear. degraded: true means embeddings were unavailable and this fell back to keyword search alone — the results are real, just weaker.
Requires the read scope. A key with less gets 403 insufficient_scope.
Authorization: Bearer tone_live_… or tone_test_…. The prefix IS the environment: a test key reaches only the sandbox, and no request field bridges the two.
In: header
Path Parameters
The knowledge base's id.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/knowledge-bases/string/search" \ -H "Content-Type: application/json" \ -d '{ "answer": true, "limit": 3, "query": "How long do I have to return an item?" }'{ "data": { "answer": "You can return unopened items within 30 days for a full refund.", "answerScope": "inline", "answerStatus": "ok", "degraded": true, "results": [ { "documentId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451", "headingPath": "Returns > Timeframe", "matchedText": true, "matchedVector": true, "score": 0, "text": "Unopened items may be returned within 30 days of delivery for a full refund." } ] }}Remove a document from a knowledge base
The index is rebuilt without it. Until that build succeeds, the old index keeps serving.
Update a knowledge base or its attached agents
agentIds is the COMPLETE attachment set, not a delta: send the full list every time, omit the key to leave attachments untouched, send an empty array to detach it from everything.