API 参考

所有接口的基础路径为 /api，需通过 Bearer Token 认证（JWT 或 Integration Token）。响应格式为 JSON。

智能体管理

方法	路径	说明
GET	`/agents`	列出当前组织下所有智能体
GET	`/agents/system-default`	获取系统默认智能体
GET	`/agents/:id`	获取单个智能体详情
POST	`/agents`	创建智能体
PATCH	`/agents/:id`	更新智能体配置
DELETE	`/agents/:id`	删除智能体（需 owner 权限）
POST	`/agent-templates/import`	从模板导入智能体

智能体共享

方法	路径	说明
GET	`/agents/:id/shares`	列出智能体的共享记录
POST	`/agents/:id/shares`	添加共享
DELETE	`/agents/:id/shares/:shareId`	移除共享

对话

方法	路径	说明
POST	`/chat`	发送消息并获取流式回复（SSE）
POST	`/chat/warmup`	预热智能体运行时
GET	`/chat/history`	获取指定对话的消息历史
GET	`/chat/conversations`	列出当前用户的对话列表
PATCH	`/chat/conversations/:id`	更新对话（如重命名）
DELETE	`/chat/conversations/:id`	删除对话

对话历史（管理侧）

方法	路径	说明
GET	`/conversation-history/status`	对话历史服务状态
POST	`/conversation-history/collect`	触发对话收集
GET	`/conversation-history/:convId`	获取对话详情
GET	`/conversation-history/:convId/messages`	获取对话消息列表
GET	`/conversation-history/list`	列出所有对话（支持分页和过滤）

知识库

方法	路径	说明
GET	`/knowledge-bases`	列出知识库
POST	`/knowledge-bases`	创建知识库
GET	`/knowledge-bases/:id`	获取知识库详情
PATCH	`/knowledge-bases/:id`	更新知识库
DELETE	`/knowledge-bases/:id`	删除知识库
POST	`/knowledge-bases/search`	知识库搜索

知识源

方法	路径	说明
GET	`/knowledge-bases/:kbId/sources`	列出知识源
POST	`/knowledge-bases/:kbId/sources`	添加知识源（支持文件上传）
DELETE	`/sources/:id`	删除知识源
POST	`/sources/:id/sync`	触发知识源同步
GET	`/sources/:id/sync-logs`	查看同步日志

文档与分块

方法	路径	说明
GET	`/knowledge-bases/:kbId/documents`	列出文档
GET	`/documents/:docId/chunks`	查看文档分块

知识库共享

方法	路径	说明
GET	`/knowledge-bases/:id/shares`	列出共享
POST	`/knowledge-bases/:id/shares`	添加共享
DELETE	`/knowledge-bases/:id/shares/:shareId`	移除共享

记忆

方法	路径	说明
GET	`/agents/:agentId/memories`	列出记忆（可按 `userId` 过滤）
GET	`/agents/:agentId/memories/stats`	记忆统计
POST	`/agents/:agentId/memories`	创建记忆
PATCH	`/agents/:agentId/memories/:memoryId`	更新记忆
DELETE	`/agents/:agentId/memories/:memoryId`	删除单条记忆
DELETE	`/agents/:agentId/memories?userId=xxx`	删除用户全部记忆

详见智能体记忆。

集成

方法	路径	说明
GET	`/integrations`	列出集成配置
POST	`/integrations`	创建集成
GET	`/integrations/:id`	获取集成详情
PATCH	`/integrations/:id`	更新集成
DELETE	`/integrations/:id`	删除集成
POST	`/integrations/:id/rotate-key`	轮换 S2S 密钥
POST	`/integrations/:id/verify`	验证集成连通性

定时任务

方法	路径	说明
GET	`/cron-jobs`	列出定时任务
GET	`/cron-jobs/:id`	获取任务详情
POST	`/cron-jobs`	创建任务（需 admin 权限）
PATCH	`/cron-jobs/:id`	更新任务
DELETE	`/cron-jobs/:id`	删除任务
POST	`/cron-jobs/:id/run`	立即执行
GET	`/cron-jobs/:id/runs`	执行历史（`?limit=50`）

详见定时任务。

技能

方法	路径	说明
GET	`/skills`	列出技能
GET	`/skills/:id`	获取技能详情
POST	`/skills`	创建技能
POST	`/skills/upload`	上传技能包
POST	`/skills/import-npx`	从 npx 导入技能
PATCH	`/skills/:id`	更新技能
DELETE	`/skills/:id`	删除技能
GET	`/skills/:id/content`	获取技能内容
GET	`/skills/:id/files`	列出技能文件

MCP Server

