Skip to main content
A knowledge base grows with your product. Three ways to add documents:

​
Creating documents

From text — paste reference content directly. Best for short docs you author in-house: brand voice, FAQs, persona definitions, escalation scripts. From a file — upload PDFs, Word docs, EPUBs, HTML, Markdown, or plain text. The server extracts the text, chunks it, and indexes it for retrieval. The original file stays accessible via the document’s source-file URL. From a URL — link to a public webpage. The server fetches the page, extracts text, and ingests it. Use the Refresh action later to re-ingest if the source page changes.

​
Organizing with folders

Documents live in folders (or at the root). Use the Move to folder action — either from a single document’s row menu or in bulk by selecting multiple documents and using the toolbar. See the Folders guide for the folder model.

​
Refreshing URL-typed documents

A URL-typed document was fetched once at creation. To pull the latest content from the source URL:
  • API: POST /v1/knowledge-base/documents/:id/refresh
  • Dashboard: open the document and choose Refresh.
The refresh is transactional — the previous content + chunks aren’t removed until the new content is fully ingested. Refresh on a text- or file-typed document is rejected with a 400.

​
Replacing a file

When you have a newer version of a file-typed document:
  • API: PATCH /v1/knowledge-base/documents/:id/file (multipart with file).
  • Dashboard: open the document and choose Replace file.
Same transactional semantics as refresh.

​
Searching

Vector similarity search over your KB’s indexed chunks:
  • API: GET /v1/knowledge-base/search?query=<your query>
  • Returns documents sorted by relevance with a snippet of the matched text.
  • Filter by document type with types=text etc.
Search is the same mechanism that powers per-turn agent retrieval — if search returns the right docs, your agents will too.

​
Inspecting chunks

Chunks are the units of retrieval. To inspect what an agent actually sees when it fetches context from a document:
  • GET /v1/knowledge-base/documents/:id/chunks — paginated.
  • GET /v1/knowledge-base/documents/:id/chunks/:chunkId — single chunk with character_start/character_end positions in the source text.

​
Knowing which agents use a document

GET /v1/knowledge-base/documents/:id/agents lists every agent in your organization that depends on this document. Useful before you delete or replace it.