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

# Knowledge Bases

> Publish tenant knowledge, link it to agents, and keep retrieval scoped before you send live traffic.

# Ground live answers in published knowledge, not draft notes.

Callaro knowledge bases are tenant-scoped collections of approved sources. Agents can link a **published** knowledge base instead of pasting large custom knowledge text into the prompt.

<Note>
  Knowledge-base CRUD lives on `/api/v1/knowledge-bases` and related source routes. Those families are enforced in the API key permission matrix (`knowledge_bases:read` / `knowledge_bases:write`) but are **not yet fully generated** in public OpenAPI. Use this guide plus the app UI until generated coverage lands.
</Note>

## Recommended rollout

<Steps>
  <Step title="Create a docs-only knowledge base">
    Start with one domain (pricing, eligibility, or office hours). Avoid mixing unrelated policies in the same corpus.
  </Step>

  <Step title="Add sources and wait for processing">
    Upload files or website sources from **Knowledge base**. Confirm each source reaches a ready state before publish.
  </Step>

  <Step title="Publish, then link from the agent">
    In the agent wizard **Prompt & Goals** step, choose a linked published knowledge base instead of unbounded custom text.
  </Step>

  <Step title="Verify on a sandbox call">
    Ask a question that only the knowledge base can answer. Confirm the transcript stays on-policy and does not invent missing facts.
  </Step>
</Steps>

## Scope and billing notes

* Website imports and file-extraction fallback can create **knowledge-base usage events** in tenant billing.
* Linking is typically plan-gated in the product UI. If the card is locked, publish the KB first and confirm the tenant plan includes retrieval.
* Keep sandbox and production knowledge bases isolated. Draft sandbox content must not serve production callers.

## API key scopes

| Scope                          | Use                                         |
| ------------------------------ | ------------------------------------------- |
| `knowledge_bases:read`         | List, show, and read summaries              |
| `knowledge_bases:write`        | Create, update, publish, unpublish, destroy |
| `knowledge_base_sources:read`  | Inspect source status                       |
| `knowledge_base_sources:write` | Add, retry, or discover sources             |
| `agents:write`                 | Link or unlink a knowledge base on an agent |

## Failure modes

| Symptom                                   | Likely cause                              | Fix                                                        |
| ----------------------------------------- | ----------------------------------------- | ---------------------------------------------------------- |
| Agent still answers from prompt text only | KB is draft or not linked                 | Publish the KB, then relink on **Prompt & Goals**.         |
| Retrieval feels noisy                     | Overlapping or stale sources              | Remove duplicates and keep one source of truth per policy. |
| Import cost surprise                      | Website crawl or file-extraction fallback | Review **Usage** events before expanding the corpus.       |

## What to do next

* Review the product concept page [`../concepts/knowledge-retrieval`](../concepts/knowledge-retrieval).
* Review Help Center article [Knowledge bases](https://help.callaro.ai) after Help Scout publish.
* Track generated-spec progress on [`../api-reference/openapi-coverage-status`](../api-reference/openapi-coverage-status).