知识库 API

简述

知识库 API 面向 技术对接人员：由您的业务后端或自动化脚本携带租户 API Key，调用 OpenDesk Open API 对知识库 目录 与 文档 进行查询、创建、更新与删除。写入结果与客服工作台知识库 共用同一套数据，操作人展示为 「API Key: {名称}」。

调用边界： 仅允许 服务端 调用；浏览器、Web SDK、移动 App 不得持有 API Key。员工日常维护知识库仍使用工作台内部接口（员工 JWT），不走本 Open API。

适用场景

典型用途： 实施脚本导入问题库、产品文档从中台同步至 OpenDesk 知识库、运维自动化发布 / 下线说明文档。

接入前准备

接口前缀：

{OpenDesk地址}/api/v1/open/knowledge

鉴权 Header（每次请求必填）：

Authorization: Bearer sk-odk-您的密钥
Content-Type: application/json

技术特性：

• 鉴权走统一依赖 get_open_api_context：只读取 Authorization Header，不接受 Query / Cookie / Body 中的 Key。
• 数据范围严格限定为 API Key 所属租户；跨租户资源 ID 返回 404。
• 无效或已删除 Key → 401；已禁用 Key → 403；成功调用更新 Key 的 最近使用时间。
• 目录 / 文档 CRUD 复用内部 KnowledgeService 规则，与工作台行为一致。
• 当前 API Key 无 scope 细分，启用 Key 均可调用知识库 Open API 及 context-token 接口。

整体流程

外部系统 / 脚本                          OpenDesk Open API                    客服工作台知识库
     │                                          │                                  │
     │  ① GET /knowledge/directories             │                                  │
     │ ───────────────────────────────────────> │                                  │
     │  ② 返回目录树（含 id、children）           │                                  │
     │ <─────────────────────────────────────── │                                  │
     │                                          │                                  │
     │  ③ POST /knowledge/documents              │                                  │
     │     title + directory_id + content_html   │                                  │
     │ ───────────────────────────────────────> │  ④ 写入租户知识库                 │
     │  ⑤ 返回文档 id、status 等                 │ ───────────────────────────────> │
     │ <─────────────────────────────────────── │     坐席可立即阅读 / 编辑          │

推荐操作顺序：

① 查询目录树，确认目标分类
        ↓
② 若无合适目录 → POST 新建目录（最多 3 级）
        ↓
③ POST 新建或 PUT 更新文档（title + content_html）
        ↓
④ GET 列表对账，或按标题存在性决定更新 / 新建

如何使用

第一步：创建 API Key

1. 超级管理员登录 管理后台 → 全局设置 → API Key。
2. 新建 Key（如「知识库同步脚本」「CMS 对接服务」），保存完整 sk-odk-...。
3. 在脚本或密钥管理系统中配置，勿提交至 Git。

第二步：确认目标目录

调用 查询目录树，建立「业务分类名 → 目录 ID」映射：

curl "{OpenDesk地址}/api/v1/open/knowledge/directories" \
  -H "Authorization: Bearer sk-odk-您的密钥"

响应 items 为树形结构，节点含 id、name、children 等。记下目标 id 作为后续 directory_id。

若无合适目录，先 新建目录：

curl -X POST "{OpenDesk地址}/api/v1/open/knowledge/directories" \
  -H "Authorization: Bearer sk-odk-您的密钥" \
  -H "Content-Type: application/json" \
  -d '{"name": "常见问题", "parent_id": null}'

目录层级上限：3 级。 删除目录前须清空其下所有子目录与文档。

第三步：创建或更新文档

新建文档：

curl -X POST "{OpenDesk地址}/api/v1/open/knowledge/documents" \
  -H "Authorization: Bearer sk-odk-您的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "如何重置密码",
    "directory_id": 3,
    "content_html": "<p>进入<strong>设置</strong> → 安全 → 重置密码。</p>",
    "status": "published"
  }'

更新文档（部分字段）：

curl -X PUT "{OpenDesk地址}/api/v1/open/knowledge/documents/{文档ID}" \
  -H "Authorization: Bearer sk-odk-您的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "如何重置密码（2026版）",
    "content_html": "<p>更新后的操作步骤...</p>",
    "status": "published"
  }'

PUT 只需传入要修改的字段。

第四步：查询与对账

文档列表（分页 + 筛选）：

curl "{OpenDesk地址}/api/v1/open/knowledge/documents?directory=3&status=published&page=1&per_page=20" \
  -H "Authorization: Bearer sk-odk-您的密钥"

列表默认 包含草稿，便于外部系统做全量同步。

接口速查

目录

文档

完整请求 / 响应 Schema 见 {OpenDesk地址}/docs。

错误与排查

知识库专项规则：

安全与限制

1. API Key 仅部署在服务端；日志与监控不得打印完整 Key。
2. 生产 / 测试环境分离 Key；停用脚本后 禁用并删除 对应 Key。
3. 所有请求使用 HTTPS。
4. Open API 不走员工权限树，不继承 knowledge.workspace.* 等员工权限；租户隔离完全由 Key 决定。
5. 本 API 不提供：Excel 导入导出接口、附件上传、版本历史、审批流、AI 向量检索。

与其他功能的关系

• API Key（管理后台）：与本接口及《传递客户上下文》共用鉴权凭证。
• 客服工作台 · 知识库：API 写入的数据在同一界面可见、可编辑。
• 知识库 SDK：员工侧浏览器 SDK 使用员工 JWT，不使用本 Open API。
• 传递客户上下文：同属 /api/v1/open/*，鉴权方式相同。

对接示例

从 Excel 批量导入 FAQ

角色与目标： 实施人员将「问题库.xlsx」（分类、标题、答案）导入 OpenDesk 知识库。

对接逻辑：

1. GET /knowledge/directories → 建立「Excel 分类 → directory_id」映射；缺失分类则 POST 创建。
2. 逐行读取：标题 → title，答案 → content_html（纯文本包 <p>）。
3. GET /knowledge/documents?directory={id}&q={title} 判断是否已存在；存在则 PUT 更新，否则 POST 新建。
4. 导入结束后再次 GET 列表核对条数。

场景效果： 工作台知识库出现完整 FAQ 目录；操作记录显示「API Key: 问题库导入脚本」。

定时同步产品说明

角色与目标： 产品中台 nightly 任务将最新产品说明 HTML 同步至 OpenDesk。

对接逻辑：

1. 中台输出 { slug, title, html, category }。
2. 脚本按 category 解析 directory_id。
3. 按 slug 或标题查找文档 ID，存在则 PUT content_html + status: published，否则 POST 新建。
4. 下线产品时对文档 PUT status: draft 或 DELETE。

场景效果： 坐席在工作台搜索到与中台一致的最新说明，无需手工复制粘贴。