{"slug":"knowledgebases","title":"Knowledgebases","path":"knowledgebases.md","markdown":"# Knowledgebases\n\nA knowledgebase is a private collection of files you can index and search. You never pass an owner id: every call runs as the account behind your API key.\n\n## Identifiers\n\n| Field | Role |\n| ----- | ---- |\n| `id` | Stable handle (`kb_…`). Use this in all nested routes and CLI `-kb` / `-id` flags. |\n| `name` | Display name. You can rename it; the `id` does not change. |\n| `description` | Short blurb. |\n\nExample object:\n\n```json\n{\n  \"id\": \"kb_qc0rp0gz\",\n  \"name\": \"notes\",\n  \"description\": \"project notes\",\n  \"status\": \"complete\",\n  \"statusInfo\": \"index up to date\",\n  \"createdAt\": \"2026-07-15T13:24:19.812169Z\",\n  \"lastUpdated\": \"2026-07-15T13:53:38.853622Z\"\n}\n```\n\n`status` / `statusInfo` reflect indexing progress for this knowledgebase. Common status values: `pending`, `checking`, `digesting`, `halted`, `error`, `complete`.\n\n## List\n\n```bash\nkobold-cli kb list\nkobold-cli kb list -offset 0 -limit 20\n```\n\n```http\nGET /v1/knowledgebases?offset=0\u0026limit=50\nAuthorization: Bearer \u003capi_key\u003e\n```\n\n| Query | Default | Notes |\n| ----- | ------- | ----- |\n| `offset` | `0` | Skip this many rows |\n| `limit` | `50` | Max `100` |\n\nResults are ordered newest-first by `createdAt`. Response: JSON array of knowledgebase objects.\n\n## Create\n\n```bash\nkobold-cli kb create -name notes -description \"project notes\"\n```\n\n```http\nPOST /v1/knowledgebases\nAuthorization: Bearer \u003capi_key\u003e\nContent-Type: application/json\n\n{\n  \"name\": \"notes\",\n  \"description\": \"project notes\"\n}\n```\n\nBoth `name` and `description` are required. Response includes the new `id`. Initial index `status` is typically `pending`.\n\nIf you are at your plan’s knowledgebase count ceiling, create fails with `403`.\n\n## Get\n\n```bash\nkobold-cli kb get -id kb_qc0rp0gz\n```\n\n```http\nGET /v1/knowledgebases/kb_qc0rp0gz\nAuthorization: Bearer \u003capi_key\u003e\n```\n\nUnknown or inaccessible ids → `404`.\n\n## Patch\n\nUpdate name and/or description. At least one field required.\n\n```bash\nkobold-cli kb patch -id kb_qc0rp0gz -name \"project notes\"\nkobold-cli kb patch -id kb_qc0rp0gz -description \"updated\"\n```\n\n```http\nPATCH /v1/knowledgebases/kb_qc0rp0gz\nAuthorization: Bearer \u003capi_key\u003e\nContent-Type: application/json\n\n{\n  \"name\": \"project notes\"\n}\n```\n\nRenaming does not change `id` or break existing file/search URLs that use that id.\n\n## Delete\n\n```bash\nkobold-cli kb delete -id kb_qc0rp0gz\n```\n\n```http\nDELETE /v1/knowledgebases/kb_qc0rp0gz\nAuthorization: Bearer \u003capi_key\u003e\n```\n\nDeletes the knowledgebase and its files. CLI prints `{\"ok\": true}` on success.\n\n## Related\n\n- [Files](files.md) — put content in the knowledgebase\n- [Index and search](index-and-search.md) — make it searchable\n"}