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

# Knowledge Bases

> Upload your content — docs, FAQs, policies — so your agent can answer questions from it during calls.

## How it works

<Note>
  You don't need to create a knowledge base manually. Adding content (a URL, file, or text) automatically creates one for you and returns its ID.
</Note>

Uploaded content is indexed and retrieved automatically during calls — no configuration needed.

Supported file types: PDF, Excel, and Word documents. Maximum file size: 20 MB.

***

## Quick start — add content in one call

You can skip creating a knowledge base ID manually. `POST /v1/knowledge-bases/sources` (without a `kb_id` in the path) auto-creates a new knowledge base named after your source and starts ingestion immediately. The response gives you the `knowledge_base_id` — save it for attaching to your agent.

### Add a URL

Provide any public URL — a docs page, FAQ, blog post, or product page. OneInbox fetches the page and indexes its content automatically.

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/knowledge-bases/sources \
  -H "Authorization: Bearer <api_key>" \
  -F "type=url" \
  -F "source=https://docs.yourproduct.com/faq"
```

### Upload a file

Upload a document directly. Supported formats: PDF, Excel, and Word documents. Use the `file` field only — do not include a `type` field when uploading a file.

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/knowledge-bases/sources \
  -H "Authorization: Bearer <api_key>" \
  -F "file=@/path/to/your-document.pdf"
```

### Add inline text

Paste content directly as plain text — useful for policies, scripts, FAQs, or any text you already have on hand.

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/knowledge-bases/sources \
  -H "Authorization: Bearer <api_key>" \
  -F "type=text" \
  -F "source=Our refund policy is 30 days. Customers must provide proof of purchase to receive a refund."
```

All three endpoints return the same response structure:

```json theme={null}
{
  "knowledge_base_id": "kb_abc123",
  "source": { "id": "kbs_xyz", "status": "processing" },
  "job": { "id": "kbj_xyz", "status": "queued" }
}
```

* **`knowledge_base_id`** — the ID of the auto-created knowledge base. Save this — you'll use it in Step 3 to attach the KB to your agent.
* **`source.id`** — the individual content source that was added.
* **`job.id`** — the processing job. Poll this to track indexing progress.

The KB is named after the URL domain or file name.

***

## Step 2 — Check processing status

Content is indexed asynchronously. Wait for the job to complete before attaching the KB to your agent — the agent can only use content that has finished processing.

```bash theme={null}
# List all jobs for this KB
curl https://api.oneinbox.ai/v1/knowledge-bases/<kb_id>/jobs \
  -H "Authorization: Bearer <api_key>"

# Get a specific job
curl https://api.oneinbox.ai/v1/knowledge-bases/<kb_id>/jobs/<job_id> \
  -H "Authorization: Bearer <api_key>"
```

Jobs follow this sequence: `queued` → `running` → `completed` or `failed`

Wait for `"status": "completed"` before moving to Step 3.

***

## Step 3 — Attach to your LLM model

This is the step that makes the knowledge base available to your agent. Attach it to the LLM model (not the agent directly). `llm_id` is returned when you create an agent — if you don't have it, fetch it with `GET /v1/agents/<agent_id>`.

```bash theme={null}
curl -X PATCH https://api.oneinbox.ai/v1/models/<llm_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_base_ids": ["<kb_id>"]
  }'
```

Every agent using this LLM model now has access to the knowledge base. To attach multiple knowledge bases at once:

```bash theme={null}
{ "knowledge_base_ids": ["kb_abc123", "kb_def456"] }
```

***

## Manage knowledge bases

### List all knowledge bases

Retrieve all knowledge bases in your account. Useful for finding `kb_id` values or auditing what content your agents have access to.

```bash theme={null}
curl https://api.oneinbox.ai/v1/knowledge-bases \
  -H "Authorization: Bearer <api_key>"
```

### List sources in a knowledge base

See all the individual content sources (URLs, files, inline text) that have been added to a specific KB.

```bash theme={null}
curl https://api.oneinbox.ai/v1/knowledge-bases/<kb_id>/sources \
  -H "Authorization: Bearer <api_key>"
```

### Delete a source

Remove a single source from the KB along with its vector chunks and stored file. Get the `source_id` from the list sources endpoint above.

```bash theme={null}
curl -X DELETE "https://api.oneinbox.ai/v1/knowledge-bases/<kb_id>/sources/<source_id>" \
  -H "Authorization: Bearer <api_key>"
```

### Update a knowledge base

Rename a KB, change its chunk size, or toggle multilingual mode. Chunk size changes take effect on the next source processed — existing content is not re-indexed automatically.

```bash theme={null}
curl -X PATCH https://api.oneinbox.ai/v1/knowledge-bases/<kb_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product Docs v2", "chunk_size": 1024, "multilingual": true }'
```

| Field          | What it does                                                                              |
| -------------- | ----------------------------------------------------------------------------------------- |
| `name`         | Rename the KB                                                                             |
| `chunk_size`   | Token size per chunk — smaller = more precise retrieval, larger = more context per result |
| `multilingual` | `true` enables cross-language retrieval (content in one language, query in another)       |

### Delete a knowledge base

Permanently removes the KB and all its indexed content. If the KB is attached to an LLM model, it will no longer be available to those agents after deletion.

```bash theme={null}
curl -X DELETE https://api.oneinbox.ai/v1/knowledge-bases/<kb_id> \
  -H "Authorization: Bearer <api_key>"
```

***

## API reference

[Add source (auto-create KB)](/api-reference/knowledge-bases/add-knowledge-base-source-auto-create) · [Add source](/api-reference/knowledge-bases/add-knowledge-base-source) · [List jobs](/api-reference/knowledge-bases/list-knowledge-base-jobs)