Skip to main content
A knowledge base document holds the content an agent retrieves from during a conversation. Documents come in three flavors:
  • Text — raw text you provide directly. Best for brand voice, short reference docs, or pasted content.
  • File — uploaded files (PDF, DOCX, EPUB, TXT, MD, HTML). The server extracts text, chunks it, and embeds the chunks for vector similarity retrieval.
  • URL — a public web page or document. The server fetches it, extracts text, and ingests it the same way as a file.
Every document carries:
  • A stable id like kndoc_<cuid2> (we diverge from ElevenLabs’s bare-UUID convention to keep IDs prefixed and self-describing).
  • A name (display title, defaults to the first line of text / the uploaded filename / the page <title>).
  • A folder_path describing where the doc lives in your knowledge base’s folder tree (root-first ancestor chain by ID + name).
  • metadata.size_bytes (the doc’s raw text size in bytes), plus ISO-8601 created_at and updated_at timestamps.
  • A type of text, file, or url.
  • A status of pending, processing, ready, or failed. A document only becomes retrievable via search and /chunks once it reaches ready. Documents created through the API today stay pending until a follow-up wires up server-side chunk + embed indexing (the existing path that runs from the Knowledge Base UI is not yet shared with the API).

​
Creating documents

Three POST endpoints:
  • POST /v1/knowledge-base/documents/from-text — JSON body with text, optional name and folder_id.
  • POST /v1/knowledge-base/documents/from-file — multipart form with a file field (max 25 MB), plus optional name and folder_id. Currently returns 501 Not Implemented. The route shape is stable but the server-side file-ingestion pipeline (PDF/DOCX/EPUB/TXT extraction + blob storage + chunking) ships in a follow-up. Use the Knowledge Base UI to upload files in the meantime.
  • POST /v1/knowledge-base/documents/from-url — JSON body with url (http(s) only), optional name and folder_id. The server fetches the URL, validates safety (SSRF guard, size cap, content-type allow-list), and extracts text.
All three return the full document object.

​
Reading documents

  • GET /v1/knowledge-base/documents — paginated list with optional filters (folder_id, ids for batch-get, types, search). Cursor pagination via the opaque cursor query param.
  • GET /v1/knowledge-base/documents/:id — full document object.
  • GET /v1/knowledge-base/documents/:id/content — raw text as text/plain.
  • GET /v1/knowledge-base/documents/:id/chunks — paginated chunks of the doc after splitting + embedding.
  • GET /v1/knowledge-base/documents/:id/chunks/:chunkId — one chunk by ID.
  • GET /v1/knowledge-base/documents/:id/source-file-url — pre-signed URL (or redirect) to the doc’s blob storage entry.
  • GET /v1/knowledge-base/documents/:id/agents — agents that depend on this document.

​
Updating documents

  • PATCH /v1/knowledge-base/documents/:id — rename and/or move to a different folder. Body: { name?, folder_id? }. Pass folder_id: null to move to root.
  • PATCH /v1/knowledge-base/documents/:id/file — replace the source file for a file-typed document. Re-chunks and re-embeds transactionally. Returns 400 for non-file-typed docs. Currently returns 501 Not Implemented alongside POST /from-file (same follow-up).
  • POST /v1/knowledge-base/documents/:id/refresh — re-fetches the source URL for a URL-typed document, re-extracts text, replaces chunks. Returns 400 for non-URL-typed docs.

​
Deleting documents

  • DELETE /v1/knowledge-base/documents/:id — hard delete. Chunks are cascade-deleted via the database constraint; any agent attachments through this document are also cleaned up.

​
Searching

  • GET /v1/knowledge-base/search — vector similarity search over the org’s indexed chunks. Returns documents sorted by relevance with a score (0-1, higher is better) and a search_snippet (the matched chunk content, trimmed to 300 chars). Filters: types.

​
Stats

  • GET /v1/knowledge-base/size — { size_bytes, document_count, chunk_count } for the org’s knowledge base.

​
Differences from ElevenLabs

Three documented divergences, surfaced explicitly:
  1. ID format — kndoc_<cuid2> instead of bare UUID. Our convention prefixes every entity ID with a short type marker for log readability and forwards-compat with multi-tenant routing.
  2. Timestamps — ISO-8601 strings ("2026-05-21T11:00:00.000Z") instead of *_unix_secs integers. Easier to read; standard for modern API consumers.
  3. access_info omitted — ElevenLabs returns a per-document access_info object. We don’t have per-document ACLs — organisations are the access boundary — so we omit the field rather than return a misleading stub.
And one diverged endpoint:
  • GET /v1/knowledge-base/size returns { size_bytes, document_count, chunk_count }. ElevenLabs’s equivalent returns { number_of_pages } (a tokens/pages metric specific to their billing model). We expose the underlying real units.