Knowledge Base overview

The Knowledge Base API lets you upload documents, chunk + embed them in the background, and retrieve relevant chunks during a call via the query tool type.

Lifecycle

[upload]  →  [process]  →  [chunks indexed]  →  [retrievable in calls]
   ↓             ↓                                       ↑
upload-url   process-document                        query tool
+ PUT file   (or create-from-text)                   (during a call)

Endpoints

Method	Path	Purpose
`POST`	`/knowledge-base/upload-url`	Get a presigned S3 URL to PUT a file.
`POST`	`/knowledge-base/create-from-text`	Create a doc directly from pasted text.
`POST`	`/knowledge-base/process-document`	Register an uploaded file for processing.
`GET`	`/knowledge-base/documents`	List documents.
`GET`	`/knowledge-base/documents/{uuid}`	Document detail (status, total chunks, error).
`DELETE`	`/knowledge-base/documents/{uuid}`	Soft-delete a document + its chunks.
`POST`	`/knowledge-base/search`	Vector search across your documents.

Embedding model

Embeddings are computed with OpenAI text-embedding-3-small (1536 dims). The platform's OpenAI key is used — you don't supply one.

Retrieval modes

Documents are ingested with one of two retrieval modes:

Mode	When to use
`chunked` (default)	Long documents — chunked at ~128 tokens and individually embedded. Best for fact lookup.
`full_document`	Short documents (FAQs, single-topic notes) where the LLM benefits from the full text every time.

State	Meaning
`pending`	Document record exists; processing job not yet picked up.
`processing`	Background worker is parsing + embedding.
`completed`	Chunks indexed; document is queryable in calls.
`failed`	Parsing or embedding errored — see `processing_error` field.

You can reference a documentId in an agent or query tool before processing completes — the retrieval simply returns no chunks until status is completed. Don't block on processing in real-time provisioning flows.

File size + format

Limit	Value
Max file size	100 MB
Presigned URL expiration	30 minutes
Supported formats	PDF, DOCX, DOC, TXT, MD, JSON, and CSV via the Files API, plus additional formats handled by the document-parsing engine