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; 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",
    "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

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

#Documents and folders

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: