> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# Knowledge bases API

Use the Knowledge Bases API to create document collections that agents search in chat. Most people should start from the [web UI](/en/guide/concepts/knowledge.md); this page is for automating the same flow.

```text
/api/knowledge-bases
```

Anyone signed in can list bases they own or that are **Shared**. Creating, uploading, and deleting require that you own the base (administrators can manage any base). An administrator must enable knowledge bases in the web UI before indexing works.

## Create a knowledge base

```bash
curl -X POST http://127.0.0.1:8088/api/knowledge-bases \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Team handbook",
    "description": "Onboarding docs",
    "max_documents": 500,
    "shared": true,
    "default_open": false
  }'
```

`shared` lets other signed-in users read the base. `default_open` attaches it to **your** new chats only. `max_documents` sets this base's document limit. Omit it for the default **100**, set `0` for no per-base limit, or choose any value up to **10000**.

## Upload a document

```bash
curl -X POST http://127.0.0.1:8088/api/knowledge-bases/<kb_id>/documents \
  -H 'Authorization: Bearer $TOKEN' \
  -F 'upload=@handbook.pdf'
```

Supported files: text (`.md`, `.txt`, `.rst`, `.html`, `.json`, `.jsonl`, `.yaml`, `.csv`, `.tsv`), spreadsheets (`.xls`, `.xlsx`, `.xlsm`), plus `.pdf`, `.docx`, `.pptx`. With OCR enabled, also `.png`, `.jpg`, `.jpeg`, `.webp` and scanned PDFs. Indexing starts after the upload. The response includes upload progress while the file is accepted.

To create markdown or text without uploading a file:

```bash
curl -X POST http://127.0.0.1:8088/api/knowledge-bases/<kb_id>/documents/text \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "notes",
    "format": "md",
    "content": "# Welcome\n\nTeam handbook goes here."
  }'
```

## Knowledge bases

| Method   | Path                            | Who can call it | What it does                                                  |
| -------- | ------------------------------- | --------------- | ------------------------------------------------------------- |
| `GET`    | `/knowledge-bases`              | signed in       | List bases you can see                                        |
| `POST`   | `/knowledge-bases`              | owner           | Create a base                                                 |
| `GET`    | `/knowledge-bases/default-open` | signed in       | IDs of bases that open in your new chats                      |
| `GET`    | `/knowledge-bases/{kb_id}`      | signed in       | Get one base                                                  |
| `PATCH`  | `/knowledge-bases/{kb_id}`      | owner           | Rename, share, change default-open, or change `max_documents` |
| `DELETE` | `/knowledge-bases/{kb_id}`      | owner           | Delete a base                                                 |

## Documents and folders

| Method   | Path                                                  | Who can call it | What it does                                                                                                                                                                                           |
| -------- | ----------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET`    | `/knowledge-bases/{kb_id}/documents`                  | signed in       | List files and folders                                                                                                                                                                                 |
| `POST`   | `/knowledge-bases/{kb_id}/documents`                  | owner           | Upload a file                                                                                                                                                                                          |
| `POST`   | `/knowledge-bases/{kb_id}/documents/text`             | owner           | Create a markdown or text file                                                                                                                                                                         |
| `POST`   | `/knowledge-bases/{kb_id}/folders`                    | owner           | Create a folder                                                                                                                                                                                        |
| `POST`   | `/knowledge-bases/{kb_id}/documents/{doc_id}/rename`  | owner           | Rename a file or folder (`new_name`)                                                                                                                                                                   |
| `POST`   | `/knowledge-bases/{kb_id}/documents/{doc_id}/move`    | owner           | Move a file or folder (`target_folder`; empty means the root). A folder moves with its contents. Moving into itself returns `KNOWLEDGE_MOVE_INVALID`. A name clash returns `KNOWLEDGE_MOVE_NAME_TAKEN` |
| `GET`    | `/knowledge-bases/{kb_id}/documents/{doc_id}/preview` | signed in       | Preview in the original layout                                                                                                                                                                         |
| `GET`    | `/knowledge-bases/{kb_id}/documents/{doc_id}/file`    | signed in       | Download the original (`Content-Disposition: attachment`) or inline preview                                                                                                                            |
| `GET`    | `/knowledge-bases/{kb_id}/documents/{doc_id}/content` | owner           | Read text content                                                                                                                                                                                      |
| `PUT`    | `/knowledge-bases/{kb_id}/documents/{doc_id}/content` | owner           | Save an in-page text edit (re-indexes)                                                                                                                                                                 |
| `DELETE` | `/knowledge-bases/{kb_id}/documents/{doc_id}`         | owner           | Delete a file or folder                                                                                                                                                                                |

Each owner can create up to **20** bases. Each base has its own document limit: the default is **100**, `0` means unlimited, and the maximum accepted value is **10000**. Upload size follows the server file-size cap (default **100** MB).

## Enable indexing (administrators)

Turn the feature on in **Knowledge Bases → Knowledge base settings**, or call these routes after you pick a local or online embedding model:

| Method | Path                                    | What it does                                                     |
| ------ | --------------------------------------- | ---------------------------------------------------------------- |
| `GET`  | `/knowledge-bases/capability`           | Whether the feature is on and ready                              |
| `GET`  | `/knowledge-bases/embedding-options`    | Available local and online models                                |
| `PUT`  | `/knowledge-bases/feature`              | Enable or disable knowledge bases (can set OCR at the same time) |
| `GET`  | `/knowledge-bases/ocr-options`          | List OCR backends (local RapidOCR / online vision models)        |
| `POST` | `/knowledge-bases/onnx-download`        | Download a local model                                           |
| `GET`  | `/knowledge-bases/onnx-download-status` | Download progress                                                |
| `POST` | `/knowledge-bases/onnx-activate`        | Switch to a downloaded local model                               |
