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; this page is for automating the same flow.

/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

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

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:

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