#Knowledge Base API

Manage knowledge bases, documents, and vector retrieval. Knowledge bases provide domain knowledge context (RAG) for Agents.

Base Path: /v1/knowledge-bases

#Knowledge Base Management

#List Knowledge Bases

GET /v1/knowledge-bases

Required Permission: kb:read

#Query Parameters

Parameter	Type	Description
`page`	number	Page number, default 1
`limit`	number	Items per page, default 20, max 100
`projectId`	string	Filter by project

#Response

json{
  "data": [
    {
      "id": "kb_abc123",
      "name": "Product Documentation",
      "description": "Product-related documents",
      "documentCount": 15,
      "embeddingModel": "text-embedding-ada-002",
      "organizationId": "org_xxx",
      "projectId": "proj_xxx",
      "createdAt": "2026-01-10T08:00:00Z",
      "updatedAt": "2026-02-15T12:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

#Get Knowledge Base Details

GET /v1/knowledge-bases/:kbId

Required Permission: kb:read

#Create Knowledge Base

POST /v1/knowledge-bases

Required Permission: kb:create (admin or user role)

#Request Body

json{
  "name": "Product Documentation",
  "description": "Storage for all product-related documents",
  "embeddingModel": "text-embedding-ada-002",
  "embeddingProvider": "openai",
  "apiKeyConfigId": "config_xxx",
  "chunkSize": 500,
  "chunkOverlap": 50
}

Field	Type	Required	Description
`name`	string	Yes	Knowledge base name
`description`	string	No	Description
`embeddingModel`	string	No	Embedding model
`embeddingProvider`	string	No	Embedding model provider
`apiKeyConfigId`	string	No	API Key configuration ID
`chunkSize`	number	No	Chunk size
`chunkOverlap`	number	No	Chunk overlap size

#Response

HTTP 201 Created

#Update Knowledge Base

PATCH /v1/knowledge-bases/:kbId

Required Permission: kb:write (admin or user role)

#Request Body

json{
  "name": "Updated Name",
  "description": "Updated description",
  "settings": {}
}

#Delete Knowledge Base

DELETE /v1/knowledge-bases/:kbId

Required Permission: kb:delete (admin or user role)

#Response

json{
  "id": "kb_abc123",
  "deleted": true
}

#Document Management

#List Documents

GET /v1/knowledge-bases/:kbId/documents

Required Permission: kb:read

#Response

json{
  "data": [
    {
      "id": "doc_xxx",
      "name": "User Manual.pdf",
      "status": "processed",
      "chunkCount": 42,
      "size": 1048576,
      "createdAt": "2026-02-01T08:00:00Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

#Get Document Details

GET /v1/knowledge-bases/:kbId/documents/:docId

Required Permission: kb:read

#Upload Document

POST /v1/knowledge-bases/:kbId/documents

Required Permission: kb:upload (admin or user role)

Upload files using multipart/form-data format:

bashcurl -X POST "https://your-domain.com/v1/knowledge-bases/kb_abc123/documents" \
  -H "X-API-Key: sk_your_api_key_here" \
  -F "file=@./document.pdf"

#Batch Upload (URL)

POST /v1/knowledge-bases/:kbId/documents/batch

Required Permission: kb:upload (admin or user role)

#Request Body

json{
  "urls": [
    "https://example.com/doc1.pdf",
    "https://example.com/doc2.md"
  ],
  "tags": ["product", "v2"]
}

#Response

HTTP 202 Accepted

json{
  "data": [
    {
      "url": "https://example.com/doc1.pdf",
      "status": "queued",
      "documentId": "doc_xxx"
    }
  ],
  "meta": {
    "total": 1,
    "jobId": "job_xxx"
  }
}

#Delete Document

DELETE /v1/knowledge-bases/:kbId/documents/:docId

Required Permission: kb:delete (admin or user role)

#Response

json{
  "id": "doc_xxx",
  "deleted": true
}

#Import Jobs

Batch imports create import jobs to track processing progress.

#Create Import Job

POST /v1/knowledge-bases/:kbId/import-jobs

Required Permission: kb:upload (admin or user role)

Uses multipart/form-data format, supporting file uploads and URL sources:

Field	Type	Description
`files`	File[]	Uploaded files (up to 50)
`sources`	string (JSON)	URL source list
`options`	string (JSON)	Import options
`webhookUrl`	string	Completion notification URL

#Response

HTTP 202 Accepted

#List Import Jobs

GET /v1/knowledge-bases/:kbId/import-jobs

Required Permission: kb:read

#Query Parameters

Parameter	Type	Description
`page`	number	Page number, default 1
`limit`	number	Items per page, default 20

#Get Import Job Details

GET /v1/knowledge-bases/:kbId/import-jobs/:jobId

Required Permission: kb:read

Returns job details and associated document processing progress.

#Cancel Import Job

DELETE /v1/knowledge-bases/:kbId/import-jobs/:jobId

Required Permission: kb:upload (admin or user role)

#Response

json{
  "id": "job_xxx",
  "status": "cancelled",
  "cancelledDocuments": 3,
  "alreadyProcessed": 2
}

#Retry Failed Documents

POST /v1/knowledge-bases/:kbId/import-jobs/:jobId/retry

Required Permission: kb:upload (admin or user role)

#Response

json{
  "id": "job_xxx",
  "status": "processing",
  "retriedDocuments": 2
}

#Search

#Search Knowledge Base

POST /v1/knowledge-bases/:kbId/search

Required Permission: rag:search

#Request Body

json{
  "query": "How to configure system parameters",
  "topK": 5,
  "scoreThreshold": 0.7,
  "filters": {}
}

Field	Type	Required	Description
`query`	string	Yes	Search query
`topK`	number	No	Maximum number of results to return, default 5
`scoreThreshold`	number	No	Minimum similarity threshold, default 0.7
`filters`	object	No	Additional filter conditions

#Response

json{
  "query": "How to configure system parameters",
  "results": [
    {
      "documentId": "doc_xxx",
      "documentName": "System Configuration Guide",
      "content": "System parameters can be configured through the following methods...",
      "score": 0.95,
      "metadata": {}
    }
  ],
  "totalResults": 1,
  "searchTime": 0.125
}