Skip to main content
Knowledge bases give your AI agents the ability to search and retrieve relevant information from your documents. This guide walks through creating a KB, adding a source, waiting for indexing, and testing semantic search.
Prerequisites:
  • A completed source (see Upload a Document guide)
1

Create the knowledge base

Choose a name and indexing strategy. The default strategy works well for most documents.Endpoint: POST /api/knowledge-bases
response = requests.post(
    f"{BASE_URL}/api/knowledge-bases",
    headers=headers,
    json={
        "name": "Product Docs",
        "description": "Product documentation and guides",
    },
)
kb = response.json()
kb_id = kb["id"]
print(f"KB created: {kb_id}")
Response:
{
  "id": "kb-uuid",
  "name": "Product Docs",
  "description": "Product documentation and guides",
  "indexing_config": {
    "strategy": "chunk_embed",
    "...": "strategy defaults"
  },
  "retrieval_config": {
    "...": "strategy defaults"
  }
}
If you pass indexing_config or retrieval_config in the request, your values are merged over the strategy defaults. Omit either field to accept the defaults for strategy (default chunk_embed).
The retrieval features — reranking, query enrichment, and multimodal retrieval (context_mode: "image") — all live inside retrieval_config, so you can turn them on here at creation or add them later with PATCH /api/knowledge-bases/{id} (no reindex required).
2

Add a source to the knowledge base

Link an uploaded source (from the previous guide) to trigger indexing. The source’s extracted content is chunked, embedded, and stored.Endpoint: POST /api/knowledge-bases/{id}/sources
Indexing runs asynchronously. For large documents this can take 30 seconds or more.
response = requests.post(
    f"{BASE_URL}/api/knowledge-bases/{kb_id}/sources",
    headers=headers,
    json={"source_id": source_id},
)
print(response.json())
3

Check indexing status

Fetch the knowledge base to see the status of each indexed source. Wait until all sources show ‘indexed’.Endpoint: GET /api/knowledge-bases/{id}
response = requests.get(
    f"{BASE_URL}/api/knowledge-bases/{kb_id}",
    headers=headers,
)
kb = response.json()
for src in kb.get("indexed_sources", []):
    print(f"Source {src['source_id']}: {src['index_status']}")
4

Test search

Run a semantic search query against the knowledge base to verify indexing worked.Endpoint: POST /api/knowledge-bases/{id}/search
response = requests.post(
    f"{BASE_URL}/api/knowledge-bases/{kb_id}/search",
    headers=headers,
    json={"query": "How do I get started?", "top_k": 5},
)
results = response.json()
for r in results.get("results", []):
    print(f"Score: {r['score']:.3f} — {r['text'][:80]}...")

​
What’s Next

Build an Agent

Create an agent that uses your knowledge base.

Knowledge Bases & Indexing

Deep dive into chunking and embeddings.

Knowledge Bases API Reference

Full endpoint documentation.