Knowledge Base API

Knowledge base resource endpoints have a base path of /api/v1/knowledge-bases. All endpoints require an authenticated JWT user session; API-key authentication is not accepted.

Required Scopes

Endpoint Overview

Knowledge Base Management

List Knowledge Bases

GET /api/v1/knowledge-bases

Query parameters:

include_shared only adds KBs whose visibility is team or public and that have been shared with the caller's teams; with own_only=true no shared KBs are merged in. Because the default is true, "list knowledge bases" returns both owned and shared KBs — use is_owned to tell them apart.

curl -X GET "https://your-domain.com/api/v1/knowledge-bases?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Each KB object in data.items contains id, name, description, icon, team, created_by, status, visibility, embedding_model_id, embedding_model, rerank_model_id, rerank_model, embedding_dimension, document_count, total_chunks, total_tokens, created_at, plus share metadata:

The response is wrapped in the items/total/page/page_size pagination structure.

Get Knowledge Base Details

GET /api/v1/knowledge-bases/{kb_id}

Returns a single KB with additional settings and updated_at fields. The settings object contains chunk_size, chunk_overlap, rerank_enabled, rerank_candidate_k, search_mode, top_k, score_threshold.

Create Knowledge Base

POST /api/v1/knowledge-bases

Request fields:

curl -X POST "https://your-domain.com/api/v1/knowledge-bases" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation",
    "description": "Product docs and FAQs",
    "team_id": "team-123",
    "embedding_model_id": "model-emb-01",
    "settings": {"chunk_size": 1000}
  }'

Update Knowledge Base

PUT /api/v1/knowledge-bases/{kb_id}

All fields are optional; include only the fields you want to update: name, description, icon, settings.

Delete Knowledge Base

DELETE /api/v1/knowledge-bases/{kb_id}

Successful response has data: null and msg: "Knowledge base deleted successfully".

Document Management

Upload Document

POST /api/v1/knowledge-bases/{kb_id}/documents/upload

Content-Type is multipart/form-data; the file field is required. Supports .pdf, .docx, .txt, .md, etc.

curl -X POST "https://your-domain.com/api/v1/knowledge-bases/{kb_id}/documents/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf"

After upload, the document status is pending; you must call a process endpoint to begin embedding.

Import URL

POST /api/v1/knowledge-bases/{kb_id}/documents/url

Request body:

{"name": "Page Title", "source_url": "https://example.com/page", "doc_type": "url"}

List Documents

GET /api/v1/knowledge-bases/{kb_id}/documents

Query parameters:

Get Document Details

GET /api/v1/knowledge-bases/{kb_id}/documents/{document_id}

Returns full document info including uploaded_by, processed_at, etc.

Download and Document Media

GET /api/v1/knowledge-bases/{kb_id}/documents/{doc_id}/download

Returns the original file's binary content (with Content-Disposition; the filename matches the document name).

GET /api/v1/knowledge-bases/{kb_id}/documents/{doc_id}/media/{filename}

Returns media extracted during document parsing (such as images embedded in docx or Markdown). The body is binary with a type-appropriate Content-Type (for example image/png or image/jpeg). {filename} must be one of the filenames produced by that document's parsing. Both endpoints require kb:read.

Update Document

PUT /api/v1/knowledge-bases/{kb_id}/documents/{document_id}

Only the document name can be updated:

{"name": "Updated Title.pdf"}

Delete Document

DELETE /api/v1/knowledge-bases/{kb_id}/documents/{document_id}

Successful response has data: null.

Document Processing Lifecycle

Uploading a document creates it with status: "pending"; upload does not process it automatically. The processing flow is: pending → processing → completed (or error).

Process a Pending Document

POST /api/v1/knowledge-bases/{kb_id}/documents/{document_id}/process

Optional JSON body:

{"chunk_size": 1000, "chunk_overlap": 100, "separator": null, "clean_text": true}

Returns 200 OK with the document object, normally transitioning to processing before asynchronous embedding completes.

Process with Edited Chunks

POST /api/v1/knowledge-bases/{kb_id}/documents/{document_id}/process-with-chunks

Request body contains custom chunks:

