API ReferenceKnowledge Bases

Upload Knowledge Base Document

Upload a document (PDF, plain text, markdown, or HTML) to a knowledge base. The document is extracted, chunked, embedded, and indexed synchronously; expect a few seconds per MB of input. Maximum 10 MB per upload.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

idstringRequired

Request

This endpoint expects a multipart form containing a file.
filefileRequired

Response

The ingested document record.
idstring
kb_idstring

Prefixed wire identifier (kb_<26 char Crockford base32>) of the knowledge base the document belongs to.

source_kindenum

How the document entered the KB. file is the upload path, text is inline pasted content, url is fetched via Firecrawl. Sitemap and crawl imports also produce url rows.

folder_idstring or null

Folder this document lives in. Null for root-level (unfiled) documents. Mutated via the move endpoint.

filenamestring
content_typestring
byte_sizelong
char_countinteger
chunk_countinteger
statusenum

Document lifecycle. fetching is the pre-scrape state used only by url-sourced rows; file and text docs skip straight to embedding because their content is available synchronously. Terminal states are ready and failed.

created_atdatetime
updated_atdatetime
source_urlstring

Source URL for url-sourced documents (and the sitemap / crawl imports that produce them). Empty string for file and text rows.

errorstring
Populated when status is failed.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
413
Content Too Large Error