租户服务端 API 列表

知办AI 当前对租户外部系统 / 租户自建 Agent 服务开放的 HTTP 接口都集中在 /api/external/v1/* 路径下，按业务域分组。

按你要做的直跳

试一下接口（不写代码） → API 在线调试
查接口字段全规范 → OpenAPI 规范
做 Agent 间协作 → Agent 间协作 A2A
查错误码含义 → 错误码
查限流策略 → 限流策略
还没拿到凭证 → 鉴权与凭证
接入应用栏 H5 免登 → 单点登录接入

A2A 不在本页接口清单内

Agent 间协作不是 /api/external/v1/* 服务端 API。它由自定义 Agent Runtime 通过 SDK A2A helper 发起，Bus 负责治理和转发。接入方式见 Agent 间协作 A2A。

接口分类

                                ┌──────────────────────┐
                                │  /api/external/v1/*   │
                                └──────────┬───────────┘
                                           │
                ┌──────────────────────────┼──────────────────────────┬──────────────────────────┐
                ▼                          ▼                          ▼                          ▼
        ┌───────────────┐         ┌───────────────┐          ┌────────────────┐
        │      鉴权     │         │     知识库    │          │   组织与人员   │
        │ (OAuth Token) │         │ (KB / 文档)   │          │ (成员/部门/职位)│
        └───────────────┘         └───────────────┘          └────────────────┘
                                                                    │
                                                                    ▼
                                                             ┌───────────────┐
                                                             │    系统通知   │
                                                             │(数字员工对话) │
                                                             └───────────────┘

                                      路线图：云盘 / SkillHub

业务域	路径前缀	当前状态	典型用法
鉴权	`/oauth/token`	✅ 已上线	Agent SDK 换 Session Token；H5 应用交换授权码或刷新令牌
知识库	`/knowledge-bases/*`	✅ 已上线	列出 / 读取知识库及其文档
记忆	`/memories/*`	✅ 已上线	召回 / 写入数字员工的长期与会话记忆
组织与人员	`/org/*`	✅ 已上线	同步部门、成员、职位，支持增量回查
系统通知	`/notifications/*`	✅ 已上线	外部系统触发站内消息通知，点击进入知办数字员工对话
主动发送聊天消息	`/chat/messages`	✅ 已上线	外部系统或租户自建 Agent 服务按 EMP 标准向数字员工直聊写入结构化消息
SkillHub	`/skills/*`	🚧 路线图	查询 / 借用平台技能
云盘	`/drive/*`	🚧 路线图	拉取云盘文件、上传文档

调用规范

基础路径

环境	域名
测试	`https://*-test.creditease.corp`
生产	`https://zhiban.creditease.corp`

具体域名向对接同事确认；不同环境的凭证不通用。

请求头

所有接口都必须带：

Authorization: Bearer <凭证>
Content-Type: application/json      （POST / PUT 时）

凭证类型见鉴权概述。

通用响应结构

json

{
  "data": { /* 接口数据 */ },
  "meta": {
    "request_id": "req_...",
    "page": { "total": 123, "limit": 50, "offset": 0 }
  }
}

错误响应：

json

{
  "error": {
    "code": "scope_denied",
    "message": "API Key 缺少所需 scope: kb.read"
  },
  "meta": { "request_id": "req_..." }
}

出错时也带 request_id——联系运维排查时先把 request_id 告诉对方，能直接定位日志。

当前已上线接口

每个接口都能在线试

点表格里任一接口的「在线试」可跳到 API 在线调试，填一份凭证就能直接发请求。

鉴权

Method & Path	用途	所需范围	调试
`POST /api/external/v1/oauth/token`	Agent SDK 换 Session Token；H5 应用交换授权码或刷新令牌	—	→
`POST /api/external/v1/auth/introspect`	解码并校验知办用户登录 token	`tenant.auth.introspect`	→

知识库（增 / 查 / 检索）

数字员工运行时使用第一行的聚合检索入口：请求体传 agent_id + query，服务端检索该数字员工关联的全部平台/租户知识库。该入口只接受 runtime_access 换出的 st_。其余接口用于知识库管理、浏览或明确指定单库的通用集成；API Key 使用表中的 tenant.* scope，H5 应用 Access Token 使用 kb.read，仅能调用只读与单库检索接口，不能调用创建或上传接口。