方法	路径	说明
GET	`/mcp-servers`	列出 MCP Server
GET	`/mcp-servers/resolve`	解析 MCP Server 工具
POST	`/mcp-servers`	创建 MCP Server
PATCH	`/mcp-servers/:id`	更新 MCP Server
DELETE	`/mcp-servers/:id`	删除 MCP Server

插件

方法	路径	说明
GET	`/plugins`	列出插件
GET	`/plugins/:id`	获取插件详情
POST	`/plugins/upload`	上传插件
POST	`/plugins/import-npx`	从 npx 导入插件
PATCH	`/plugins/:id`	更新插件
DELETE	`/plugins/:id`	删除插件

评估

方法	路径	说明
POST	`/agents/:agentId/evaluations`	触发评估（需 editor 权限）
GET	`/agents/:agentId/evaluations`	列出评估记录
GET	`/agents/:agentId/evaluations/latest`	获取最新评估
GET	`/agents/:agentId/evaluations/:evalId`	获取指定评估

详见智能体评估。

文件

方法	路径	说明
POST	`/files/upload`	上传文件（multipart/form-data）
GET	`/files/serve/*`	获取文件内容（公开访问）

沙箱

方法	路径	说明
POST	`/sandbox/pause`	暂停沙箱会话
GET	`/sandbox/status`	查看沙箱状态

沙箱模板

方法	路径	说明
GET	`/sandbox-templates`	列出沙箱模板
GET	`/sandbox-templates/:id`	获取模板详情
POST	`/sandbox-templates`	创建模板
PATCH	`/sandbox-templates/:id`	更新模板
DELETE	`/sandbox-templates/:id`	删除模板

渠道与路由

方法	路径	说明
GET	`/channels`	列出渠道（`?unitId=xxx`）
POST	`/channels`	创建渠道
PATCH	`/channels/:id`	更新渠道
DELETE	`/channels/:id`	删除渠道及关联路由
GET	`/routing-rules`	列出路由规则（`?agentId=xxx`）
POST	`/routing-rules`	创建路由规则
PATCH	`/routing-rules/:id`	更新规则
DELETE	`/routing-rules/:id`	删除规则

Webhook 回调

方法	路径	说明
GET	`/webhook/:channelType/:channelId`	Webhook 验证（微信接入校验）
POST	`/webhook/:channelType/:channelId`	接收渠道消息

详见渠道与分发。

分析洞察

方法	路径	说明
GET	`/agent-insights/:agentId`	获取智能体使用洞察数据

凭证管理

方法	路径	说明
GET	`/credentials`	列出凭证
POST	`/credentials`	创建凭证
PATCH	`/credentials/:id`	更新凭证
DELETE	`/credentials/:id`	删除凭证
GET	`/credentials/:id/test`	测试凭证连通性

组织管理

组织单元

方法	路径	说明
GET	`/org-units`	列出组织单元
GET	`/org-units/:id`	获取单元详情
POST	`/org-units`	创建组织单元
PATCH	`/org-units/:id`	更新组织单元
DELETE	`/org-units/:id`	删除组织单元

模型配置

方法	路径	说明
GET	`/model-definitions`	列出内置模型定义
GET	`/model-configs`	列出模型配置
POST	`/model-configs`	创建模型配置
PATCH	`/model-configs/:id`	更新模型配置
DELETE	`/model-configs/:id`	删除模型配置

通知

方法	路径	说明
GET	`/notifications`	列出通知
GET	`/notifications/unread-count`	未读数量
POST	`/notifications`	创建通知
PATCH	`/notifications/:id/read`	标记已读
POST	`/notifications/read-all`	全部标记已读

其他

方法	路径	说明
GET	`/templates`	列出智能体模板
GET	`/templates/:id`	获取模板详情
POST	`/templates`	创建模板
PATCH	`/templates/:id`	更新模板
DELETE	`/templates/:id`	删除模板
GET	`/sessions`	列出活跃会话
GET	`/activity-events`	获取活动事件流
GET	`/dashboard/stats`	获取仪表盘统计数据

认证方式

方式一：用户 Session

通过 Better Auth 登录后自动携带 Session Cookie，适用于管理面板前端。

方式二：Integration JWT

由你的后端使用 Integration 的 S2S 密钥签发 HS256 JWT，适用于嵌入式集成场景。详见集成与嵌入。

方式三：Chatbot Token

通过 /api/chatbot-tokens 签发的 ct_ 前缀 Token，适用于 iframe 嵌入的聊天界面。

错误响应

所有接口在异常时返回统一格式：

{
  "error": "错误标识",
  "details": {
    "formErrors": ["全局错误信息"],
    "fieldErrors": {
      "fieldName": ["字段级错误"]
    }
  }
}

常见 HTTP 状态码：

状态码	说明
400	请求参数无效
401	未认证
403	权限不足
404	资源不存在
501	功能未启用（如知识库未配置）

API 参考

目录