Knowledge Base

A knowledge base is pinned to one embedding model, chosen when it's created and fixed after -- everything added to it is indexed with that model.

POST /api/knowledge-bases
Content-Type: application/json

{
  "name": "Product docs",
  "description": "Public help-center articles",
  "embeddingModelSlug": "studio/qwen3-embedding-0.6b"
}

Sources are added as file uploads -- text, Markdown, or PDF today. Upload is a multipart/form-data request; indexing happens in the background, so the response comes back immediately with the source in a QUEUED state.

POST /api/knowledge-bases/:id/sources
Content-Type: multipart/form-data

type=TEXT
file=<binary>

A source moves through UPLOADED → QUEUED → PROCESSING → INDEXED (or FAILED, with a plain-language reason) as it's processed. Poll GET /api/knowledge-bases/:id to watch its status.

Querying is streaming, the same Server-Sent Events shape as Chat Completions, with one addition: a sources event sent before the first answer token, listing what was found before generation starts.

POST /api/knowledge-bases/:id/query
Content-Type: application/json

{
  "query": "What's the refund policy?",
  "model": "studio/qwen3-0.6b"
}

data: {"type":"sources","sources":[{"score":0.82,"snippet":"...","documentId":"...","sourceId":"..."}]}

data: {"type":"delta","content":"Refunds"}
data: {"type":"delta","content":" are"}
...
data: {"type":"done","finishReason":"stop","usage":{"inputTokens":251,"outputTokens":42,"totalTokens":293}}

This endpoint streams the same event shape used internally by the model gateway (inputTokens/outputTokens), not the OpenAI-wire-format field names Chat Completions uses -- there's no choices/delta wrapping here.

If nothing relevant is indexed, sources comes back empty and the model is instructed to say so rather than guess -- it never falls back to answering from outside what you've added to the knowledge base.

POST /api/knowledge-bases/:id/reindex re-processes every active source -- useful after a chunking or model change. The previous version keeps answering questions until the new one finishes successfully, so there's no gap where nothing is searchable.

DELETE /api/knowledge-bases/:id/sources/:sourceId removes a source and everything indexed from it; it stops being searchable immediately, not just hidden from listings. DELETE /api/knowledge-bases/:id removes the whole knowledge base the same way.

Indexing and querying draw down the same hosted credits as chat traffic -- there's no separate billing system for this feature. See Usage for a breakdown by knowledge base.