Skip to main content

对外接口

KnowWork 的全部功能都有 HTTP 接口，网页用的就是这些接口。业务系统、自己写的 Agent、支持 MCP 的客户端，都可以用 API Key 调用。

接口文档​

部署好以后打开 https://<你的域名>/api/docs，是 Swagger 页面：按「对话」「知识库」「成员与权限」等分组列出每个接口的参数和中文说明，可以直接在页面上试。OpenAPI 描述在 /api/openapi.json，可以导入 Postman、Apifox，或者生成客户端代码。

API Key​

在网页左下角账号菜单 →「个人设置」→「API Key」里创建。密钥只在创建时显示一次，丢了只能重建。调用时放在请求头里：

Authorization: Bearer ak_xxxxxxxx
  • 权限不会超过本人：Key 代表创建它的人，只能查到这个人被授权的知识库；
  • 按范围收窄：创建时选范围，一个 Key 只能调它范围里的接口；
  • 绑定空间：Key 只在创建时所在的空间里有效；
  • 有效期：创建时选，到期自动失效，不用了随时吊销。
范围能做什么
knowledge:read检索、阅读知识库（对外知识接口与 MCP）
conversations:use新建对话、发消息、取回答
knowledge:manage管理知识源
workspace:manage管理成员与授权
tools:manage管理工具与 MCP 服务
models:manage查看用量统计
audit:read查看审计日志
给系统对接建专用账号

建一个专用账号（比如「OA 系统对接」），只授它要用的那几个知识库，再给它发一个范围最小的 Key。只做检索就只选 knowledge:read。不要用管理员的个人账号发 Key。

知识库检索与阅读​

列出能查的知识库（说明、元数据字段、标签）：

curl -H "Authorization: Bearer $KEY" https://kw.example.com/api/v1/knowledge-bases

检索：

curl -X POST https://kw.example.com/api/v1/knowledge/search \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"query": "差旅住宿标准", "top_n": 8}'

可选参数：

参数说明
knowledge_bases只查这几个库，写列出知识库时返回的 id
modehybrid（默认）、semantic 只按语义、keyword 只按字面（适合编号、型号）
folders、tags按文件夹、标签限定
filters按元数据字段筛，字段名与可选值见列出知识库的结果

结果里每个片段带 source_id、doc_ref 和 span_ref。要看上下文或整篇原文，接着调阅读：

curl -X POST https://kw.example.com/api/v1/knowledge/read \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"source_id": "<source_id>", "doc_ref": "<doc_ref>", "chunk": "<span_ref>", "context": 2}'

阅读还能按目录读（outline: true 先看目录，再用 section 读某一节）、在文档里查找（find），没读完时用返回的 next_cursor 接着读。

MCP​

同样的检索和阅读能力也以 MCP（Streamable HTTP）提供，地址是 https://<你的域名>/api/v1/mcp，用带 knowledge:read 的 Key。在支持 MCP 的客户端里这样配：

{
  "mcpServers": {
    "knowwork": {
      "url": "https://kw.example.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer ak_xxxxxxxx" }
    }
  }
}

提供三个工具：列出知识库、检索、阅读，参数与上面的接口相同。

程序化对话​

用 conversations:use 范围的 Key，可以像网页里一样和智能助手对话：

  1. 新建对话：POST /api/workspaces/{workspace_id}/conversations，返回对话 id；
  2. 发消息：POST /api/workspaces/{workspace_id}/conversations/{id}/messages，body 是 {"text": "问题"}；
  3. 取回答：GET /api/workspaces/{workspace_id}/conversations/{id}/events 是事件流（Server-Sent Events），回答的文字、调用了哪些工具、引用了哪些原文都在里面，回合结束时有结束事件。

{workspace_id} 是工作空间编号，默认空间是 default。出错时返回对应的 HTTP 状态码和 {"detail": "说明"}。