Apps API · Knowledge Bases
Knowledge Bases: 9 个接口
GET /api/v1/agents/{agent_member_id}/knowledge-bases
List the knowledge bases an Agent can read
权限(scope): kb:space:read · 调用方式: appToken · operationId: list-agent-knowledge-bases
Required app scope: kb:space:read.
Lists the knowledge bases the Agent can actually read (its owner's private knowledge base included, the Default knowledge base by its member rule), keeping only those the caller can read too. The others are not listed; their number is returned as hidden_count. The caller must be able to see the Agent: an unknown member is 404, an Agent of another org is 403, a member that is not an Agent is 400. Paged with limit/offset like list-kbs; pagination.total_count excludes hidden_count. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
limit |
query | integer (int32) | Items per page (default: 20, max: 100) | |
offset |
query | integer (int32) | Number of items to skip (default: 0) | |
status_filter |
query | string: active, archived |
Filter by KB status (default: all non-trashed) |
回包
200OK —application/json·ListAgentKnowledgeBasesResponseBodydefaultError —application/problem+json·D8Error
GET /api/v1/kbs
List KBs
权限(scope): kb:space:read · 调用方式: appToken · operationId: list-kbs
Required app scope: kb:space:read.
Returns knowledge bases. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
limit |
query | integer (int32) | Items per page (default: 20, max: 100) | |
offset |
query | integer (int32) | Number of items to skip (default: 0) | |
status_filter |
query | string: active, archived, trashed |
Filter by KB status |
回包
200OK —application/json·CursorListResponseKbSummaryItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/kbs
Create KB
权限(scope): kb:space:write · 调用方式: appToken · operationId: create-kb
Required app scope: kb:space:write.
Creates a knowledge base. visibility private creates a private knowledge base owned by the caller (the platform sets the owner): only a human member signed in directly may ask for it; Agents, services and delegated credentials (personal access tokens, workspace app tokens) get 400 KB_PRIVATE_VISIBILITY_RESERVED, and while system setting automation_private_scope_enabled is not "true" a human gets 403 PRIVATE_SCOPE_DISABLED (503 when the setting can't be read). Nothing is created when refused. open and closed are unchanged. Response wrapped in standard envelope.
请求体
application/json · CreateKBRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
description |
string | KB description | |
icon |
string | KB icon | |
name |
string | 是 | KB name |
visibility |
string: open, closed, private |
是 | KB visibility |
回包
200OK —application/json·DataResponseKbItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/kbs/init
Initialize org KB
权限(scope): kb:space:write · 调用方式: appToken · operationId: init-org-kb
Required app scope: kb:space:write.
Initializes the organization knowledge base. Response wrapped in standard envelope.
回包
200OK —application/json·DataResponseInitOrgKBDataBodydefaultError —application/problem+json·D8Error
DELETE /api/v1/kbs/{kb_id}
Delete KB
权限(scope): kb:space:delete · 调用方式: appToken · operationId: delete-kb
Required app scope: kb:space:delete.
Deletes a knowledge base. Needs kb.manage, as before, except that a private knowledge base can be deleted only by its owner (a caller without kb.manage gets 403 whether or not the knowledge base exists or is visible to it; one with kb.manage gets 404 for another member's private knowledge base), and not while projects (archived ones included) still use it: 409 KB_IN_USE_BY_PROJECTS with meta.project_count. Same rule as archive-kb. The platform still refuses deleting the personal knowledge base. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
kb_id |
path | string (uuid) | 是 | KB UUID |
回包
200OK —application/json·DataResponseStruct {}BodydefaultError —application/problem+json·D8Error
GET /api/v1/kbs/{kb_id}
Get KB
权限(scope): kb:space:read · 调用方式: appToken · operationId: get-kb
Required app scope: kb:space:read.
Returns a knowledge base. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
kb_id |
path | string (uuid) | 是 | KB UUID |
回包
200OK —application/json·DataResponseKbItemBodydefaultError —application/problem+json·D8Error
PATCH /api/v1/kbs/{kb_id}
Update KB
权限(scope): kb:space:write · 调用方式: appToken · operationId: update-kb
Required app scope: kb:space:write.
Updates a knowledge base. Setting visibility to private, or changing the visibility of a private knowledge base, is refused with 412 KB_PRIVATE_VISIBILITY_IMMUTABLE and nothing is changed. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
kb_id |
path | string (uuid) | 是 | KB UUID |
请求体
application/json · UpdateKBRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
description |
string | KB description | |
icon |
string | KB icon | |
name |
string | KB name | |
set_description |
boolean | Set to true to apply description, or clear it when description is omitted | |
set_icon |
boolean | Set to true to apply icon, or clear it when icon is omitted | |
visibility |
string: open, closed, private |
KB visibility |
回包
200OK —application/json·DataResponseKbItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/kbs/{kb_id}/archive
Archive KB
权限(scope): kb:space:write · 调用方式: appToken · operationId: archive-kb
Required app scope: kb:space:write.
Archives a knowledge base. Needs kb.manage, as before, except that a private knowledge base can be archived only by its owner (a caller without kb.manage gets 403 whether or not the knowledge base exists or is visible to it; one with kb.manage gets 404 for another member's private knowledge base), and not while projects (archived ones included) still use it: 409 KB_IN_USE_BY_PROJECTS with meta.project_count. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
kb_id |
path | string (uuid) | 是 | KB UUID |
回包
200OK —application/json·DataResponseStruct {}BodydefaultError —application/problem+json·D8Error
POST /api/v1/kbs/{kb_id}/unarchive
Unarchive KB
权限(scope): kb:space:write · 调用方式: appToken · operationId: unarchive-kb
Required app scope: kb:space:write.
Unarchives a knowledge base. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
kb_id |
path | string (uuid) | 是 | KB UUID |
回包
200OK —application/json·DataResponseStruct {}BodydefaultError —application/problem+json·D8Error
