Knowledge Bases
Manage and search knowledge bases via the API.
Endpoints for knowledge bases under /api/v1/knowledge-bases.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/knowledge-bases | List knowledge bases |
| POST | /api/v1/knowledge-bases | Create a knowledge base |
| PATCH | /api/v1/knowledge-bases/{id} | Update a knowledge base |
| POST | /api/v1/knowledge-bases/search | Semantic search |
Manage knowledge bases
GET /api/v1/knowledge-bases returns { knowledgeBases[] }.
POST /api/v1/knowledge-bases creates one:
| Field | Type | Notes |
|---|---|---|
name | string | Required |
description | string | Optional |
chunking | object | Optional { minChunkSizeChars, maxChunkSizeTokens, overlapTokens } |
Defaults are minChunkSizeChars: 100, maxChunkSizeTokens: 1024, overlapTokens: 200. Returns
201 with { knowledgeBase }. PATCH /api/v1/knowledge-bases/{id} accepts { trashed } to
trash or restore.
Search
POST /api/v1/knowledge-bases/search runs hybrid (semantic + keyword) retrieval:
{ "knowledgeBaseId": "kb_...", "query": "refund policy", "limit": 5 }
knowledgeBaseId is optional — omit it to search across all knowledge bases in the workspace. An
empty query returns { results: [] }. Each result carries the matching chunk, its document,
score, and a provenance of vector, hybrid, or keyword (keyword-only when embeddings are
unavailable). See Knowledge Base for how indexing and retrieval work.