POST/1.0/knowledge-bases/:id/documents

Adds documents and starts ingestion — chunking and embedding, plus entity extraction for graph-recipe knowledge bases. Required scope: workbench:knowledge_bases:write (scopes reference).

Embedding spends workspace inference credit, like any other run.

Request body

sourcesarrayRequired

1–50 documents per request. Each source:

name (string, required) — e.g. "refund-policy.md".
content (string, required) — the document body, up to ~10 MB per source.
mimeType (string) — defaults to text/plain. Use application/pdf / DOCX types with base64 encoding for binary uploads.
encoding ("utf8" | "base64") — defaults to utf8 for text (Markdown, TXT, CSV). Use base64 for binary formats (PDF, DOCX); the server extracts text before chunking.

embeddingModelstring

Namespaced embedding model override. Defaults are applied automatically; changing models across ingestions re-embeds on the new model.

Response

202 — ingestion runs in the background:

{
  "ingestion": {
    "runId": "kbrun_...",
    "kbId": "kb_...",
    "status": "running",
    "sourceCount": 2
  }
}

Poll GET /1.0/knowledge-bases/:id — when status returns to ready, the new content is searchable.

Returns 402 plan_limit when the upload would exceed the workspace's knowledge-base storage for its plan.

1 min read