Tone docs
API referenceKnowledge bases

Get a knowledge base

Includes the chunk count from the last successful build — the number of retrievable passages an agent can actually draw on.

Open in ClaudeOpen in ChatGPTView as Markdown

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

GET
/v1/knowledge-bases/{id}

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

Path Parameters

id*string

The knowledge base's id.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/knowledge-bases/string"
{  "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?

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.

List the organization’s knowledge bases

Each with its derived status, document count and size. Status is computed, not stored: a base is empty, indexing, ready or error based on what its last build did.