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

kb_idstringRequired

Knowledge base id (prefixed external id, kb_...).

Headers

Speechify-VersionstringOptional

Request

This endpoint expects a multipart form containing a file.

filefileRequired

Response headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

The ingested document record.

idstringformat: "^doc_[0-9a-hjkmnp-tv-z]{26}$"

kb_idstringformat: "^kb_[0-9a-hjkmnp-tv-z]{26}$"

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 nullformat: "^kfolder_[0-9a-hjkmnp-tv-z]{26}$"

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

$	curl -X POST https://api.speechify.ai/v1/agents/knowledge-bases/kb_01jqr8x9zg5k2m3n4p5q6r7s8t/documents \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: multipart/form-data" \
>	-F file=@string

1	{
2	"id": "doc_01knthz1d4v2bn8y9wz5ewjagk",
3	"kb_id": "kb_01jqr8x9zg5k2m3n4p5q6r7s8t",
4	"source_kind": "file",
5	"folder_id": "kfolder_01jqr8x9zg5k2m3n4p5q6r7s8t",
6	"filename": "example",
7	"content_type": "example",
8	"byte_size": 1,
9	"char_count": 10,
10	"chunk_count": 10,
11	"status": "fetching",
12	"created_at": "2026-06-24T18:03:11Z",
13	"updated_at": "2026-06-24T18:03:11Z",
14	"source_url": "example",
15	"error": "example"
16	}