Knowledge API
Native API for knowledge bases (retrieval-augmented generation): create
knowledge bases, upload documents, search them and export them. Knowledge
events (knowledge.document.ready, …) are delivered by the platform
webhooks — see the Webhooks guide. Grounded chat uses the existing POST /v1/chat/completions with
knowledge_base_ids — see the Chat with citations guide.
Authentication. Authorization: Bearer <API key>. The key must be an
inference key carrying knowledge:read (read and search) or
knowledge:write (everything, including read). Its knowledge-base access
list is enforced on every call. Each operation lists the scope it needs.
Conventions.
- Paths are also accepted with an
/apiprefix (/api/v1/knowledge_bases). - Ids are lower-case hyphenated UUIDs. Timestamps are RFC 3339 UTC
(
2026-09-23T10:00:00Z). - Lists are cursor-paginated:
?limit=(1–100, default 20) and?after=<next_cursor>; responses are{"object":"list","data":[…],"has_more":bool,"next_cursor":string|null}. - Errors use the platform error envelope with a stable
code, plusrequest_id,retryable,retry_after_secondsanddetails. - Every POST that creates work accepts
Idempotency-Key(≤255 characters, kept 24 h per organization and route). Same key and same request → the original response is replayed without new work or charge. Same key with a different request → 409idempotency_key_conflict; original still running → 409idempotency_in_progress. - When knowledge bases are switched off on the platform, an organization
without knowledge bases gets 404
module_disabledon every path. An organization that still has knowledge bases keeps its data read and export only: listing, reading, search and grounded chat (billed as usual), downloads, exports, metadata edits, cancelling and deleting keep working; creating knowledge bases, uploads, file replacements and retries are refused with 403module_disabled. Stored data stays billed until you delete it. Each operation's Access line says whether it stays available.
Default limits (the same for every organization; your effective values
are returned by GET /v1/knowledge_module): file 50 MB; 50 files and
500 MB per upload request; 20 knowledge bases per organization; 1,000
uploaded documents per knowledge base; query 2,000 characters; top_k 1–20; 5
knowledge bases per chat request; 16 metadata keys per document; 100 ids per
batch operation; one running export per knowledge base;
1 hour of processing per document; 50,000 data rows per spreadsheet
(XLSX/CSV) document and 3,000,000 embedding tokens per document — a larger
document fails (extraction_limit_exceeded / processing_limit_exceeded)
instead of being partly indexed.
Website sources. A knowledge base can also index a website (tag Web
sources). Every fetched page becomes an ordinary document (origin: web,
with its URL in source), searched, cited and billed like an upload:
fetching is free, new and changed pages cost processing tokens and storage,
unchanged pages cost nothing. https on port 443 only; robots.txt is always
obeyed; bot protection is never bypassed. Each source holds at most 100
pages on an unverified domain (5,000 on a verified one), and these pages do
not count toward the 1,000 uploaded documents. See the Website Sources
guide.
Metadata. A flat object of at most 16 keys. Key:
^[a-z][a-z0-9_]{0,63}$. Value: string (≤256 characters), finite number,
boolean, or date. A string that parses as an ISO 8601 date (YYYY-MM-DD) or
RFC 3339 date-time is stored and filtered as a date, normalised to
YYYY-MM-DDTHH:MM:SSZ. null, arrays and objects are rejected. Reserved keys
(422 metadata_key_reserved): tenant_id, kb_id, knowledge_base_id,
doc_id, document_id, version_id, chunk_index, page, section,
profile_id, text, owner_type, location, token_count, created_at,
meta, id, and any key starting with _.
Authentication
- HTTP: Bearer Auth
API key (sk-…, inference key type with a knowledge:* scope) or a portal session.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |