Create a Knowledge Base

Knowledge bases let your AI agents 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)

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}")

const response = await fetch(`${BASE_URL}/api/knowledge-bases`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Product Docs",
    description: "Product documentation and guides",
  }),
});
const kb = await response.json();
console.log("KB created:", kb.id);

curl -X POST '{BASE_URL}/api/knowledge-bases' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Product Docs", "description": "Product documentation and guides"}'

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 via context_mode: "image") all live inside retrieval_config. Turn them on here at creation, or add them later with PATCH /api/knowledge-bases/{id} (no reindex required).

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())

const response = await fetch(
  `${BASE_URL}/api/knowledge-bases/${kbId}/sources`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({ source_id: sourceId }),
  },
);
console.log(await response.json());

curl -X POST '{BASE_URL}/api/knowledge-bases/{kb_id}/sources' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"source_id": "{source_id}"}'

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']}")

const res = await fetch(`${BASE_URL}/api/knowledge-bases/${kbId}`, { headers });
const kb = await res.json();
kb.indexed_sources?.forEach((s: any) =>
  console.log(`Source ${s.source_id}: ${s.index_status}`)
);

curl '{BASE_URL}/api/knowledge-bases/{kb_id}' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}"

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]}...")

const res = await fetch(`${BASE_URL}/api/knowledge-bases/${kbId}/search`, {
  method: "POST",
  headers,
  body: JSON.stringify({ query: "How do I get started?", top_k: 5 }),
});
const { results } = await res.json();
results.forEach((r: any) => console.log(`Score: ${r.score} — ${r.text.slice(0, 80)}...`));

curl -X POST '{BASE_URL}/api/knowledge-bases/{kb_id}/search' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I get started?", "top_k": 5}'

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.

​What’s Next

Build an Agent

Knowledge Bases & Indexing

Knowledge Bases API Reference

What’s Next