# Create a knowledge base

Source: https://docs.usetone.ai/reference/knowledge/create

> Creates it empty.

`POST /v1/knowledge-bases`
Creates it empty. Add documents, wait for the build, then attach it to an agent.

Requires the `write` scope.

## Request body

| Field | Type | | Meaning |
|---|---|---|---|
| `description` | string | optional | What this base covers. For your own reference; the agent does not read it. |
| `name` | string | required | Your name for the knowledge base. |

### Example request

```json
{
  "description": "Delivery timelines, COD rules and the returns window.",
  "name": "Shipping and returns policy"
}
```

## Response

| Field | Type | | Meaning |
|---|---|---|---|
| `agentCount` | integer | required | How many agents currently reference this base. Listed by `GET /v1/knowledge-bases/{id}/agents`. |
| `chunkCount` | integer | null | required | How many retrievable passages the last successful build produced. Null before the first build succeeds. |
| `compiledTokens` | integer | null | required | Size of the compiled snapshot. Null until a build has succeeded. |
| `createdAt` | string | required | RFC 3339, UTC. |
| `deliveryMode` | string | required | How this base reaches the agent on a call: `inline` — the whole text rides in the system prompt, no per-turn retrieval and no added latency; `search` — too large to send in full, so passages are retrieved per question; `pending` — nothing built yet. Open set — handle an unrecognised value rather than throwing. Today: `inline`, `search`, `pending`. |
| `description` | string | null | required | What this base covers. For your reference; the agent does not read it. |
| `docCount` | integer | required | How many documents the base holds. |
| `error` | string | null | required | Populated only when `status` is `error`. A failed build behind a still-serving one deliberately reports null — the agent is not broken. |
| `id` | string | required | The knowledge base's unique id. |
| `name` | string | required | Your name for the knowledge base. |
| `status` | string | required | Derived lifecycle. `ready` means an agent can answer from this base right now; a base serving its last good build while a newer one failed is still `ready`, because the agent genuinely is answering fine. Open set — handle an unrecognised value rather than throwing. Today: `empty`, `processing`, `ready`, `error`. |
| `totalBytes` | integer | required | Combined size of those documents, in bytes. |
| `updatedAt` | string | required | When the knowledge base was last changed. RFC 3339, UTC. |

### Example response

```json
{
  "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"
  }
}
```