完整规范 (OpenAPI Spec)

知办AI 对外接口的机器可读规范，OpenAPI 3.x 格式。本页嵌入 YAML 原文，方便开发同事拷贝、做代码生成、对接 API 网关。

看接口怎么用？

• 接口概览 + 调用规范：见 接口总览
• 直接在线试：见 API 在线调试 (Scalar)
• 下载 YAML 做代码生成：zhiban-external-v1.yaml

当前端点（28 个）

Method & Path	说明	所需范围
POST /oauth/token	用 client_id + secret 换 60 分钟 Session Token	—
POST /auth/introspect	解码并校验知办用户登录 token	tenant.auth.introspect
GET /knowledge-bases	列本租户的租户级知识库	tenant.kb.read
POST /knowledge-bases	创建租户级知识库	tenant.kb.write
GET /knowledge-bases/{knowledge_base_id}	查知识库详情	tenant.kb.read
GET /knowledge-bases/{knowledge_base_id}/documents	列文档	tenant.kb.read
POST /knowledge-bases/{knowledge_base_id}/documents	上传文档	tenant.kb.write
GET /knowledge-bases/{knowledge_base_id}/documents/{document_id}	查文档详情	tenant.kb.read
POST /knowledge-bases/{knowledge_base_id}/retrieve	语义检索（RAG 核心）	tenant.kb.read
GET /org/departments	列部门，支持增量查询	tenant.org.read / org.read
POST /org/departments	创建部门	tenant.org.write
GET /org/departments/{department_id}	查部门详情	tenant.org.read / org.read
PATCH /org/departments/{department_id}	更新部门	tenant.org.write
DELETE /org/departments/{department_id}	删除部门	tenant.org.write
GET /org/members	列成员，支持增量查询	tenant.org.read / org.read
POST /org/members	添加成员	tenant.org.write
GET /org/members/{account_id}	查成员详情	tenant.org.read / org.read
PATCH /org/members/{account_id}	更新成员	tenant.org.write
DELETE /org/members/{account_id}	移除成员	tenant.org.write
GET /org/positions	列职位，支持增量查询	tenant.org.read / org.read
POST /org/positions	创建职位	tenant.org.write
GET /org/positions/{position_id}	查职位详情	tenant.org.read / org.read
PATCH /org/positions/{position_id}	更新职位	tenant.org.write
DELETE /org/positions/{position_id}	删除职位	tenant.org.write
POST /notifications/agent-conversation	发送知办数字员工对话通知	tenant.notification.write
POST /chat/messages	按 EMP 标准主动发送数字员工聊天消息	tenant.chat.message.write
GET /users/{user_id}/knowledge-bases	跨用户列私有 KB（审计）	tenant.kb.list_user_private
GET /users/{user_id}/knowledge-bases/{knowledge_base_id}	跨用户查私有 KB（审计）	tenant.kb.list_user_private
GET /users/{user_id}/knowledge-bases/{knowledge_base_id}/documents	跨用户读私有 KB 文档（审计）	tenant.kb.read_user_private

路径前缀都是 /api/external/v1。组织与人员 GET 读取接口可用 ek_ 或 st_；组织写入接口只用 ek_。所有跨用户接口自动写审计日志。

OpenAPI YAML

<<< @/openapi/zhiban-external-v1.yaml

VitePress 构建时把 YAML 内容嵌进来。如果上面区块没渲染，直接打开 zhiban-external-v1.yaml 看原文。

相关链接

• 接口总览 — 业务视角的接口分组、错误码、限流
• 鉴权概述 — 两种凭证、错误码处理
• API 在线调试 (Scalar) — 浏览器里发请求
• 租户自定义 Agent Runtime 接入 — 完整接入流程