Skip to main content
Version: 1

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 /api prefix (/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, plus request_id, retryable, retry_after_seconds and details.
  • 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 → 409 idempotency_key_conflict; original still running → 409 idempotency_in_progress.
  • When knowledge bases are switched off on the platform, an organization without knowledge bases gets 404 module_disabled on 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 403 module_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​

API key (sk-…, inference key type with a knowledge:* scope) or a portal session.

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer