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.
Requires the write 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 PATCH "https://example.com/v1/knowledge-bases/string" \ -H "Content-Type: application/json" \ -d '{ "agentIds": [ "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451" ], "description": "Delivery timelines, COD rules and the returns window.", "name": "Shipping and returns policy" }'{ "data": { "agentCount": 2, "chunkCount": 187, "compiledTokens": 0, "createdAt": "2026-08-25T09:14:22Z", "deliveryMode": "inline", "description": "Delivery timelines, COD rules and the returns window.", "docCount": 4, "error": null, "id": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451", "name": "Shipping and returns policy", "status": "empty", "totalBytes": 248311, "updatedAt": "2026-08-25T09:14:22Z" }}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.
Assign a sandbox number — 140/160 require an approved DLT PE ID
Allocates a free number from the sandbox pool. No carrier is contacted and nothing is charged — this is the number you build against before any paperwork exists.