{"chunks": [{"content": "A chunk of text", "chunk_index": 0}]}

This replaces the document chunks and starts embedding.

Preview Chunks

POST /api/v1/knowledge-bases/{kb_id}/documents/{document_id}/preview-chunks

Requires kb:read scope. Body accepts chunk_size (minimum 100), chunk_overlap, optional separator, and clean_text. Response contains total_chunks, total_tokens, total_chars, and chunks array.

Reprocess and Retry

POST /api/v1/knowledge-bases/{kb_id}/documents/{doc_id}/reprocess
POST /api/v1/knowledge-bases/{kb_id}/documents/{doc_id}/retry-failed-chunks
POST /api/v1/knowledge-bases/{kb_id}/documents/{doc_id}/chunks/{chunk_id}/retry-embedding

• reprocess: Re-chunks and re-embeds the document
• retry-failed-chunks: Re-runs all failed chunk embeddings
• retry-embedding: Re-runs a single failed chunk

Each returns 200 OK with the document object.

Document Chunks

GET    /api/v1/knowledge-bases/{kb_id}/documents/{document_id}/chunks?page=1&page_size=50
POST   /api/v1/knowledge-bases/{kb_id}/documents/{document_id}/chunks?after_index=0
PUT    /api/v1/knowledge-bases/{kb_id}/documents/{document_id}/chunks/{chunk_id}
DELETE /api/v1/knowledge-bases/{kb_id}/documents/{document_id}/chunks/{chunk_id}
POST   /api/v1/knowledge-bases/{kb_id}/documents/{document_id}/rechunk

• List: Uses items/total/page/page_size pagination
• Create: Inserts a new chunk after after_index; body {"content": "..."}
• Update: Body {"content": "..."}
• Rechunk: Accepts chunk_size, chunk_overlap, and optional separator

Each endpoint requires kb:read/kb:update/kb:delete according to the operation.

Retrieval

Single Retrieval

POST /api/v1/knowledge-bases/{kb_id}/search

Request fields:

curl -X POST "https://your-domain.com/api/v1/knowledge-bases/{kb_id}/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "How to reset password", "search_mode": "hybrid", "top_k": 5}'

Query length is limited to 1-1000 characters; in hybrid mode, dense_weight and lexical_weight cannot both be 0.

Each result in the response results array contains chunk_id, document_id, document_name, content, score, metadata, search_type, and per-stage scores: dense_score, lexical_score, fusion_score, rerank_score, rerank_rank. The timings array records recall, rerank, total stage latencies in milliseconds.

Multi-Config Comparison Retrieval

POST /api/v1/knowledge-bases/{kb_id}/search/batch

Request body is an array of retrieval configs, each executed independently and returned for parameter comparison.

Cross-Team Sharing

Share a knowledge base with other teams in the organization with read-only access. Sharing grants read access only: listing, details, document listing, chunk reads, and search work for the receiving teams, but no write endpoint (updating/deleting a KB, uploading/processing/deleting documents, creating/updating/deleting chunks) is opened up by a share — writes still require the caller to be a member of the owning team (and usually an owner/admin role).

Share Knowledge Base

POST /api/v1/knowledge-bases/{kb_id}/share

{
  "team_id": "target-team-uuid",
  "permission": "read_only"
}

Returns a KnowledgeBaseShareOut record with id, knowledge_base_id, knowledge_base_name, shared_with_team_id, shared_with_team_name, permission (currently always read_only), shared_by_id, shared_by_name, and shared_at.

These cases are rejected:

List Knowledge Base Shares

GET /api/v1/knowledge-bases/{kb_id}/shares

Returns { "shares": [...], "total": N }, ordered by shared_at descending.

Remove Knowledge Base Share

DELETE /api/v1/knowledge-bases/{kb_id}/share/{team_id}

Requires kb:delete and the owner/admin role in the owning team; on success data is null.

Knowledge Base Statistics

GET /api/v1/knowledge-bases/{kb_id}/stats

Returns document_count, total_chunks, total_tokens, documents_by_status (distribution by status), documents_by_type (distribution by type), embedding_dimension, embedding_stats (total_vectors, missing_vectors).

Error Codes