Knowledge Open API

This document describes the /api/knowledge/* open APIs for managing knowledge documents, folders, and direct knowledge retrieval from external systems.

If you want an agent to use a knowledge base through /api/v1/responses, see the knowledge_base tool configuration in OpenAPI v1/responses API.

Authentication

All endpoints require one of the following authentication methods:

Authorization: Bearer <access_token>
X-API-Key: <api_key>

When using a service API key, pass wegent-username to specify the target user.

Base URL

/api/knowledge

Common Rules

knowledge_base_id is the knowledge base ID.
document_id is the knowledge document ID.
folder_id=0 means the root folder.
Omitting folder_id means no folder filter.
folder_ids=[0] means documents directly under root. It does not mean whole-knowledge-base search.
For whole-knowledge-base search, omit both folder_ids and document_ids.
folder_ids=[] and document_ids=[] are invalid.

Knowledge Bases

List Accessible Knowledge Bases

GET /api/knowledge/list

Query parameters:

Parameter	Type	Required	Description
`scope`	string	No	`personal` returns personal accessible knowledge bases; `all` returns personal, group, and organization accessible knowledge bases. Default: `all`

Response:

{
  "total": 1,
  "items": [
    {
      "id": 1,
      "name": "Product KB",
      "namespace": "default",
      "document_count": 12
    }
  ]
}

Documents

List Documents

GET /api/knowledge/documents

Query parameters:

Parameter	Type	Required	Description
`knowledge_base_id`	integer	Yes	Knowledge base ID
`folder_id`	integer	No	Folder filter. `0` means documents directly under root; omitted means all documents; values greater than `0` return only direct documents in that folder, not recursively

Response:

{
  "total": 1,
  "items": [
    {
      "id": 101,
      "kind_id": 1,
      "name": "design.md",
      "file_extension": "md",
      "status": "enabled",
      "index_status": "success",
      "folder_id": 0
    }
  ]
}

Read Document Content

GET /api/knowledge/documents/{document_id}/content

Query parameters:

Parameter	Type	Required	Description
`offset`	integer	No	Start character offset. Default: `0`
`limit`	integer	No	Maximum characters to return. Default and maximum are server controlled

Response:

{
  "document_id": 101,
  "name": "design.md",
  "content": "Partial document content",
  "total_length": 12000,
  "offset": 0,
  "returned_length": 2000,
  "has_more": true,
  "kb_id": 1,
  "index_status": "success"
}

Create Document

POST /api/knowledge/documents

Request body fields:

Field	Type	Required	Description
`knowledge_base_id`	integer	Yes	Target knowledge base ID
`name`	string	Yes	Document name
`source_type`	string	No	`text`, `file`, `web`, or `attachment`. Default: `text`
`content`	string	Conditionally	Text content for `source_type=text`
`file_base64`	string	Conditionally	Base64-encoded file for `source_type=file`; decoded size limit is 10 MB
`file_extension`	string	Conditionally	File extension without a leading dot. Required for `file`; optional for `text`
`url`	string	Conditionally	Web page URL for `source_type=web`
`attachment_id`	integer	Conditionally	Existing attachment ID for `source_type=attachment`
`folder_id`	integer	No	Target folder ID. `0` means root. Default: `0`
`splitter_config`	object	No	Custom chunking configuration

Text example:

{
  "knowledge_base_id": 1,
  "name": "design.md",
  "source_type": "text",
  "content": "# Design\n\nBody",
  "file_extension": "md",
  "folder_id": 0
}

Web example:

{
  "knowledge_base_id": 1,
  "name": "Website docs",
  "source_type": "web",
  "url": "https://example.com/docs",
  "folder_id": 10
}

Update Document Metadata

PUT /api/knowledge/documents/{document_id}

Request body fields:

Field	Type	Required	Description
`name`	string	No	New document name
`status`	string	No	`enabled` or `disabled`
`splitter_config`	object	No	Chunking configuration

This endpoint updates metadata only. It does not update document text content.

Update Document Content

PUT /api/knowledge/documents/{document_id}/content

Request body:

{
  "content": "New Markdown content"
}

Only text documents and plain-text file documents are supported. Updating content triggers re-indexing.

Move Document

PUT /api/knowledge/documents/{document_id}/move

Request body:

{
  "folder_id": 10
}

Use folder_id=0 to move the document to root.

Delete Document

DELETE /api/knowledge/documents/{document_id}

Physically deletes the document, deletes associated attachments, and removes the corresponding RAG index. A successful deletion returns 204 No Content.

Re-index Document

POST /api/knowledge/documents/{document_id}/reindex

Re-indexes the document with the knowledge base's current retrieval configuration. Use this endpoint for index repair or manual rebuilds after configuration changes.

Batch Delete Documents

POST /api/knowledge/documents/batch/delete

Request body:

{
  "document_ids": [101, 102]
}

Response:

{
  "success_count": 1,
  "failed_count": 1,
  "failed_ids": [102],
  "message": "Successfully deleted 1 documents, 1 failed"
}

Batch delete allows partial success. Duplicate document_ids are deduplicated in first-seen order before deletion, and success_count, failed_count, and failed_ids are calculated from the deduplicated document set. Successfully deleted documents have their associated attachments and RAG indexes removed, and the affected knowledge base summaries are refreshed.

Batch Move Documents

POST /api/knowledge/documents/batch/move

Request body:

{
  "document_ids": [101, 102],
  "folder_id": 10
}

Use folder_id=0 to batch move documents to root. The endpoint allows partial success, and failed document IDs are returned in failed_ids.

Folders

Folders are knowledge document metadata, not attachment metadata. The generic attachment upload API does not accept folder_id.

Get Folder Tree

GET /api/knowledge/folders?knowledge_base_id=1

The response contains the full folder tree, including empty folders:

[
  {
    "id": 10,
    "kind_id": 1,
    "parent_id": 0,
    "name": "Product",
    "document_count": 3,
    "children": []
  }
]

Create Folder

POST /api/knowledge/folders

Request body:

{
  "knowledge_base_id": 1,
  "name": "Product",
  "parent_id": 0
}

Update Folder

PUT /api/knowledge/folders/{folder_id}

Request body:

{
  "knowledge_base_id": 1,
  "name": "Product Docs",
  "parent_id": 0
}

name and parent_id are optional, but knowledge_base_id is required for ownership validation.

Delete Folder

DELETE /api/knowledge/folders/{folder_id}?knowledge_base_id=1

Deletes the folder subtree and moves documents under the deleted folders to root.

Search

Retrieve Document Chunks

POST /api/knowledge/search

Request body fields:

Field	Type	Required	Description
`knowledge_base_id`	integer	Yes	Knowledge base ID
`query`	string	Yes	Search query. Maximum 2000 characters
`top_k`	integer	No	Number of results. Default: `5`, range: `1` to `100`
`score_threshold`	number	No	Minimum similarity score. Default: `0.7`
`route_mode`	string	No	`auto`, `direct_injection`, or `rag_retrieval`. Default: `auto`
`folder_ids`	integer[]	No	Folder scope. `[0]` means documents directly under root
`document_ids`	integer[]	No	Specific document scope
`include_subfolders`	boolean	No	Whether `folder_ids` includes descendants. Default: `true`
`context_window`	integer	No	Context window size for direct injection mode
`used_context_tokens`	integer	No	Already used context tokens
`reserved_output_tokens`	integer	No	Reserved output tokens
`context_buffer_ratio`	number	No	Safety buffer ratio for context
`max_direct_chunks`	integer	No	Maximum chunks for direct injection

Whole-knowledge-base search:

{
  "knowledge_base_id": 1,
  "query": "scoped search design",
  "top_k": 5
}

Folder-scoped search:

{
  "knowledge_base_id": 1,
  "query": "scoped search design",
  "folder_ids": [10],
  "include_subfolders": true,
  "top_k": 5
}

Document-scoped search:

{
  "knowledge_base_id": 1,
  "query": "scoped search design",
  "document_ids": [101, 102]
}

Scope rules:

Whole-knowledge-base search: omit both folder_ids and document_ids.
Root-folder search: pass folder_ids: [0].
Subfolder search: pass folder_ids: [10] and use include_subfolders to control whether descendants are included.
When both folder_ids and document_ids are provided, the scope is their union.
folder_ids=[] or document_ids=[] is invalid.
If the specified scope contains no documents, the API returns empty results and does not fall back to whole-knowledge-base search.

Response:

{
  "records": [
    {
      "content": "Matched chunk content",
      "score": 0.86,
      "title": "design.md"
    }
  ]
}

Error Codes

Status	Meaning
`400`	Semantic parameter error, such as a folder outside the knowledge base or incomplete retrieval configuration
`403`	The current user cannot access the target knowledge base, folder, or document
`404`	Knowledge base, folder, or document not found
`422`	Request validation failed, such as empty arrays, missing conditional fields, or out-of-range values
`502`	Upstream web scraping or RAG gateway error

Authentication​

Base URL​

Common Rules​

Knowledge Bases​

List Accessible Knowledge Bases​

Documents​

List Documents​

Read Document Content​

Create Document​

Update Document Metadata​

Update Document Content​

Move Document​

Delete Document​

Re-index Document​

Batch Delete Documents​

Batch Move Documents​

Folders​

Get Folder Tree​

Create Folder​

Update Folder​

Delete Folder​

Search​

Retrieve Document Chunks​

Error Codes​

Authentication

Base URL

Common Rules

Knowledge Bases

List Accessible Knowledge Bases

Documents

List Documents

Read Document Content

Create Document

Update Document Metadata

Update Document Content

Move Document

Delete Document

Re-index Document

Batch Delete Documents

Batch Move Documents

Folders

Get Folder Tree

Create Folder

Update Folder

Delete Folder

Search

Retrieve Document Chunks

Error Codes