Tone docs
API referenceKnowledge bases

Create a knowledge base

Creates it empty. Add documents, wait for the build, then attach it to an agent.

Open in ClaudeOpen in ChatGPTView as Markdown

Requires the write scope. A key with less gets 403 insufficient_scope.

POST
/v1/knowledge-bases

Authorization

AuthorizationBearer <token>

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

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

curl -X POST "https://example.com/v1/knowledge-bases" \  -H "Content-Type: application/json" \  -d '{    "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"  }}
Was this page helpful?

Confirm an upload finished and queue it for indexing

Phase two. Nothing is trusted until here: the object is re-read and its real size and type checked against what you declared. Indexing is asynchronous — wait for knowledge.build.completed rather than polling.

Get a presigned URL to upload a document

Phase one of a two-phase upload: declare the file, PUT the bytes to the URL you get back, then confirm. contentLength is signed into the URL and must match exactly — a presigned PUT that does not pin the length is an unbounded write.