> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powabase.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Knowledge Base

> Index your documents for semantic search and retrieval-augmented generation. Knowledge bases chunk, embed, and store your content for fast vector similarity search.

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.

> [!NOTE]
>
> **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`

```python Python theme={null}
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}")
```

```typescript TypeScript theme={null}
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);
```

```bash cURL theme={null}
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:**

```json theme={null}
{
  "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`).

> [!TIP]
>
> The retrieval features ([reranking](https://docs.powabase.ai/concepts/knowledge-bases-indexing.md#reranking), [query enrichment](https://docs.powabase.ai/concepts/knowledge-bases-indexing.md#query-enrichment), and [multimodal retrieval](https://docs.powabase.ai/concepts/knowledge-bases-indexing.md#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).

**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`

> [!NOTE]
>
> Indexing runs asynchronously. For large documents this can take 30 seconds or more.

```python Python theme={null}
response = requests.post(
    f"{BASE_URL}/api/knowledge-bases/{kb_id}/sources",
    headers=headers,
    json={"source_id": source_id},
)
print(response.json())
```

```typescript TypeScript theme={null}
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());
```

```bash cURL theme={null}
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}"}'
```

**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}`

```python Python theme={null}
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']}")
```

```typescript TypeScript theme={null}
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}`)
);
```

```bash cURL theme={null}
curl '{BASE_URL}/api/knowledge-bases/{kb_id}' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}"
```

**4. Test search**

Run a semantic search query against the knowledge base to verify indexing worked.

**Endpoint:** `POST /api/knowledge-bases/{id}/search`

```python Python theme={null}
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]}...")
```

```typescript TypeScript theme={null}
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)}...`));
```

```bash cURL theme={null}
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

> [card] [Build an Agent](https://docs.powabase.ai/guides/build-agent.md)
>
> Create an agent that uses your knowledge base.

> [card] [Knowledge Bases & Indexing](https://docs.powabase.ai/concepts/knowledge-bases-indexing.md)
>
> Deep dive into chunking and embeddings.

> [card] [Knowledge Bases API Reference](https://docs.powabase.ai/api-reference/knowledge-bases.md)
>
> Full endpoint documentation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.