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

# Knowledge Base

> Give agents retrieval-augmented answers from your own Q&A content.

A **knowledge base** lets an agent answer from your content instead of guessing. Documents are embedded and stored for vector search. During a call the agent retrieves the most relevant entries and uses them to ground its reply.

## The model

A knowledge base is a **named entity in your workspace**, created and filled independently of any agent. An [agent](/concepts/agents) points at one through `knowledge_base_id`:

* **One knowledge base per agent.** An agent retrieves from exactly the KB it is bound to — nothing is shared implicitly across KBs.
* **Many agents per knowledge base.** Several agents can share one KB, so the same content doesn't need re-ingesting per agent.
* The agent applies a **confidence threshold** (default 80%) and ignores low-scoring matches.
* Names are unique within a workspace; creating a duplicate returns `409`.

## Manage knowledge bases

| Method | Path                    | Scope                  | Notes                                                                                                 |
| ------ | ----------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------- |
| GET    | `/knowledge-bases`      | `knowledge_base:read`  | List. `document_count` is `null` unless you pass `?include_counts=true` (an extra round-trip per KB). |
| POST   | `/knowledge-bases`      | `knowledge_base:write` | `name` (required), `description?`. Returns `201`.                                                     |
| PATCH  | `/knowledge-bases/{id}` | `knowledge_base:write` | Rename or re-describe.                                                                                |
| DELETE | `/knowledge-bases/{id}` | `knowledge_base:write` | Removes the KB and its documents.                                                                     |

## Manage documents

| Method | Path                     | Scope                  | Notes                                                                                        |
| ------ | ------------------------ | ---------------------- | -------------------------------------------------------------------------------------------- |
| GET    | `/knowledge-base`        | `knowledge_base:read`  | List documents; `knowledge_base_id?` (omit for every document in the workspace).             |
| POST   | `/knowledge-base/ingest` | `knowledge_base:write` | Upload a file (multipart); `knowledge_base_id` **required**, `mode` = `replace` \| `append`. |
| POST   | `/knowledge-base/search` | `knowledge_base:read`  | Query: `query`, `knowledge_base_id` **required**, `top_k?`.                                  |
| DELETE | `/knowledge-base`        | `knowledge_base:write` | Delete documents in a knowledge base.                                                        |

<Note>
  Ingest and search are scoped by `knowledge_base_id`, not `agent_id`. Retrieval is exact-per-KB: searching one knowledge base never returns another's entries.
</Note>

## Search shape

`POST /knowledge-base/search` returns ranked Q\&A matches:

```json theme={null}
{
  "data": [
    { "id": "kbdoc_01EXAMPLE", "question": "What is the refund window?", "response": "30 days from delivery.", "knowledge_base_id": "kb_01EXAMPLE", "match_percentage": 92 }
  ]
}
```

Use `match_percentage` to decide how much to trust a result; the agent already filters below its threshold during live calls.

<Note>
  The knowledge base requires a **Vector Store** to be configured on the deployment. When it isn't, KB features are disabled and search returns a service-unavailable response — calls still work, just without retrieval.
</Note>

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/concepts/agents">Attach a KB to an agent.</Card>
  <Card title="Sessions" icon="phone" href="/concepts/sessions">Retrieval happens mid-call.</Card>
</CardGroup>