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

# Knowledge bases API

> Create knowledge bases, upload documents, and let chat retrieve cited sources over HTTP.

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

```text theme={null}
/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 theme={null}
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",
    "shared": true,
    "default_open": false
  }'
```

`shared` lets other signed-in users read the base. `default_open` attaches it to **your** new chats only. Optional `max_documents` sets the per-base file cap (`0` = unlimited, default `100`).

## Upload a document

```bash theme={null}
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 theme={null}
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, or change default-open |
| `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 |
| `PATCH` | `/knowledge-bases/{kb_id}/documents/{doc_id}` | owner | Rename a file or folder |
| `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` | signed in | 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 a document limit (default **100**; `0` means unlimited). 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.