> ## 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)
</Note>

<Steps>
  <Step title="Create the knowledge base">
    Choose a name and indexing strategy. The default strategy works well for most documents.

    **Endpoint:** `POST /api/knowledge-bases`

    <CodeGroup>
      ```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"}'
      ```
    </CodeGroup>

    **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](/concepts/knowledge-bases-indexing#reranking), [query enrichment](/concepts/knowledge-bases-indexing#query-enrichment), and [multimodal retrieval](/concepts/knowledge-bases-indexing#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).
    </Tip>
  </Step>

  <Step title="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.
    </Note>

    <CodeGroup>
      ```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}"}'
      ```
    </CodeGroup>
  </Step>

  <Step title="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}`

    <CodeGroup>
      ```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}"
      ```
    </CodeGroup>
  </Step>

  <Step title="Test search">
    Run a semantic search query against the knowledge base to verify indexing worked.

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

    <CodeGroup>
      ```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}'
      ```
    </CodeGroup>
  </Step>
</Steps>

## What's Next

<CardGroup cols={2}>
  <Card title="Build an Agent" href="/guides/build-agent">
    Create an agent that uses your knowledge base.
  </Card>

  <Card title="Knowledge Bases & Indexing" href="/concepts/knowledge-bases-indexing">
    Deep dive into chunking and embeddings.
  </Card>

  <Card title="Knowledge Bases API Reference" href="/api-reference/knowledge-bases">
    Full endpoint documentation.
  </Card>
</CardGroup>