Method & Path	用途	所需范围	调试
`POST /knowledge/retrieve`	按数字员工聚合检索已关联知识库（请求体传 `agent_id`）	`tenant.kb.read`；仅 `st_`	→
`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`	上传文档（multipart 或裸 body）	`tenant.kb.write`	→
`GET /knowledge-bases/{knowledge_base_id}/documents/{document_id}`	查文档详情	`tenant.kb.read`	→
`POST /knowledge-bases/{knowledge_base_id}/retrieve`	检索指定知识库（通用集成）	`tenant.kb.read`	→

路径前缀都是 /api/external/v1。

记忆（召回 / 写入）

Method & Path	用途	所需范围	调试
`POST /memories/recall`	语义召回（RAG 核心）	`tenant.memory.read`	→
`POST /memories/events`	写入一条记忆事件	`tenant.memory.write`	→
`GET /memories`	列举（检视）某 scope 下记忆	`tenant.memory.read`	→
`DELETE /memories/{id}`	遗忘一条记忆（按归属校验）	`tenant.memory.write`	→

五维上下文里 tenant_id 从凭证取，user_id / agent_id / session_id 由调用方传；详见记忆 API 指南。审计 / 跨用户接口在路线图上。

组织与人员（成员 / 部门 / 职位）

H5 应用 Access Token 使用 contacts.read，仅能调用本节 GET 接口；组织写操作仍只接受具备 tenant.org.write 的机器凭证。

Method & Path	用途	所需范围	调试
`GET /org/departments`	列部门，支持 `updated_since` 增量	`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`	列成员，支持 `updated_since` 增量	`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`	列职位，支持 `updated_since` 增量	`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`	→

组织与人员读取接口接受 API Key (ek_) 或接入方 Agent 服务的 Session Token (st_)；写入接口只接受 API Key (ek_)。详细说明见组织与人员 API 指南。

系统通知

Method & Path	用途	所需范围	调试
`POST /notifications/agent-conversation`	向目标知办用户发送一条知办数字员工对话通知	`tenant.notification.write`	→

系统通知 API 使用 API Key (ek_) 调用；目标知办用户账号用 user_id，知办数字员工用 agent_id，二者的值均为知办平台下发的稳定 UUID。点击通知固定进入对应直聊会话。详细说明见系统通知 API 指南。

主动发送聊天消息

Method & Path	用途	所需范围	调试
`POST /chat/messages`	按 EMP 标准向目标用户与数字员工直聊写入结构化 Agent 消息	`tenant.chat.message.write`	→

主动发送聊天消息 API 使用 API Key (ek_) 调用。message.blocks 是唯一消息正文，必须是 EMP registry 中的 stable block；服务端不做 fallback、不压平文本。详细说明见主动发送聊天消息 API 指南。

跨用户审计场景

Method & Path	用途	所需范围	调试
`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`	→

⚠️ 跨用户接口自动写审计日志（事件类型 tenant.admin.user_kb_inspect），仅限合规审计场景使用；普通取数走非跨用户的接口即可。

关键接口详解

按数字员工检索关联知识库

POST /api/external/v1/knowledge/retrieve —— 接入方 Agent 服务处理数字员工会话时传 agent_id + query；服务端根据 token 中的 tenant/runtime 校验数字员工，并聚合检索 agent_kb_bindings 中关联的平台/租户知识库。换取 st_ 时不需要传 agent_id。

curlPython

bash

curl -X POST -H "Authorization: Bearer st_..." -H "Content-Type: application/json" \
  -d '{"agent_id":"agent-a1b2...","query":"年假规定"}' \
  https://zhiban.creditease.corp/api/external/v1/knowledge/retrieve

python

r = httpx.post(
    "https://zhiban.creditease.corp/api/external/v1/knowledge/retrieve",
    headers={"Authorization": f"Bearer {SESSION_TOKEN}"},
    json={"agent_id": agent_id, "query": "年假规定"},
)
print(r.json()["data"]["items"])

json

{
  "success": true,
  "code": 200,
  "data": {
    "tool_name": "zhiban.kb.search",
    "query": "年假规定",
    "items": [
      {
        "reference_id": "kb:kb-a1b2...:1",
        "knowledge_base_id": "kb-a1b2...",
        "kb_name": "HR 制度库",
        "content": "员工每年享有 10 天带薪年假...",
        "document_id": "doc-...",
        "score": 0.87
      }
    ],
    "sources": [],
    "result_quality": "hit"
  }
}

