Skip to main content
A knowledge base is a searchable document library with its own category taxonomy. Where memory captures what happened in a conversation, a knowledge base holds the material an agent needs to consult — a handbook, a spec, a policy — broken into topics an LLM extracted from it. Both live behind the same API key and the same base URL.

​
How a document becomes searchable

1

Create a knowledge base

2

Ingest a document

content takes inline text, or a file you uploaded first (see Multimodal).
Ingest is always asynchronous. The call answers 202 with a task_id, and the document id is minted downstream — so the ack does not carry one.
3

Wait for it to be processed

task_wait polls until the task reaches a terminal state, backs off between polls, rides out a transient rate limit, and raises if the task fails or outlives the timeout. Pass raise_on_failure=False to inspect a failure instead of raising.
4

Find the document

The ingest ack has no document id, so resolve it by title once the task finishes.
topic_count greater than 0 is the authoritative signal that ingest finished — a document row can exist before its topics do.
5

Search it

​
What comes back

The unit of retrieval is the topic, not the document. Each hit carries its parent document’s title and summary, so a result list needs no follow-up request. Topic bodies are omitted by default. Ask for them when you actually need the text:
Results can include the document-root topic — depth 0, the document’s own title. It is a container, not a section, so its content is always null even with include=["content"]. Skip hits whose depth is 0 if you only want real sections.
Or read one topic directly:
The topic list includes one synthetic document-root item (type is "root"), so it returns exactly one more entry than the document’s topic_count, which counts real topics only. Build the tree from each item’s parent_id.

​
Reading the score

hit.score is not a raw keyword or vector score. Every retrieval method reranks its candidates with a cross-encoder and then normalizes within that response, so:
  • scores compare inside one response, never across responses or queries;
  • the best hit of any response sits near the top of the range by construction, however weak the pool actually is;
  • score_threshold therefore cuts a relative position, not an absolute relevance bar.
Tune a threshold against real results rather than from a BM25 or cosine intuition.

​
Categories

A category is a bucket a document is filed under. A new knowledge base starts with none, so until you create some, every document stays uncategorized (category_id comes back as an empty string) and the classifier has nothing to choose from.
With categories in place, ingest classifies each document into one of them — pass category_id on the upload to pin it instead. A category’s description is not decoration: it is what the classifier matches a document against. Re-file a document at any time:
Deleting a category does not delete its documents — they, and their topics, are reassigned to uncategorized first.

​
Maintenance

To change a document’s content, re-ingest it under the same id with client.knowledge.replace_document(...) — the swap is atomic and idempotent per document id.

​
What’s next

Multimodal support

Upload a PDF or an image first, then ingest it by object key.

API Reference

Every knowledge-base operation, with parameters and responses.