需要调用方明确控制某个知识库时，使用 POST /api/external/v1/knowledge-bases/{knowledge_base_id}/retrieve；数字员工运行时无需先列知识库，也无需维护知识库 ID 列表。

上传文档

POST /api/external/v1/knowledge-bases/{knowledge_base_id}/documents —— 两种格式：

方式 A：multipart/form-data（推荐，能传文件名）

bash

curl -X POST -H "Authorization: Bearer ek_..." \
  -F "file=@./report.pdf" \
  -F "title=Q4 季报" \
  https://zhiban.creditease.corp/api/external/v1/knowledge-bases/<knowledge_base_id>/documents

方式 B：裸 body + query 参数

bash

curl -X POST -H "Authorization: Bearer ek_..." \
  -H "Content-Type: application/pdf" \
  --data-binary "@./report.pdf" \
  "https://zhiban.creditease.corp/api/external/v1/knowledge-bases/<knowledge_base_id>/documents?title=Q4%20season%20report&mime_type=application/pdf"

文件大小上限 4 MiB；上传后异步切片，初始 status: ingesting，完成后变 ready。

更多字段、错误码、完整 schema → OpenAPI 规范。

错误码

HTTP	code	含义
400	`invalid_argument`	参数缺失 / 格式错
401	`invalid_api_key` / `invalid_session_token` / `invalid_client_credentials`	凭证问题
403	`scope_denied`	凭证范围不足
404	`not_found`	资源不存在 / 跨租户 / 私有不可见
429	`rate_limited`	触发限流
500	`internal_error`	服务端异常
503	`service_unavailable`	后端依赖（如知识库服务）不可用

错误细节见鉴权概述 · 错误码处理。

限流策略

维度	默认配额
单个 API Key	100 QPS
单个 Session Token	50 QPS
同租户聚合	500 QPS

超出后返回 429 rate_limited，响应头 Retry-After 给出建议退避秒数。高频场景联系运维提配额。

在线调试入口

进入方式

本站直接打开：API 在线调试 (Scalar)
侧边栏：开发者文档 → 对外开放的接口 → API 在线调试 (Scalar) ↗

使用步骤

顶部下拉选环境（dev / test / prod）。
在 Authentication 区填 Bearer <你的 API Key>。
左侧选要调的接口，右侧填参数，点 Try it out。
看真实响应（含状态码、headers、body、耗时）。

Scalar 是无状态的，凭证只存在你浏览器内存里，刷新页面就清空。

路线图

后端尚未实现、当前外部 API 不支持的能力：

缺口	备注
`PATCH /knowledge-bases/{knowledge_base_id}` (改 KB 元信息)	当前只能创建，不能改名 / 改描述
`DELETE /knowledge-bases/{knowledge_base_id}` (删 KB)	当前删 KB 走客户端，外部 API 没暴露
`DELETE /knowledge-bases/{knowledge_base_id}/documents/{document_id}` (删文档)	同上
`/drive/*` (云盘)	拉取 / 上传云盘文件
`/skills/*` (SkillHub)	查询可借技能、发起受控技能调用

跟运维或产品对接时关注最新进度。

租户服务端 API 列表 ​

接口分类 ​

调用规范 ​

基础路径 ​

请求头 ​

通用响应结构 ​

当前已上线接口 ​

鉴权 ​

知识库（增 / 查 / 检索） ​

记忆（召回 / 写入） ​

组织与人员（成员 / 部门 / 职位） ​

系统通知 ​

主动发送聊天消息 ​

跨用户审计场景 ​

关键接口详解 ​

按数字员工检索关联知识库 ​

上传文档 ​

错误码 ​

限流策略 ​

在线调试入口 ​

进入方式 ​

使用步骤 ​

路线图 ​

相关链接 ​

租户服务端 API 列表

接口分类

调用规范

基础路径

请求头

通用响应结构

当前已上线接口

鉴权

知识库（增 / 查 / 检索）

记忆（召回 / 写入）

组织与人员（成员 / 部门 / 职位）

系统通知

主动发送聊天消息

跨用户审计场景

关键接口详解

按数字员工检索关联知识库

上传文档

错误码

限流策略

在线调试入口

进入方式

使用步骤

路线图

相关链接