OpenAPI

OpenAPI 的本质是把 WinNexo 的前台能力当成你现有系统的"AI 能力插件"调用。 本文是完整接口参考：先讲清鉴权与通用规范，再按能力域给出全部接口的总览表与逐接口的路径、请求参数、响应参数与调用示例。

公共云 OpenAPI 文档站传送门

工作原理

mermaid

graph LR
    A[你的业务系统] -->|HTTP 请求 + AccessToken| B[WinNexo OpenAPI 网关]
    B --> C[会话能力]
    B --> D[快捷技能]
    B --> E[我的资源]
    B --> F[企业知识库]
    B --> I[定时任务]
    B --> J[用户与组织]
    C --> G[数字员工]
    D --> G
    E --> H[产出/资源]
    F --> H

每次调用都需要带上身份凭证（Authorization: Bearer <AccessToken>）。凭证类型见下方「鉴权」章节。

鉴权与通用规范

网关地址

所有接口统一前缀：/openapi
完整地址形如：https://<gateway-domain>/openapi/<接口路径>
<gateway-domain> 为你所在部署的网关域名，请向管理员获取。

AccessToken 类型

所有接口通过请求头 Authorization: Bearer <AccessToken> 鉴权，由 require_openapi_identity 统一处理。支持三类 Token：

Token 类型	前缀	说明	适用场景
用户 API Token	`wn_`	个人身份凭证，代表某个具体用户	个人脚本、IDE 插件、CLI 登录
部署级 Token	`wn_dpl_`	部署级凭证，需配合租户/用户信息使用	服务端集成、后台批处理
加密包 Token	`@ENCRYPT__`	加密串形式下发的凭证	特定托管/加密下发场景

获取与管理用户 API Token，请阅读个人设置中的 UserToken 说明。

租户 ID 确认

单租户用户：租户自动推断，无需显式传入。
多租户用户：需显式指定租户，二选一：
- Query 参数：tenantId 或 tenant_id
- 请求头：X-Tenant-Id
未指定且无法自动推断时返回 ERR.Auth.TenantIdRequired。

请求规范

HTTP 方法：写操作默认 POST；只读查询部分为 GET（个别删除为 DELETE），以各接口「接口信息」为准。
必填请求头：
- Authorization: Bearer <AccessToken>
- Content-Type: application/json
可选请求头：
- X-Tenant-Id：多租户下指定租户
- X-Timezone：指定时区（如 Asia/Shanghai），影响时间相关字段
字段命名：请求 / 响应字段统一使用 camelCase。
禁传字段：请求体中不要传 tenantId / tenant_id、userId / user_id——这些由鉴权链路自动推导，显式传入会被忽略或报错。

响应规范

所有接口返回 POP 网关兼容格式：顶层固定 Code / Message / RequestId，业务字段扁平展开（无嵌套 data 包装）。

成功响应：

json

{
  "Code": "200",
  "Message": "success",
  "RequestId": "req-xxx",
  "businessField": "value"
}

错误响应：

json

{
  "Code": "ERR.User.NotFound",
  "Message": "用户不存在",
  "RequestId": "req-xxx",
  "error_type": "USER_ERROR",
  "solution": "请检查用户ID是否正确"
}

多语言调用示例

以「创建个人文件」createPersonalFile 为例，演示各语言调用姿势。其余接口只需替换路径与请求体。

cURL：

bash

curl -X POST "https://<gateway-domain>/openapi/createPersonalFile" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "operatingObjectName": "my-agent",
    "name": "周报.md",
    "filePath": "https://oss.example.com/xxx/周报.md"
  }'

Python（requests）：

python

import requests

resp = requests.post(
    "https://<gateway-domain>/openapi/createPersonalFile",
    headers={
        "Authorization": "Bearer <AccessToken>",
        "Content-Type": "application/json",
    },
    json={
        "operatingObjectName": "my-agent",
        "name": "周报.md",
        "filePath": "https://oss.example.com/xxx/周报.md",
    },
)
print(resp.json())

Java（OkHttp）：

java

OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json");
String body = "{\"operatingObjectName\":\"my-agent\",\"name\":\"周报.md\",\"filePath\":\"https://oss.example.com/xxx/周报.md\"}";
Request request = new Request.Builder()
    .url("https://<gateway-domain>/openapi/createPersonalFile")
    .addHeader("Authorization", "Bearer <AccessToken>")
    .post(RequestBody.create(body, JSON))
    .build();
try (Response response = client.newCall(request).execute()) {
    System.out.println(response.body().string());
}

Go（net/http）：

payload := strings.NewReader(`{"operatingObjectName":"my-agent","name":"周报.md","filePath":"https://oss.example.com/xxx/周报.md"}`)
req, _ := http.NewRequest("POST", "https://<gateway-domain>/openapi/createPersonalFile", payload)
req.Header.Set("Authorization", "Bearer <AccessToken>")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))

Node.js（fetch）：

javascript

const resp = await fetch("https://<gateway-domain>/openapi/createPersonalFile", {
  method: "POST",
  headers: {
    Authorization: "Bearer <AccessToken>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    operatingObjectName: "my-agent",
    name: "周报.md",
    filePath: "https://oss.example.com/xxx/周报.md",
  }),
});
console.log(await resp.json());

常见错误码

错误码	含义	处理建议
`ERR.Auth.UnsupportedAuthType`	不支持的鉴权类型	检查 Token 前缀与 Authorization 头格式
`ERR.Auth.TenantIdRequired`	未指定租户且无法自动推断	多租户下传入 `tenantId` 或 `X-Tenant-Id`
`ERR.Auth.TenantAccessDenied`	无权访问该租户	确认当前用户属于目标租户
`ERR.User.NotFound`	用户不存在	检查用户标识是否正确
`ERR.Resource.NotFound`	资源不存在	检查资源 ID 是否正确、是否已删除
`ERR.Robject.UserDirectory.NotAuthorized`	无目录访问权限	确认数字员工对目标目录有可见/操作权限
`ERR.System.Error`	系统内部错误	携带 RequestId 联系管理员排查

注意事项

幂等调用：写接口可传 clientToken（调用方自行生成）用于幂等标识。
数字员工上下文：多数资源/知识/对象类接口需传 operatingObjectName（数字员工名称，即运营对象 name）来确定操作上下文与权限范围。
大文件上传：大文件走 OSS 直传——先调 getSourceUploadSignature 获取签名 URL，直传后再登记资源；会话内小文件可用 uploadChatFile 后端直传。
异步任务查询：runSkill 返回 runId，通过 getSkillRun 轮询执行状态与结果。
版本兼容：新增能力向后兼容，调用路径不变，历史接口持续可用。

接口总览

共 82 个接口，按能力域分组。

系统与实例（2 个）

接口	方法	路径	说明
checkHealth	GET	`/openapi/checkHealth`	健康检查与鉴权探测
getInstanceExpireTime	GET	`/openapi/getInstanceExpireTime`	获取实例到期时间

会话（7 个）

接口	方法	路径	说明
sendChatMessage	POST	`/openapi/v1/chatMessages`	发送会话消息
getChatSession	GET	`/openapi/v1/chatSession`	获取会话详情
listChatSessions	GET	`/openapi/v1/chatSession/list`	获取会话列表
updateChatSession	POST	`/openapi/v1/chatSession/update`	更新会话信息
stopChatSession	POST	`/openapi/v1/chatSession/stop`	停止会话生成
deleteChatSession	DELETE	`/openapi/v1/chatSession/delete`	删除会话
uploadChatFile	POST	`/openapi/v1/uploadChatFile`	上传会话文件

快捷技能（4 个）

接口	方法	路径	说明
listSkills	POST	`/openapi/listSkills`	查询技能列表
getSkill	POST	`/openapi/getSkill`	获取技能详情
runSkill	POST	`/openapi/runSkill`	异步执行技能
getSkillRun	POST	`/openapi/getSkillRun`	查询技能异步执行结果

我的资源（19 个）

接口	方法	路径	说明
createPersonalFile	POST	`/openapi/createPersonalFile`	创建个人文件资源
createPersonalText	POST	`/openapi/createPersonalText`	创建个人在线小记（文本）
createPersonalVoiceMeeting	POST	`/openapi/createPersonalVoiceMeeting`	创建个人语音会议记录
createPersonalDingtalkMeeting	POST	`/openapi/createPersonalDingtalkMeeting`	创建个人 DingTalk 会议记录
createPersonalAliDingMeeting	POST	`/openapi/createPersonalAliDingMeeting`	创建个人钉钉会议记录
createPersonalAliDingDoc	POST	`/openapi/createPersonalAliDingDoc`	创建个人钉钉文档资源
createPersonalAliDingKnowledgeBase	POST	`/openapi/createPersonalAliDingKnowledgeBase`	创建个人钉钉知识库资源
createPersonalFeishuMinute	POST	`/openapi/createPersonalFeishuMinute`	创建个人飞书妙记资源
createPersonalDirectory	POST	`/openapi/createPersonalDirectory`	创建个人资源目录
listPersonalDirectoryContents	POST	`/openapi/listPersonalDirectoryContents`	下钻查询我的资源目录内容
getSource	POST	`/openapi/getSource`	获取资源详情
getSourceUploadSignature	POST	`/openapi/getSourceUploadSignature`	获取资源上传签名
moveResource	POST	`/openapi/moveResource`	移动个人资源
renameSource	POST	`/openapi/renameSource`	重命名个人资源
updateDirectory	POST	`/openapi/updateDirectory`	更新个人资源目录
retryDirectoryFailedSources	POST	`/openapi/retryDirectoryFailedSources`	重试目录内失败资源
previewPersonalSource	POST	`/openapi/previewPersonalSource`	预览个人资源
listOutputFiles	POST	`/openapi/listOutputFiles`	查询当前用户产出列表
saveOutputFileToResource	POST	`/openapi/saveOutputFileToResource`	产出批量保存为个人资源

企业知识库（16 个）

接口	方法	路径	说明
listVisibleKnowledgeBases	POST	`/openapi/listVisibleKnowledgeBases`	查询数字员工可见知识库列表
listVisibleKnowledgeBaseContents	POST	`/openapi/listVisibleKnowledgeBaseContents`	下钻查询可见知识库目录内容
listAdminKnowledgeBases	POST	`/openapi/listAdminKnowledgeBases`	后台查询/下钻企业知识库
submitSourceToKnowledgeBase	POST	`/openapi/submitSourceToKnowledgeBase`	个人资源提交到企业知识库
createKnowledgeBaseFile	POST	`/openapi/createKnowledgeBaseFile`	创建知识库文件资源
createKnowledgeBaseText	POST	`/openapi/createKnowledgeBaseText`	创建知识库文本资源
createKnowledgeBaseAliDingDoc	POST	`/openapi/createKnowledgeBaseAliDingDoc`	创建知识库钉钉文档资源
createKnowledgeBaseDirectory	POST	`/openapi/createKnowledgeBaseDirectory`	创建知识库目录
getKnowledgeBaseSource	POST	`/openapi/getKnowledgeBaseSource`	获取知识库资源详情
listKnowledgeBaseDirectories	POST	`/openapi/listKnowledgeBaseDirectories`	查询知识库目录列表
updateKnowledgeBaseDirectory	POST	`/openapi/updateKnowledgeBaseDirectory`	更新知识库目录
moveKnowledgeBaseResource	POST	`/openapi/moveKnowledgeBaseResource`	移动企业知识库资源
renameKnowledgeBaseSource	POST	`/openapi/renameKnowledgeBaseSource`	重命名企业知识库资源
updateKnowledgeBaseSourceTags	POST	`/openapi/updateKnowledgeBaseSourceTags`	更新知识库资源标签
retryKnowledgeBaseFailedSources	POST	`/openapi/retryKnowledgeBaseFailedSources`	重试知识库失败资源
previewKnowledgeBaseSource	POST	`/openapi/previewKnowledgeBaseSource`	预览知识库资源

定时任务（8 个）

接口	方法	路径	说明
createScheduledTask	POST	`/openapi/createScheduledTask`	创建定时任务
updateScheduledTask	POST	`/openapi/updateScheduledTask`	更新定时任务
listScheduledTasks	POST	`/openapi/listScheduledTasks`	获取定时任务列表
executeScheduledTask	POST	`/openapi/executeScheduledTask`	立即执行定时任务
getScheduledTaskExecutionDetail	POST	`/openapi/getScheduledTaskExecutionDetail`	获取定时任务执行详情
getScheduledTaskExecutionRecords	POST	`/openapi/getScheduledTaskExecutionRecords`	获取定时任务执行记录
getScheduledTaskPushOptions	POST	`/openapi/getScheduledTaskPushOptions`	获取定时任务推送选项
getScheduledTaskUnderstandDetail	POST	`/openapi/getScheduledTaskUnderstandDetail`	获取定时任务理解详情

主对象数据（3 个）

接口	方法	路径	说明
queryPrimaryObjectData	POST	`/openapi/queryPrimaryObjectData`	分页查询主对象数据
togglePrimaryObjectFavorite	POST	`/openapi/togglePrimaryObjectFavorite`	关注/取消关注主对象
replaceObjectBindings	POST	`/openapi/replaceObjectBindings`	替换对象绑定关系

用户、Credit 与账单（4 个）

接口	方法	路径	说明
getUserInfo	GET	`/openapi/getUserInfo`	获取当前用户信息
updateUserInfo	POST	`/openapi/updateUserInfo`	更新当前用户信息
getUserCreditUsage	POST	`/openapi/getUserCreditUsage`	获取用户 Credit 用量
listBilling	POST	`/openapi/listBilling`	查询账单列表

用户与权限管理（15 个）

接口	方法	路径	说明
createUser	POST	`/openapi/createUser`	创建用户
updateUser	POST	`/openapi/updateUser`	更新用户
getUser	POST	`/openapi/getUser`	获取用户详情
listUsers	POST	`/openapi/listUsers`	查询用户列表
removeUser	POST	`/openapi/removeUser`	移除用户
resetPassword	POST	`/openapi/resetPassword`	重置用户密码
getTokenInfo	POST	`/openapi/getTokenInfo`	获取 Token 信息
enableToken	POST	`/openapi/enableToken`	启用用户 Token
disableToken	POST	`/openapi/disableToken`	停用用户 Token
resetToken	POST	`/openapi/resetToken`	重置用户 Token
grantAgentUsers	POST	`/openapi/grantAgentUsers`	授予数字员工用户权限
revokeAgentUsers	POST	`/openapi/revokeAgentUsers`	回收数字员工用户权限
listAuthorizedAgents	POST	`/openapi/listAuthorizedAgents`	查询已授权数字员工
listAuthorizedUsers	POST	`/openapi/listAuthorizedUsers`	查询已授权用户
updateAgentAuthMode	POST	`/openapi/updateAgentAuthMode`	更新数字员工授权模式

组织同步（4 个）

接口	方法	路径	说明
createCustomOrg	POST	`/openapi/createCustomOrg`	创建自定义组织
syncOrgStructure	POST	`/openapi/syncOrgStructure`	同步组织架构
querySyncResult	POST	`/openapi/querySyncResult`	查询组织同步结果
listAvailableConfigs	POST	`/openapi/listAvailableConfigs`	查询可用组织同步配置

系统与实例

checkHealth · 健康检查与鉴权探测

OpenAPI 入口健康检查，可用于探测鉴权是否生效及当前生效的调用方 / 租户 / 数字员工。

GET /openapi/checkHealth

请求：无请求体参数。

响应字段：

字段	类型	说明
`callerType`	str	调用方类型：user / aliyun_main / aliyun_ram / service
`authSource`	str	认证来源：bearer / aliyun_gateway
`userId`	int	平台用户 ID
`tenantId`	int	生效租户 ID
`digitalEmployeeName`	str	当前请求生效的数字员工名（运营对象）；未传且租户下无数字员工时为空

bash

curl -X GET "https://<gateway-domain>/openapi/checkHealth" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json"

getInstanceExpireTime · 查询租户标准包实例过期时间

OpenAPI 查询租户标准包实例过期时间。

POST /openapi/getInstanceExpireTime

请求：无请求体参数。

响应字段：

字段	类型	说明
`tenantId`	int	系统租户 ID
`instanceId`	str	实例 ID
`instanceExpireTime`	str	实例过期时间（ISO 格式）
`instanceStatus`	str	实例状态
`found`	bool	是否找到标准包实例

bash

curl -X POST "https://<gateway-domain>/openapi/getInstanceExpireTime" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{}'

会话

sendChatMessage · 发送会话消息

向会话发送消息，不传 sessionId 则新建会话。

POST /openapi/v1/chatMessages

请求字段：

字段	类型	必填	说明
`content`	str	✅	用户消息正文
`contentType`	str	❌	消息类型：Text / Markdown（默认 Text）
`sessionId`	str	❌	会话ID，不传则新建会话
`digitalEmployeeName`	str	❌	数字员工名称
`files`	list[FileRef]	❌	文件引用列表
`stream`	bool	❌	是否流式返回（默认 True）
`reuseLastSession`	bool	❌	不传 sessionId 时是否复用该数字员工最近一个会话（默认 False）

响应：仅返回通用包装字段 {"Code":"200","Message":"success","RequestId":"req-xxx"}（流式内容通过流通道推送）。

bash

curl -X POST "https://<gateway-domain>/openapi/v1/chatMessages" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"content":"帮我总结上周客户拜访","stream":true}'

getChatSession · 获取单个会话详情

OpenAPI 获取单个会话详情端点。

GET /openapi/v1/chatSession

Query 参数：

参数	类型	必填	说明
`sessionId`	string	❌	会话 ID

响应字段：

字段	类型	说明
`session`	ConversationInfo	会话信息
`messages`	list[ConversationMessageInfo]	最近消息列表

bash

curl -X GET "https://<gateway-domain>/openapi/v1/chatSession?sessionId=<sessionId>" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json"

listChatSessions · 获取会话列表

OpenAPI 会话列表端点。

GET /openapi/v1/chatSession/list

Query 参数：

参数	类型	必填	说明
`tenant_id`	string	❌	租户 ID
`page_size`	string	❌	每页数量
`page`	string	❌	页码
`keyword`	string	❌	关键词
`digital_employee_name`	string	❌	数字员工名称

响应字段：

字段	类型	说明
`data`	list[ConversationInfo]	会话列表
`total`	int	满足条件的总数
`page`	int	当前页码
`pageSize`	int	每页条数
`hasMore`	bool	是否有更多数据

bash

curl -X GET "https://<gateway-domain>/openapi/v1/chatSession/list?page=1&page_size=20" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json"

updateChatSession · 更新会话信息

更新会话标题等信息。

POST /openapi/v1/chatSession/update

请求字段：

字段	类型	必填	说明
`sessionId`	str	❌	会话ID
`title`	str	❌	新的会话标题

响应字段：

字段	类型	说明
`session`	ConversationInfo	更新后的会话信息

bash

curl -X POST "https://<gateway-domain>/openapi/v1/chatSession/update" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"12345","title":"客户拜访总结"}'

stopChatSession · 停止会话生成

停止指定会话当前正在生成的回复。

POST /openapi/v1/chatSession/stop

Query 参数：

参数	类型	必填	说明
`sessionId`	string	❌	会话 ID

请求字段：

字段	类型	必填	说明
`Reason`	str	❌	停止原因（审计用）

响应字段：

字段	类型	说明
`sessionId`	str	会话ID
`messageId`	str	被停止的消息ID
`status`	str	消息最终状态
`finishReason`	str	结束原因
`partialContent`	str	已生成的部分内容

bash

curl -X POST "https://<gateway-domain>/openapi/v1/chatSession/stop?sessionId=12345" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"Reason":"用户主动取消"}'

deleteChatSession · 删除会话

OpenAPI 删除会话端点。

DELETE /openapi/v1/chatSession/delete

Query 参数：

参数	类型	必填	说明
`sessionId`	string	❌	会话 ID

响应字段：

字段	类型	说明
`sessionId`	str	会话 ID
`deleted`	bool	是否删除成功
`hardDelete`	bool	是否硬删除

bash

curl -X DELETE "https://<gateway-domain>/openapi/v1/chatSession/delete?sessionId=<sessionId>" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json"

uploadChatFile · 会话文件上传

会话场景下的后端直传文件上传端点。

POST /openapi/v1/uploadChatFile

请求：无请求体参数（文件通过 multipart 形式上传）。

响应字段：

字段	类型	说明
`objectName`	str	OSS 对象路径
`fileUrl`	str	文件 remote_url（入库路径）
`filePublicUrl`	str	文件公开访问 URL（有效期 1 小时）
`uploadSignatureUrl`	str	签名上传 URL（本接口为后端直传，该字段为空）
`fileRecordId`	str	文件记录 ID
`contentType`	str	文件 MIME 类型
`fileName`	str	文件名

bash

curl -X POST "https://<gateway-domain>/openapi/v1/uploadChatFile" \
  -H "Authorization: Bearer <AccessToken>" \
  -F "file=@/path/to/local/file.pdf"

快捷技能

listSkills · 查询技能列表

OpenAPI 技能列表查询。

POST /openapi/listSkills

请求字段：

字段	类型	必填	说明
`filterType`	str	❌	筛选类型：ALL / BUILTIN / CUSTOM / DRAFT / ALL_WITH_DRAFTS（默认 ALL）
`tags`	list[str]	❌	按标签筛选，数组任一命中即匹配
`keyword`	str	❌	关键词搜索，模糊匹配名称或描述
`page`	int	❌	页码（默认 1）
`pageSize`	int	❌	每页数量，1-100（默认 20）
`operatingObjectName`	str	❌	数字员工名称；必须与 bindStatus 同时传入
`bindStatus`	str	❌	绑定状态：BOUND / UNBOUND；必须与 operatingObjectName 同时传入

响应字段：

字段	类型	说明
`items`	list[OpenAPISkillItem]	技能列表
`total`	int	符合条件的技能总数
`page`	int	当前页码
`pageSize`	int	每页数量

bash

curl -X POST "https://<gateway-domain>/openapi/listSkills" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"filterType":"BUILTIN","page":1,"pageSize":20}'

getSkill · 获取技能详情

OpenAPI 技能详情查询。

POST /openapi/getSkill

请求字段：

字段	类型	必填	说明
`skillCode`	str	❌	技能编码（全局唯一），优先级高于 skillName
`skillName`	str	❌	技能名称，未传 skillCode 时使用；租户范围内唯一
`viewMode`	str	❌	视角：draft（草稿）/ published（默认）
`includeSkillFiles`	bool	❌	是否返回完整文件树（默认 false）

响应字段（节选）：

字段	类型	说明
`skillHubDefinitionId`	int	技能定义 ID
`skillCode`	str	技能编码（全局唯一）
`name`	str	技能名称（已 i18n 解析）
`displayName`	str	展示名称
`description`	str	技能描述
`tags`	list[str]	标签列表
`sourceType`	str	来源类型：BUILTIN / CUSTOM
`globalAccess`	bool	是否全局可访问
`executeMode`	str	执行模式
`inputConfig`	str	入参配置原文
`inputConfigFormatted`	list[dict]	结构化入参 schema 数组
`detailLogic`	str	技能详细逻辑
`skillMdSummary`	str	SKILL.md 简介
`versionNumber`	str	版本号
`versionCount`	int	版本总数
`status`	str	技能状态：ACTIVE / DRAFT
`hasDraftChanges`	bool	是否存在未发布的草稿修改
`createdTime`	str	创建时间 ISO8601
`updatedTime`	str	修改时间 ISO8601
`arguments`	list[ArgumentSchema]	精简参数 schema，描述 runSkill.arguments 需要传什么
`skillFiles`	list[dict]	技能文件嵌套树（仅 includeSkillFiles=True）

bash

curl -X POST "https://<gateway-domain>/openapi/getSkill" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"skillCode":"skill-abc","viewMode":"published"}'

runSkill · 异步执行技能

提交技能异步执行，返回 runId，后续用 getSkillRun 轮询结果。

POST /openapi/runSkill

请求字段：

字段	类型	必填	说明
`skillCode`	str	❌	技能编码（全局唯一），优先级高于 skillName
`skillName`	str	❌	技能名称，未传 skillCode 时使用；租户范围内必须唯一
`arguments`	dict[str, Any]	❌	技能入参字典；schema 由 getSkill 的 arguments 字段描述
`clientToken`	str	❌	幂等 token，调用方自行生成（当前版本仅记录到 metadata）

响应字段：

字段	类型	说明
`runId`	str	异步任务 ID，用于 getSkillRun 查询
`skillCode`	str	实际执行的技能编码
`skillName`	str	技能名称
`status`	str	任务状态：提交即返回 Running
`createdAt`	str	任务创建时间，ISO8601 UTC 格式

bash

curl -X POST "https://<gateway-domain>/openapi/runSkill" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"skillName":"客户摘要","arguments":{"customer_id":"C-2026-0612"}}'

getSkillRun · 查询技能异步执行结果

OpenAPI 异步技能执行结果查询入口。

POST /openapi/getSkillRun

请求字段：

字段	类型	必填	说明
`runId`	str	❌	runSkill 返回的异步任务 ID
`includeLogs`	bool	❌	是否附带执行日志（默认 false）

响应字段：

字段	类型	说明
`runId`	str	异步任务 ID
`skillCode`	str	技能编码
`skillName`	str	技能名称
`status`	str	执行状态：Running / Succeeded / Failed / Cancelled
`progress`	int	进度百分比（仅 Running 时有意义）
`progressMessage`	str	进度描述
`result`	dict[str, Any]	执行结果，仅 Succeeded 时返回；包含 content 列表
`usage`	dict[str, Any]	LLM token 使用统计，仅 Succeeded 时返回
`logs`	list[dict[str, Any]]	执行日志列表（仅 includeLogs=true 时返回）
`errorCode`	str	错误码，仅 Failed 时返回
`errorMessage`	str	错误描述，仅 Failed 时返回
`createdAt`	str	任务创建时间 ISO8601
`startedAt`	str	任务开始执行时间 ISO8601
`finishedAt`	str	任务结束时间 ISO8601；仅终态有值

bash

curl -X POST "https://<gateway-domain>/openapi/getSkillRun" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"runId":"run_123","includeLogs":false}'

我的资源

createPersonalFile · 上传文件到我的资源

上传文件到当前数字员工的"我的资源"。

POST /openapi/createPersonalFile

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）
`name`	str	✅	资源显示名称
`filePath`	str	✅	文件 OSS 持久化地址
`filePublicUrl`	str	❌	文件公开访问 URL（带签名）
`fileName`	str	❌	原始文件名（含后缀）
`fileExt`	str	❌	文件后缀名（如 pdf、docx）
`fileRecordId`	str	❌	文件记录 ID
`directoryId`	str	❌	目标目录 ID
`description`	str	❌	资源描述

响应字段：

字段	类型	说明
`sourceId`	str	新建资源 ID
`name`	str	资源显示名称
`status`	str	资源状态
`scope`	str	资源 scope，固定为 PERSONAL
`directoryId`	str	绑定的目录 ID
`gmtCreate`	str	创建时间 ISO8601

bash

curl -X POST "https://<gateway-domain>/openapi/createPersonalFile" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent","name":"合同.pdf","filePath":"oss://bucket/path/to/file.pdf"}'

createPersonalText · 上传纯文本到我的资源

上传纯文本到当前数字员工的"我的资源"。

POST /openapi/createPersonalText

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）
`name`	str	✅	资源显示名称
`textContent`	str	✅	纯文本正文
`directoryId`	str	❌	目标目录 ID
`description`	str	❌	资源描述

响应字段：

字段	类型	说明
`sourceId`	str	新建资源 ID
`name`	str	资源显示名称
`status`	str	资源状态（初始多为 PENDING；失败则为 FAILED）
`scope`	str	资源 scope，固定为 PERSONAL
`directoryId`	str	绑定的目录 ID
`gmtCreate`	str	创建时间 ISO8601

bash

curl -X POST "https://<gateway-domain>/openapi/createPersonalText" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent","name":"备忘","textContent":"这是一段小记正文"}'

createPersonalVoiceMeeting · 上传离线会议到我的资源

上传离线会议音频到当前数字员工的"我的资源"。

POST /openapi/createPersonalVoiceMeeting

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）
`name`	str	✅	资源显示名称
`fileUrl`	str	✅	离线会议音频文件 URL
`directoryId`	str	❌	目标目录 ID
`description`	str	❌	资源描述

响应字段：

字段	类型	说明
`sourceId`	str	新建资源 ID
`name`	str	资源显示名称
`status`	str	资源状态（初始多为 PENDING；失败则为 FAILED）
`scope`	str	资源 scope，固定为 PERSONAL
`directoryId`	str	绑定的目录 ID
`gmtCreate`	str	创建时间 ISO8601

bash

curl -X POST "https://<gateway-domain>/openapi/createPersonalVoiceMeeting" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent","name":"客户拜访录音","fileUrl":"https://oss.example.com/a.mp3"}'

createPersonalDingtalkMeeting · 上传钉钉会议到我的资源

上传钉钉会议到当前数字员工的"我的资源"。

POST /openapi/createPersonalDingtalkMeeting

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）
`name`	str	✅	资源显示名称
`roomCode`	str	✅	钉钉会议号
`credentialId`	str	❌	凭证 ID（不传则使用系统默认配置）
`directoryId`	str	❌	目标目录 ID
`description`	str	❌	资源描述
`notes`	str	❌	会议笔记内容，会参与辅助分析

响应字段：

字段	类型	说明
`sourceId`	str	新建资源 ID
`name`	str	资源显示名称
`status`	str	资源状态
`scope`	str	资源 scope，固定为 PERSONAL
`directoryId`	str	绑定的目录 ID
`gmtCreate`	str	创建时间 ISO8601

bash

curl -X POST "https://<gateway-domain>/openapi/createPersonalDingtalkMeeting" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent","name":"客户会议","roomCode":"1234567890"}'

createPersonalAliDingMeeting · 上传阿里钉会议到我的资源

上传阿里钉会议到当前数字员工的"我的资源"。

POST /openapi/createPersonalAliDingMeeting

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）
`name`	str	✅	资源显示名称
`ossUrl`	str	✅	公开的音视频 OSS 地址
`shanjiUrl`	str	✅	原始的闪记链接
`directoryId`	str	❌	目标目录 ID
`description`	str	❌	资源描述
`notes`	str	❌	会议笔记内容，会参与辅助分析

响应字段：

字段	类型	说明
`sourceId`	str	新建资源 ID
`name`	str	资源显示名称
`status`	str	资源状态
`scope`	str	资源 scope，固定为 PERSONAL
`directoryId`	str	绑定的目录 ID
`gmtCreate`	str	创建时间 ISO8601

bash

curl -X POST "https://<gateway-domain>/openapi/createPersonalAliDingMeeting" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent","name":"周会","ossUrl":"https://oss.example.com/a.mp4","shanjiUrl":"https://shanji.example.com/x"}'

createPersonalAliDingDoc · 上传阿里钉在线文档到我的资源

上传阿里钉在线文档到当前数字员工的"我的资源"。

POST /openapi/createPersonalAliDingDoc

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）
`name`	str	✅	资源显示名称（建议传入钉钉文档标题）
`filePublicUrl`	str	✅	阿里钉在线文档的可公开访问 URL
`directoryId`	str	❌	目标目录 ID
`description`	str	❌	资源描述

响应字段：

字段	类型	说明
`sourceId`	str	新建资源 ID
`name`	str	资源显示名称
`status`	str	资源状态（初始多为 PENDING；on_create 失败则为 FAILED）
`scope`	str	资源 scope，固定为 PERSONAL
`directoryId`	str	绑定的目录 ID（缺省走默认根目录时为 null）
`filePublicUrl`	str	文档公开 URL（echo 回入参）
`gmtCreate`	str	创建时间 ISO8601

bash

curl -X POST "https://<gateway-domain>/openapi/createPersonalAliDingDoc" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent","name":"产品方案","filePublicUrl":"https://doc.example.com/x"}'

createPersonalAliDingKnowledgeBase · 创建阿里钉整体知识库到我的资源

创建阿里钉整体知识库到当前数字员工的"我的资源"。

POST /openapi/createPersonalAliDingKnowledgeBase

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）
`kbUrl`	str	✅	阿里钉知识库的可公开访问 URL
`kbName`	str	❌	知识库显示名称；不传时由后台从远程根节点名称回填
`directoryId`	str	❌	目标目录 ID
`objectBindings`	list[ObjectBinding]	❌	多值对象绑定列表；写入知识库 metadata，同步时透传给子节点 source
`syncConfig`	SyncConfig	❌	定时同步配置；不传时按禁用处理

响应字段：

字段	类型	说明
`directoryId`	str	新建知识库根目录 ID
`name`	str	知识库显示名称
`status`	str	根目录状态（创建后 RUNNING；同步完成转 READY 或 FAILED）
`kbUrl`	str	知识库 URL（echo 回入参）
`operatingObjectName`	str	所属数字员工名称（echo 回入参）
`gmtCreate`	str	创建时间 ISO8601

bash

curl -X POST "https://<gateway-domain>/openapi/createPersonalAliDingKnowledgeBase" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent","kbUrl":"https://kb.example.com/x"}'

createPersonalFeishuMinute · 上传飞书妙记会议到我的资源

上传飞书妙记会议到当前数字员工的"我的资源"。

POST /openapi/createPersonalFeishuMinute

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）
`name`	str	✅	资源显示名称
`minuteToken`	str	✅	飞书妙记 token（妙记唯一标识符）
`credentialId`	str	✅	凭证 ID（关联 rbj_credential 表）
`directoryId`	str	❌	目标目录 ID
`description`	str	❌	资源描述

响应字段：

字段	类型	说明
`sourceId`	str	新建资源 ID
`name`	str	资源显示名称
`status`	str	资源状态
`scope`	str	资源 scope，固定为 PERSONAL
`directoryId`	str	绑定的目录 ID
`gmtCreate`	str	创建时间 ISO8601

bash

curl -X POST "https://<gateway-domain>/openapi/createPersonalFeishuMinute" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent","name":"周会纪要","minuteToken":"minute_xxx","credentialId":"cred_1"}'

createPersonalDirectory · 在我的资源下创建个人目录

在"我的资源"下创建个人目录（分类）。

POST /openapi/createPersonalDirectory

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）
`name`	str	✅	目录名称
`parentDirectoryId`	str	❌	父目录 ID
`description`	str	❌	目录描述

响应字段：

字段	类型	说明
`directoryId`	str	新建目录 ID
`name`	str	目录名称
`path`	str	目录完整路径（自动计算）
`description`	str	目录描述
`parentDirectoryId`	str	父目录 ID（回填默认根目录时返回回填后的 ID）
`operatingObjectName`	str	所属数字员工名称
`directoryKind`	str	目录 KB 归属类型：normal / aliding_kb_root / aliding_kb_internal
`gmtCreate`	int	创建时间戳（毫秒）
`gmtModified`	int	修改时间戳（毫秒）

bash

curl -X POST "https://<gateway-domain>/openapi/createPersonalDirectory" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent","name":"合同模板"}'

listPersonalDirectoryContents · 下钻查询我的资源目录内容

下钻查询"我的资源"目录下的子目录与资源。

POST /openapi/listPersonalDirectoryContents

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）
`directoryId`	str	✅	目录 ID
`page`	int	❌	页码（默认 1）
`pageSize`	int	❌	每页数量，1-100（默认 20）
`sortField`	str	❌	排序字段：name / gmt_create / gmt_modified（默认 name）
`sortOrder`	str	❌	排序方向：asc / desc（默认 asc）
`sourceTypes`	list[str]	❌	资源类型筛选

响应字段：

字段	类型	说明
`items`	list[PersonalDirectoryContentItem]	目录下内容（子目录 + 资源）统一分页列表
`total`	int	总数（不分页前的命中行数）
`page`	int	当前页码
`pageSize`	int	每页数量

bash

curl -X POST "https://<gateway-domain>/openapi/listPersonalDirectoryContents" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent","directoryId":"dir_1"}'

getSource · 获取数据源详情

OpenAPI 数据源详情查询。

POST /openapi/getSource

请求字段：

字段	类型	必填	说明
`sourceId`	str	❌	数据源 ID（租户内唯一）
`includeDetails`	bool	❌	是否返回详情（默认 false）

响应字段：

字段	类型	说明
`sourceId`	str	数据源 ID
`sourceType`	str	数据源类型
`sourceKind`	str	数据源归属类型：normal / aliding_kb_doc
`name`	str	数据源名称
`description`	str	数据源描述
`status`	str	数据源状态
`scope`	str	可见范围：PERSONAL / TENANT
`objectType`	str	主对象类型（兼容字段）
`objectId`	str	主对象 ID（兼容字段）
`operatingObjectName`	str	运营对象名称
`objectBindings`	list[ObjectBindingItem]	多值对象绑定列表
`skillOutputId`	str	技能产出 ID
`sourceTags`	str	资源标签 JSON 字符串
`hasSettings`	bool	是否存在 settings 配置
`hasNotes`	bool	是否存在备注
`hasStructuredTables`	bool	是否存在结构化表
`hasUnstructuredDocs`	bool	是否存在非结构化文档
`gmtCreate`	str	创建时间 ISO8601
`gmtModified`	str	修改时间 ISO8601
`settings`	dict	数据源配置（仅 includeDetails=True）
`notes`	str	备注（仅 includeDetails=True）
`structuredTables`	list[str]	结构化表名列表（仅 includeDetails=True）
`unstructuredDocs`	list[UnstructuredDocItem]	非结构化文档明细（仅 includeDetails=True；不含 content）

bash

curl -X POST "https://<gateway-domain>/openapi/getSource" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"src_1234567890","includeDetails":true}'

getSourceUploadSignature · 获取数据源文件 OSS 直传签名 URL

获取数据源文件 OSS 直传签名 URL，用于大文件直传。

POST /openapi/getSourceUploadSignature

请求字段：

字段	类型	必填	说明
`filename`	str	✅	文件名（含后缀，如 report.pdf）
`operatingObjectName`	str	❌	Agent 命名空间标识（数字员工名称）
`expires`	int	❌	签名 URL 过期时间（秒），默认 3600
`contentType`	str	❌	文件 Content-Type（不传则自动推断）
`scope`	str	❌	归属范围：source（个人，映射 PERSONAL）/ knowledge（企业知识库，映射 TENANT）

响应字段：

字段	类型	说明
`objectName`	str	OSS 对象名
`fileUrl`	str	文件 OSS 内部 URL
`filePublicUrl`	str	文件公开访问 URL
`uploadSignatureUrl`	str	签名上传 URL（PUT 方式）
`fileRecordId`	str	文件记录 ID
`method`	str	上传 HTTP 方法（固定为 PUT）
`expiresIn`	int	签名 URL 有效时长（秒）
`contentType`	str	文件 Content-Type

bash

curl -X POST "https://<gateway-domain>/openapi/getSourceUploadSignature" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"filename":"report.pdf","scope":"source"}'

moveResource · 在个人目录间移动资源

在个人目录间移动资源。

POST /openapi/moveResource

请求字段：

字段	类型	必填	说明
`sourceDirectoryId`	str	✅	源目录 ID（资源当前所在的个人目录）
`targetDirectoryId`	str	✅	目标目录 ID（资源即将移动到的个人目录）
`sourceId`	str	✅	待移动的资源 ID

响应字段：

字段	类型	说明
`success`	bool	是否移动成功
`sourceId`	str	资源 ID（echo 回入参）
`sourceDirectoryId`	str	源目录 ID（echo 回入参）
`targetDirectoryId`	str	目标目录 ID（echo 回入参）

bash

curl -X POST "https://<gateway-domain>/openapi/moveResource" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sourceDirectoryId":"dir_1","targetDirectoryId":"dir_2","sourceId":"src_1"}'

renameSource · 重命名数据源

重命名数据源（轻量级操作）。

POST /openapi/renameSource

请求字段：

字段	类型	必填	说明
`sourceId`	str	✅	数据源 ID（租户内唯一）
`newName`	str	✅	新的数据源名称

响应字段：

字段	类型	说明
`sourceId`	str	数据源 ID
`name`	str	重命名后的数据源名称
`status`	str	数据源状态
`gmtModified`	str	最近修改时间，ISO8601 格式

bash

curl -X POST "https://<gateway-domain>/openapi/renameSource" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"src_1234567890","newName":"客户合同-最终版"}'

updateDirectory · 更新个人目录

更新个人目录基础信息。

POST /openapi/updateDirectory

请求字段：

字段	类型	必填	说明
`directoryId`	str	✅	目录唯一标识（业务 ID，非主键 ID）
`name`	str	❌	新目录名称；缺省表示不更新
`description`	str	❌	新目录描述；缺省表示不更新
`parentId`	int	❌	新父目录主键 ID；缺省表示不更新父目录
`path`	str	❌	新目录路径；传入时会级联更新当前目录及全部子目录的 path

响应字段：

字段	类型	说明
`success`	bool	是否更新成功
`directoryId`	str	目录唯一标识（echo 回入参）

bash

curl -X POST "https://<gateway-domain>/openapi/updateDirectory" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"directoryId":"dir_1234567890","name":"客户资料"}'

retryDirectoryFailedSources · 重试个人目录下失败数据源

获取个人目录下失败的数据源并批量重试（递归包含子目录）。

POST /openapi/retryDirectoryFailedSources

请求字段：

字段	类型	必填	说明
`directoryId`	str	✅	目录 ID（递归包含子目录下的失败资源）

响应字段：

字段	类型	说明
`directoryId`	str	目录 ID
`failedCount`	int	目录下失败资源总数
`enqueuedCount`	int	成功入队重试的数量
`skippedCount`	int	跳过（非 FAILED 或无权限）的数量
`enqueuedIds`	list[str]	成功入队的 source_id 列表
`failedSources`	list[FailedSourceItem]	目录下检测到的失败数据源列表

bash

curl -X POST "https://<gateway-domain>/openapi/retryDirectoryFailedSources" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"directoryId":"dir_1234567890"}'

previewPersonalSource · 预览个人知识库知识

预览个人知识库下指定知识的内容（仅允许预览本人资源，PERSONAL 类型目录）。

POST /openapi/previewPersonalSource

请求字段：

字段	类型	必填	说明
`sourceId`	str	✅	知识 ID（数据源唯一标识）

响应字段：

字段	类型	说明
`previewType`	str	预览类型：OSS_IMM / IMAGE / AUDIO / VIDEO / HTML / DING_TALK / VOICE_MEETING / CONTENT
`previewUrl`	str	预览 URL（OSS_IMM、DING_TALK、VOICE_MEETING 使用）
`content`	str	文本内容（CONTENT 类型使用）
`fileName`	str	文件名（OSS_IMM 类型使用）
`fileExt`	str	文件扩展名（OSS_IMM 类型使用）
`publicUrl`	str	公开下载 URL

bash

curl -X POST "https://<gateway-domain>/openapi/previewPersonalSource" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"src_123"}'

listOutputFiles · 查询当前用户产出列表

查询当前用户的产出列表。

POST /openapi/listOutputFiles

请求：无请求体参数。

响应字段：

字段	类型	说明
`items`	list[ListOutputFilesRecord]	产出列表
`total`	int	符合条件的产出总数
`page`	int	当前页码
`pageSize`	int	每页数量

bash

curl -X POST "https://<gateway-domain>/openapi/listOutputFiles" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{}'

saveOutputFileToResource · 将产出批量保存为个人资源

将产出明细批量保存为个人资源（链接引用或拷贝）。

POST /openapi/saveOutputFileToResource

请求字段：

字段	类型	必填	说明
`itemIds`	list[str]	❌	产出明细 ID 列表，单批最多 50 条
`mode`	Literal["link","copy"]	❌	保存方式：link-链接引用，copy-拷贝入库
`directoryId`	str	❌	目标个人目录 ID

响应字段：

字段	类型	说明
`results`	list[SaveOutputFileToResourceItem]	逐条结果，与入参 itemIds 同序；单条失败不影响其他

bash

curl -X POST "https://<gateway-domain>/openapi/saveOutputFileToResource" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"itemIds":["item_1"],"mode":"link","directoryId":"dir_1"}'

企业知识库

listVisibleKnowledgeBases · 查询数字员工可见知识库列表

查询数字员工可见的企业知识库顶层目录。

POST /openapi/listVisibleKnowledgeBases

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）

响应字段：

字段	类型	说明
`items`	list[VisibleKnowledgeBaseItem]	数字员工可见的企业知识库顶层目录列表
`total`	int	返回条数（不分页）

bash

curl -X POST "https://<gateway-domain>/openapi/listVisibleKnowledgeBases" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent"}'

listVisibleKnowledgeBaseContents · 下钻查询可见知识库目录内容

下钻查询数字员工可见知识库目录下的子目录与资源。

POST /openapi/listVisibleKnowledgeBaseContents

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称（运营对象 name）
`directoryId`	str	✅	目录 ID（必传非空，需在数字员工 linked_directories 及子目录范围内）
`page`	int	❌	页码（默认 1）
`pageSize`	int	❌	每页数量，1-100（默认 20）
`sortField`	str	❌	排序字段：name / gmt_create / gmt_modified（默认 name）
`sortOrder`	str	❌	排序方向：asc / desc（默认 asc）
`sourceTypes`	list[str]	❌	资源类型筛选（有值时仅返回资源）

响应字段：

字段	类型	说明
`items`	list[VisibleKnowledgeBaseContentItem]	目录下内容统一分页列表
`total`	int	总数（不分页前的命中行数）
`page`	int	当前页码
`pageSize`	int	每页数量

bash

curl -X POST "https://<gateway-domain>/openapi/listVisibleKnowledgeBaseContents" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"my-agent","directoryId":"dir_1"}'

listAdminKnowledgeBases · 后台查询/下钻企业知识库

后台企业知识库列表 / 下钻查询。

POST /openapi/listAdminKnowledgeBases

请求字段：

字段	类型	必填	说明
`directoryId`	str	❌	目录 ID（下钻时传入）
`page`	int	❌	页码（默认 1）
`pageSize`	int	❌	每页数量，1-100（默认 20）
`sortField`	str	❌	排序字段：name / gmtCreate / gmtModified（默认 name）
`sortOrder`	str	❌	排序方向：asc / desc（默认 asc）
`keyword`	str	❌	搜索关键词，仅 directoryId 为空/root 时生效
`sourceTypes`	list[str]	❌	资源类型过滤，仅下钻时生效

响应字段：

字段	类型	说明
`items`	list[AdminKnowledgeBaseItem]	内容列表（KB 列表仅 directory；下钻含 directory + resource）
`total`	int	符合条件的总数
`page`	int	当前页码
`pageSize`	int	每页数量

bash

curl -X POST "https://<gateway-domain>/openapi/listAdminKnowledgeBases" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"pageSize":20,"sortField":"name","sortOrder":"asc"}'

submitSourceToKnowledgeBase · 将个人资源提交到企业知识库

将个人资源提交到企业知识库（租户目录）。

POST /openapi/submitSourceToKnowledgeBase

请求字段：

字段	类型	必填	说明
`sourceId`	str	✅	要提交的个人资源ID（必须 scope=PERSONAL 且当前用户为 creator）
`targetDirectoryId`	str	✅	目标企业知识库目录ID（必须为 TENANT 类型目录）

响应字段：

字段	类型	说明
`sourceId`	str	资源ID（迁移后保持不变）
`scope`	str	提交后资源 scope，成功路径下固定为 TENANT
`targetDirectoryId`	str	资源当前绑定的目标企业知识库目录ID

bash

curl -X POST "https://<gateway-domain>/openapi/submitSourceToKnowledgeBase" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"src_1234567890","targetDirectoryId":"dir_1234567890"}'

createKnowledgeBaseFile · 上传文件到企业知识库

上传文件到企业知识库（需要知识库管理权限）。

POST /openapi/createKnowledgeBaseFile

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	❌	数字员工名称（运营对象 name）
`name`	str	✅	资源显示名称
`filePath`	str	✅	文件 OSS 持久化地址
`filePublicUrl`	str	❌	文件公开访问 URL（带签名）
`fileName`	str	❌	原始文件名（含后缀）
`fileExt`	str	❌	文件后缀名（如 pdf、docx）
`fileRecordId`	str	❌	文件记录 ID
`directoryId`	str	❌	目标分类 ID
`description`	str	❌	资源描述
`knowledgeId`	str	❌	知识库 ID
`sourceTags`	str	❌	资源标签（JSON 字符串列表）

响应字段：

字段	类型	说明
`sourceId`	str	新建资源 ID
`name`	str	资源显示名称
`status`	str	资源状态
`scope`	str	资源 scope，固定为 TENANT
`directoryId`	str	绑定的目录 ID
`gmtCreate`	str	创建时间 ISO8601

bash

curl -X POST "https://<gateway-domain>/openapi/createKnowledgeBaseFile" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"name":"合同模板.pdf","filePath":"oss://bucket/path/to/file.pdf","directoryId":"dir_1"}'

createKnowledgeBaseText · 上传纯文本到企业知识库

上传纯文本到企业知识库（需要知识库管理权限）。

POST /openapi/createKnowledgeBaseText

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	❌	数字员工名称
`name`	str	✅	资源显示名称
`textContent`	str	✅	纯文本正文
`directoryId`	str	❌	目标分类 ID
`description`	str	❌	资源描述
`knowledgeId`	str	❌	知识库 ID
`sourceTags`	str	❌	资源标签（JSON 字符串列表）

响应字段：sourceId / name / status / scope(TENANT) / directoryId / gmtCreate（同 createKnowledgeBaseFile）。

bash

curl -X POST "https://<gateway-domain>/openapi/createKnowledgeBaseText" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"name":"客户服务规范","textContent":"一、服务原则...","directoryId":"dir_1"}'

createKnowledgeBaseAliDingDoc · 上传阿里钉在线文档到企业知识库

上传阿里钉在线文档到企业知识库（需要知识库管理权限）。

POST /openapi/createKnowledgeBaseAliDingDoc

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	❌	数字员工名称
`name`	str	✅	资源显示名称（建议传入钉钉文档标题）
`filePublicUrl`	str	✅	阿里钉在线文档的可公开访问 URL
`directoryId`	str	❌	目标分类 ID
`description`	str	❌	资源描述
`knowledgeId`	str	❌	知识库 ID
`sourceTags`	str	❌	资源标签（JSON 字符串列表）

响应字段：sourceId / name / status / scope(TENANT) / directoryId / filePublicUrl / gmtCreate。

bash

curl -X POST "https://<gateway-domain>/openapi/createKnowledgeBaseAliDingDoc" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"name":"产品需求文档","filePublicUrl":"https://alidocs.dingtalk.com/i/xxx","directoryId":"dir_1"}'

createKnowledgeBaseDirectory · 创建企业知识库分类

创建企业知识库分类（租户目录，需要知识库管理权限）。

POST /openapi/createKnowledgeBaseDirectory

请求字段：

字段	类型	必填	说明
`name`	str	✅	分类名称（企业知识库目录名称）
`parentDirectoryId`	str	❌	父分类 ID；不传挂在租户根目录下
`description`	str	❌	分类描述

响应字段：

字段	类型	说明
`directoryId`	str	新建分类 ID
`name`	str	分类名称
`path`	str	分类完整路径（自动计算）
`description`	str	分类描述
`parentDirectoryId`	str	父分类 ID；挂在根目录时返回 null
`directoryKind`	str	目录 KB 归属类型：normal / aliding_kb_root / aliding_kb_internal
`gmtCreate`	int	创建时间戳（毫秒）
`gmtModified`	int	修改时间戳（毫秒）

bash

curl -X POST "https://<gateway-domain>/openapi/createKnowledgeBaseDirectory" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"name":"合同模板","description":"各类标准合同"}'

getKnowledgeBaseSource · 获取企业知识库知识详情

获取企业知识库下指定知识的详情（需要知识库查看权限）。

POST /openapi/getKnowledgeBaseSource

请求字段：

字段	类型	必填	说明
`sourceId`	str	❌	知识 ID（数据源唯一标识）

响应字段：

字段	类型	说明
`sourceId`	str	知识 ID
`sourceType`	str	知识类型（TEXT / FILE / ONLINE_DOC 等）
`name`	str	知识名称
`description`	str	知识描述
`status`	str	处理状态（READY / RUNNING / FAILED 等）
`statusMessage`	str	状态附加信息（如失败原因）
`sourceKind`	str	知识 KB 归属类型：aliding_kb_doc / normal
`sourceTags`	str	知识标签（JSON 字符串列表）
`directoryId`	str	所属分类 ID
`directoryPath`	str	所属分类完整路径
`gmtCreate`	int	创建时间戳（毫秒）
`gmtModified`	int	修改时间戳（毫秒）

bash

curl -X POST "https://<gateway-domain>/openapi/getKnowledgeBaseSource" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"src_1234567890"}'

listKnowledgeBaseDirectories · 获取企业知识库分类列表

获取企业知识库分类列表（子目录树，需要知识库查看权限）。

POST /openapi/listKnowledgeBaseDirectories

请求字段：

字段	类型	必填	说明
`directoryId`	str	❌	父分类 ID；不传时返回根目录下所有分类树
`sortField`	str	❌	排序字段：name / gmt_create / gmt_modified（默认 gmt_create）
`sortOrder`	str	❌	排序方向：asc / desc（默认 desc）

响应字段：

字段	类型	说明
`directories`	list[dict[str, Any]]	分类树（嵌套，含 directoryId/name/description/path/directoryKind/gmtCreate/gmtModified/children）
`totalCount`	int	分类总数

bash

curl -X POST "https://<gateway-domain>/openapi/listKnowledgeBaseDirectories" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sortField":"gmt_create","sortOrder":"desc"}'

updateKnowledgeBaseDirectory · 修改企业知识库分类

修改企业知识库分类（租户目录，需要知识库管理权限）。

POST /openapi/updateKnowledgeBaseDirectory

请求字段：

字段	类型	必填	说明
`directoryId`	str	✅	待修改的分类 ID
`name`	str	❌	新分类名称；不传不更新
`description`	str	❌	新分类描述；不传不更新
`parentDirectoryId`	str	❌	新父分类 ID；不传不移动，传入需为当前租户已存在的知识库目录

响应字段：

字段	类型	说明
`success`	bool	是否更新成功
`directoryId`	str	分类 ID（echo 回入参）

bash

curl -X POST "https://<gateway-domain>/openapi/updateKnowledgeBaseDirectory" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"directoryId":"dir_1234567890","name":"标准合同模板"}'

moveKnowledgeBaseResource · 在企业知识库目录间移动资源

在企业知识库目录间移动资源（需要知识库管理权限）。

POST /openapi/moveKnowledgeBaseResource

请求字段：

字段	类型	必填	说明
`sourceDirectoryId`	str	✅	源目录 ID
`targetDirectoryId`	str	✅	目标目录 ID
`sourceId`	str	✅	待移动的资源 ID
`knowledgeId`	str	✅	目标知识库 ID

响应字段：sourceId / sourceDirectoryId / targetDirectoryId / knowledgeId（均 echo 回入参）。

bash

curl -X POST "https://<gateway-domain>/openapi/moveKnowledgeBaseResource" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sourceDirectoryId":"dir_1","targetDirectoryId":"dir_2","sourceId":"src_1","knowledgeId":"kb_1"}'

renameKnowledgeBaseSource · 重命名企业知识库数据源

重命名企业知识库中的数据源（需要知识库管理权限）。

POST /openapi/renameKnowledgeBaseSource

请求字段：

字段	类型	必填	说明
`sourceId`	str	✅	数据源 ID（租户内唯一）
`newName`	str	✅	新的数据源名称

响应字段：sourceId / name / status / gmtModified（同 renameSource）。

bash

curl -X POST "https://<gateway-domain>/openapi/renameKnowledgeBaseSource" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"src_1234567890","newName":"公司制度-2026"}'

updateKnowledgeBaseSourceTags · 更新企业知识库数据源标签

更新企业知识库数据源的资源标签（需要知识库管理权限）。

POST /openapi/updateKnowledgeBaseSourceTags

请求字段：

字段	类型	必填	说明
`sourceId`	str	✅	数据源 ID（租户内唯一）
`sourceTags`	str	❌	资源标签（JSON 字符串列表）

响应字段：

字段	类型	说明
`sourceId`	str	数据源 ID
`sourceTags`	str	更新后的资源标签
`gmtModified`	str	最近修改时间，ISO8601 格式

bash

curl -X POST "https://<gateway-domain>/openapi/updateKnowledgeBaseSourceTags" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"src_1234567890","sourceTags":"[\"合同\",\"2026\"]"}'

retryKnowledgeBaseFailedSources · 重试企业知识库目录下失败数据源

获取企业知识库目录下失败的数据源并批量重试（递归包含子目录）。

POST /openapi/retryKnowledgeBaseFailedSources

请求字段：

字段	类型	必填	说明
`directoryId`	str	✅	企业知识库目录 ID（递归包含子目录）

响应字段：directoryId / failedCount / enqueuedCount / skippedCount / enqueuedIds / failedSources（同 retryDirectoryFailedSources，failedSources 为 list[KbFailedSourceItem]）。

bash

curl -X POST "https://<gateway-domain>/openapi/retryKnowledgeBaseFailedSources" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"directoryId":"dir_1234567890"}'

previewKnowledgeBaseSource · 预览企业知识库知识

预览企业知识库下指定知识的内容（需要 DEVELOPMENT_KB_VIEW 知识库查看权限，TENANT 类型目录）。

POST /openapi/previewKnowledgeBaseSource

请求字段：

字段	类型	必填	说明
`sourceId`	str	✅	知识 ID（数据源唯一标识）

响应字段：previewType / previewUrl / content / fileName / fileExt / publicUrl（同 previewPersonalSource）。

bash

curl -X POST "https://<gateway-domain>/openapi/previewKnowledgeBaseSource" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"src_123"}'

定时任务

createScheduledTask · 创建定时任务

创建定时任务。

POST /openapi/createScheduledTask

请求字段：

字段	类型	必填	说明
`name`	str	✅	任务名称（最多 50 字）
`description`	list[SegmentItem]	❌	任务描述（segments 格式），支持 text/web_search/mention/skill 类型
`digitalEmployeeName`	str	❌	数字员工名称
`triggerConfig`	TriggerConfigRequest	❌	触发配置，含触发模式、Cron 表达式等；timezone/language 由服务端自动注入
`taskDetail`	TaskDetailRequest	❌	任务详情（理解结果回传），含任务理解、相关语义、相关对象、相关技能
`isOpen`	bool	❌	是否公开访问（默认 true）
`segments`	list[SegmentItem]	❌	富文本消息片段，支持 @对象（type=mention）和 /技能（type=skill）

响应字段：

字段	类型	说明
`taskId`	str	新建任务 ID

bash

curl -X POST "https://<gateway-domain>/openapi/createScheduledTask" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"name":"每日销售报告","digitalEmployeeName":"销售助手"}'

updateScheduledTask · 更新定时任务

更新已有定时任务定义。

POST /openapi/updateScheduledTask

请求字段：

字段	类型	必填	说明
`taskId`	str	✅	任务 ID
`name`	str	❌	任务名称（最多50字）
`description`	list[SegmentItem]	❌	任务描述（segments 格式），支持 text/web_search/mention/skill
`digitalEmployeeName`	str	❌	数字员工名称
`triggerConfig`	TriggerConfigRequest	❌	触发配置（触发模式、Cron 等）；timezone/language 服务端自动注入
`taskDetail`	TaskDetailRequest	❌	任务详情（理解结果回传）
`isOpen`	bool	❌	是否公开访问
`segments`	list[SegmentItem]	❌	富文本消息片段，支持 @对象与 /技能

响应字段：

字段	类型	说明
`taskId`	str	任务 ID（回显）
`updated`	bool	是否实际产生更新

bash

curl -X POST "https://<gateway-domain>/openapi/updateScheduledTask" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"taskId":"12345","name":"每日销售日报","isOpen":false}'

listScheduledTasks · 获取定时任务列表

获取当前用户的定时任务列表。

POST /openapi/listScheduledTasks

请求字段：

字段	类型	必填	说明
`page`	int	❌	页码（默认 1）
`pageSize`	int	❌	每页条数（1~100，默认 20）
`keyword`	str	❌	任务名模糊搜索
`digitalEmployeeName`	str	❌	按数字员工名称过滤

响应字段：

字段	类型	说明
`items`	list[ScheduledTaskItem]	任务列表
`total`	int	满足条件的总数
`page`	int	当前页码
`pageSize`	int	每页条数
`hasMore`	bool	是否有更多数据

bash

curl -X POST "https://<gateway-domain>/openapi/listScheduledTasks" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"pageSize":20}'

executeScheduledTask · 立即执行定时任务

立即执行指定的定时任务，创建手动触发的执行记录，并返回可透传给 Chat 链路的任务执行元数据。

POST /openapi/executeScheduledTask

请求字段：

字段	类型	必填	说明
`taskId`	str	✅	任务 ID

响应字段：

字段	类型	说明
`executionId`	str	执行记录 ID
`taskExecution`	ScheduledTaskExecutionPayload	可透传给 Chat metadata.task_execution 的执行元数据

taskExecution（ScheduledTaskExecutionPayload）结构：

字段	类型	说明
`taskId`	str	任务 ID
`executionId`	str	执行记录 ID
`taskUnderstand`	str	任务理解内容
`operatingObjectName`	str	数字员工名称
`skillCodes`	array<str>	关联技能编码列表
`enableWebSearch`	boolean	是否启用联网搜索
`billingId`	str	计费 ID，供 Chat 回调结束计费
`tenantId`	str	任务所属租户 ID
`userId`	str	任务所属用户 ID
`taskName`	str	任务名称
`model`	str	执行模型档位：model_max(旗舰)/model_plus(标准)/model_flash(轻量)

bash

curl -X POST "https://<gateway-domain>/openapi/executeScheduledTask" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"taskId":"task_123"}'

getScheduledTaskExecutionDetail · 获取定时任务执行详情

获取单条执行记录的完整详情。

POST /openapi/getScheduledTaskExecutionDetail

请求字段：

字段	类型	必填	说明
`executionId`	str	✅	执行记录 ID

响应字段：

字段	类型	说明
`executionId`	str	执行 ID
`taskId`	str	任务 ID
`triggerType`	str	触发类型
`digitalEmployeeName`	str	数字员工名称
`triggerInfo`	dict[str, Any]	触发信息
`status`	str	执行状态
`skillCodes`	list[str]	关联技能编码列表
`title`	str	执行结果标题
`content`	str	执行完整内容
`outputContent`	str	结构化输出内容
`errorMessage`	str	错误信息
`metadata`	dict[str, Any]	元数据
`files`	list[dict[str, Any]]	产出文件列表
`startedAt`	str	开始时间 ISO8601
`completedAt`	str	完成时间 ISO8601
`creator`	str	创建人
`gmtCreate`	str	创建时间 ISO8601

bash

curl -X POST "https://<gateway-domain>/openapi/getScheduledTaskExecutionDetail" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"executionId":"exec_456"}'

getScheduledTaskExecutionRecords · 获取定时任务执行记录

按操作对象聚合查询所有任务的执行记录时间线。

POST /openapi/getScheduledTaskExecutionRecords

请求字段：

字段	类型	必填	说明
`digitalEmployeeName`	str	✅	数字员工名称

响应字段：

字段	类型	说明
`tasks`	list[ScheduledTaskTimeline]	所有定时任务的时间线

bash

curl -X POST "https://<gateway-domain>/openapi/getScheduledTaskExecutionRecords" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"digitalEmployeeName":"销售助手"}'

getScheduledTaskPushOptions · 获取定时任务推送配置选项

查询当前用户可用于定时任务推送的渠道与推送方式。

POST /openapi/getScheduledTaskPushOptions

请求字段：

字段	类型	必填	说明
`digitalEmployeeName`	str	✅	数字员工名称

响应字段：

字段	类型	说明
`channels`	array<ScheduledTaskPushChannelOption>	推送渠道列表
`emptyHint`	str	无已绑定三方账号时的提示

channels[]（ScheduledTaskPushChannelOption）结构：

字段	类型	说明
`channelType`	str	渠道枚举值
`channelName`	str	渠道展示名
`methods`	array<ScheduledTaskPushMethodOption>	推送方式列表

methods[]（ScheduledTaskPushMethodOption）结构：

字段	类型	说明
`method`	str	推送方式：channel_bot/direct
`name`	str	推送方式展示名
`enabled`	boolean	是否可选
`disabledReason`	str	置灰原因

bash

curl -X POST "https://<gateway-domain>/openapi/getScheduledTaskPushOptions" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"digitalEmployeeName":"销售助手"}'

getScheduledTaskUnderstandDetail · 获取定时任务理解详情

通过 LLM 理解用户自然语言输入，提取语义实体、相关对象和相关技能。

POST /openapi/getScheduledTaskUnderstandDetail

请求字段：

字段	类型	必填	说明
`userInput`	str	✅	自然语言任务描述
`digitalEmployeeName`	str	❌	数字员工名称，用于过滤可用技能
`segments`	list[SegmentItem]	❌	富文本消息片段，支持 @对象（type=mention）和 /技能（type=skill）

响应字段：

字段	类型	说明
`taskUnderstand`	str	润色后的任务理解
`relatedSemantics`	list[SemanticEntityOpen]	相关语义实体列表
`relatedObjects`	list[RelatedObjectOpen]	相关对象列表
`relatedSkills`	list[RelatedSkillOpen]	相关技能列表

bash

curl -X POST "https://<gateway-domain>/openapi/getScheduledTaskUnderstandDetail" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"userInput":"每天早上汇总昨日销售数据"}'

主对象数据

queryPrimaryObjectData · 分页查询主对象数据

OpenAPI 分页查询主对象数据。

POST /openapi/queryPrimaryObjectData

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	运营对象名称（如 customer_1）
`page`	int	❌	页码（默认 1）
`pageSize`	int	❌	每页数量，1-100（默认 20）
`keyword`	str	❌	关键字搜索（匹配 name；schema 定义 description 时同时匹配）
`onlyFavorites`	bool	❌	仅返回关注的主对象（默认 false）

响应字段：

字段	类型	说明
`total`	int	总数
`page`	int	当前页码
`pageSize`	int	每页数量
`items`	list[dict[str, Any]]	主对象数据列表（字段因 schema 定义而异）

bash

curl -X POST "https://<gateway-domain>/openapi/queryPrimaryObjectData" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"customer_1","page":1,"pageSize":20}'

togglePrimaryObjectFavorite · 关注/取消关注主对象

批量关注或取消关注主对象。

POST /openapi/togglePrimaryObjectFavorite

请求字段：

字段	类型	必填	说明
`objectType`	str	✅	对象类型（如 customer、project）
`operatingObjectName`	str	✅	运营对象名称（如 customer_1）
`objectIds`	list[str]	✅	主对象业务ID列表
`action`	Literal["add","remove"]	✅	操作：add-关注，remove-取消关注

响应字段：

字段	类型	说明
`results`	list[TogglePrimaryObjectFavoriteResult]	每条对象的处理结果
`favoriteCount`	int	该用户的关注总数（针对该对象类型）

bash

curl -X POST "https://<gateway-domain>/openapi/togglePrimaryObjectFavorite" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"objectType":"customer","operatingObjectName":"customer_1","objectIds":["C-001"],"action":"add"}'

replaceObjectBindings · 全量替换数据源对象绑定

全量替换数据源的对象绑定（先删后插，同一事务）。

POST /openapi/replaceObjectBindings

请求字段：

字段	类型	必填	说明
`sourceId`	str	✅	数据源 ID（租户内唯一）
`objectBindings`	list[ObjectBindingItem]	✅	新的对象绑定列表（全量替换；传空表示清空所有绑定）

响应字段：

字段	类型	说明
`sourceId`	str	数据源 ID
`objectBindings`	list[ObjectBindingItem]	替换后的对象绑定列表

bash

curl -X POST "https://<gateway-domain>/openapi/replaceObjectBindings" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"src_1234567890","objectBindings":[]}'

用户、Credit 与账单

getUserInfo · 获取当前用户信息

OpenAPI 获取当前用户信息。

GET /openapi/getUserInfo

请求：无请求体参数。

响应字段：

字段	类型	说明
`userId`	int	用户 ID
`userCode`	str	用户代码
`isAdmin`	bool	是否为超级管理员
`tenantId`	int	当前租户 ID
`tenantName`	str	当前租户名称
`tenantType`	TenantType	当前租户类型
`crmType`	str	当前租户 CRM 类型
`tenantList`	list[TenantInfo]	用户所属租户列表
`name`	str	用户名称
`avatar`	str	用户头像 URL
`languagePreference`	str	用户语言偏好
`profileRole`	str	用户角色
`profileRoleInfo`	str	用户角色描述（profileRole 为 Others 时）
`offering`	str	用户服务描述
`parsedOffering`	str	用户服务解析结果（JSON）
`selfIntroduction`	str	用户自我介绍
`isSystemTenant`	bool	当前登录租户是否为系统租户（tenantId=10000）

bash

curl -X GET "https://<gateway-domain>/openapi/getUserInfo" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json"

updateUserInfo · 更新当前用户信息

更新当前登录用户的基本信息。

POST /openapi/updateUserInfo

请求字段：

字段	类型	必填	说明
`name`	str	❌	用户名称
`avatar`	str	❌	用户头像 URL
`languagePreference`	str	❌	语言偏好：zh-CN, en-US
`profileRoleInfo`	str	❌	用户角色描述（profileRole 为 Others 时使用），最多100字符
`offering`	str	❌	用户服务描述，最多1000字符
`selfIntroduction`	str	❌	用户自我介绍，最多1000字符

响应字段：

字段	类型	说明
`success`	bool	是否更新成功
`message`	str	结果描述
`user`	UserInfo	更新后的用户信息

bash

curl -X POST "https://<gateway-domain>/openapi/updateUserInfo" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"name":"张三","languagePreference":"zh-CN"}'

getUserCreditUsage · 查询用户已消耗 Credit

OpenAPI 查询用户已消耗 credit（实时）。

POST /openapi/getUserCreditUsage

请求：无请求体参数。

响应字段：

字段	类型	说明
`tenantId`	int	租户 ID
`userId`	int	用户 ID
`creditLimit`	Decimal	用户 credit 限额
`usedCredits`	Decimal	已消耗 credit（实时）
`remainingCredits`	Decimal	剩余 credit（实时）
`shadowCreditLimit`	Decimal	影子 credit 限额
`shadowUsedCredits`	Decimal	已消耗影子 credit（实时）
`shadowRemainingCredits`	Decimal	剩余影子 credit（实时）

bash

curl -X POST "https://<gateway-domain>/openapi/getUserCreditUsage" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{}'

listBilling · 查询账单列表

OpenAPI 查询账单列表。

POST /openapi/listBilling

请求字段：

字段	类型	必填	说明
`userId`	int	❌	用户 ID（可选筛选）
`operation`	str	❌	操作类型（可选筛选）
`status`	str	❌	状态（可选筛选）
`startTime`	datetime	❌	开始时间范围
`endTime`	datetime	❌	结束时间范围
`bizType`	str	❌	业务来源类型（可选筛选）
`bizId`	str	❌	业务来源 ID（可选筛选）
`ignoreZero`	bool	❌	是否过滤 credit 消耗为 0 的账单（默认 true）
`page`	int	❌	页码（默认 1）
`pageSize`	int	❌	每页条数（默认 20）

响应字段：

字段	类型	说明
`list`	list[BillingItemResponse]	账单列表
`total`	int	总数
`page`	int	页码
`pageSize`	int	每页条数

bash

curl -X POST "https://<gateway-domain>/openapi/listBilling" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"pageSize":20,"ignoreZero":true}'

用户与权限管理

createUser · 创建用户并加入租户

智能创建 WINNEXO 自建账号用户并加入当前租户（账号已存在则直接加入）。

POST /openapi/createUser

请求字段：

字段	类型	必填	说明
`accountId`	str	✅	WINNEXO 登录账号（唯一标识）
`displayName`	str	✅	用户显示名称（租户内唯一）
`roleCodes`	array<str>	❌	系统角色：SUPER_ADMIN / SYSTEM_ADMIN / SEMANTIC_ADMIN / SKILL_ADMIN / KB_ADMIN / AGENT_ADMIN / APPLICATION_USER（默认 APPLICATION_USER）
`passwordEncrypted`	str	❌	RSA-OAEP-SHA256 加密后的 base64 密文；不传用系统默认密码

响应字段：

字段	类型	说明
`userId`	int	平台用户ID
`accountId`	str	WINNEXO 登录账号
`displayName`	str	用户显示名称
`isNewUser`	boolean	是否为新创建用户
`isDefaultPassword`	boolean	是否使用系统默认密码（true 时建议通知用户修改）

bash

curl -X POST "https://<gateway-domain>/openapi/createUser" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"accountId":"zhangsan","displayName":"张三","roleCodes":["APPLICATION_USER"]}'

updateUser · 修改用户信息（含启停用）

修改用户显示名、角色、启停用状态、用户组。除 userId 外均可选（不传不改，至少改一个）；roleCodes/userGroupIds 为全量替换。

POST /openapi/updateUser

请求字段：

字段	类型	必填	说明
`userId`	int	✅	目标用户ID
`displayName`	str	❌	新显示名称（传则不可为空）
`roleCodes`	array<str>	❌	新角色列表（全量替换，至少一个）
`isActive`	boolean	❌	启用/停用（false=停用，true=启用）
`userGroupIds`	array<str>	❌	新用户组ID列表（全量替换）

响应字段：userId(int, 被修改的用户ID)。HTTP 200 即表示成功。

bash

curl -X POST "https://<gateway-domain>/openapi/updateUser" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"userId":1001,"displayName":"张三丰","isActive":true}'

getUser · 查询用户详情

查询用户详情，userId / accountId 任传一个（都传以 userId 为准）。

POST /openapi/getUser

请求字段：

字段	类型	必填	说明
`userId`	int	❌	用户ID（与 accountId 二选一）
`accountId`	str	❌	WINNEXO 登录账号（与 userId 二选一）

响应字段：

字段	类型	说明
`userId`	int	用户ID
`accountId`	str	WINNEXO 登录账号
`displayName`	str	用户显示名称
`isActive`	boolean	启用/停用状态
`roleCodes`	array<str>	系统角色 code 列表
`userGroupIds`	array<str>	所属用户组ID列表
`gmtCreate`	str	加入租户时间
`lastLoginTime`	str	最后登录时间

bash

curl -X POST "https://<gateway-domain>/openapi/getUser" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"userId":1001}'

listUsers · 分页查询租户成员列表

分页查询租户成员列表，支持状态、角色、关键词筛选。

POST /openapi/listUsers

请求字段：

字段	类型	必填	说明
`page`	int	❌	页码（默认 1）
`pageSize`	int	❌	每页数量（最大 100，默认 20）
`keyword`	str	❌	搜索关键词（模糊匹配显示名和账号）
`isActive`	boolean	❌	启用/停用状态筛选
`roleCodes`	array<str>	❌	按角色筛选

响应字段：total(int) / page(int) / pageSize(int) / items(array<ListUsersItemResponse>)。

items[]：userId / accountId / displayName / isActive / roleCodes / gmtCreate / lastLoginTime。

bash

curl -X POST "https://<gateway-domain>/openapi/listUsers" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"pageSize":20,"keyword":"张"}'

removeUser · 从租户移除用户

从当前租户移除用户（保留用户主体），同时移除其角色/用户组关联与数字员工授权，含最后超管保护。

POST /openapi/removeUser

请求字段：

字段	类型	必填	说明
`userId`	int	✅	要移除的用户ID

响应字段：userId(int, 被移除的用户ID)。HTTP 200 即表示成功。

bash

curl -X POST "https://<gateway-domain>/openapi/removeUser" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"userId":1001}'

resetPassword · 重置用户密码

管理员重置用户密码；不传 passwordEncrypted 则重置为系统默认密码。仅支持 WINNEXO 自建账号。

POST /openapi/resetPassword

请求字段：

字段	类型	必填	说明
`userId`	int	✅	目标用户ID
`passwordEncrypted`	str	❌	RSA-OAEP-SHA256 加密后的新密码 base64 密文；不传重置为默认密码

响应字段：userId(int) / isDefaultPassword(boolean, 是否重置为系统默认密码)。

bash

curl -X POST "https://<gateway-domain>/openapi/resetPassword" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"userId":1001}'

getTokenInfo · 查询用户的 Token 状态

查询用户的 INSTANCE Token 状态（仅个人 Token 可调）。userId 为空时查自身；超管/系管可代查同租户用户。

POST /openapi/getTokenInfo

请求字段（可选）：

字段	类型	必填	说明
`userId`	int	❌	目标用户 ID（空则自身，管理员可代操作）

响应字段：

字段	类型	说明
`enabled`	boolean	Token 是否开启（存在 ACTIVE 状态）
`tokenMasked`	str	脱敏后的 Token 值
`gmtCreate`	str	Token 创建时间（ISO 8601）

bash

curl -X POST "https://<gateway-domain>/openapi/getTokenInfo" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{}'

enableToken · 开启 API Token

开启用户的 INSTANCE Token（幂等）。明文仅首次开启时返回一次。仅个人 Token 可调。

POST /openapi/enableToken

请求字段（可选）：userId(int, 空则自身，管理员可代操作)。

响应字段：

字段	类型	说明
`token`	str	Token 明文（仅本次返回，请妥善保管）
`tokenMasked`	str	脱敏后的 Token 值

bash

curl -X POST "https://<gateway-domain>/openapi/enableToken" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{}'

disableToken · 关闭 API Token

关闭用户的 INSTANCE Token（ACTIVE → INACTIVE，幂等）。仅个人 Token 可调。

POST /openapi/disableToken

请求字段（可选）：userId(int, 空则自身)。

响应字段：disabled(boolean, 操作是否成功)。

bash

curl -X POST "https://<gateway-domain>/openapi/disableToken" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{}'

resetToken · 重置 API Token

重置用户的 INSTANCE Token：旧 ACTIVE Token 永久失效（RESET），生成新 ACTIVE Token。仅个人 Token 可调。

POST /openapi/resetToken

请求字段（可选）：userId(int, 空则自身)。

响应字段：

字段	类型	说明
`token`	str	新 Token 明文（仅本次返回）
`tokenMasked`	str	脱敏后的新 Token 值

bash

curl -X POST "https://<gateway-domain>/openapi/resetToken" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{}'

grantAgentUsers · 授权用户/用户组使用数字员工

授权用户或用户组使用指定数字员工（已存在则更新）。需 MANAGE 权限。userIds 与 userGroupIds 二选一。

POST /openapi/grantAgentUsers

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称
`userIds`	array<int>	❌	被授权用户 ID 列表（与 userGroupIds 二选一）
`userGroupIds`	array<str>	❌	被授权用户组 ID 列表（16 位 hex）
`expireDate`	int	❌	授权截止时间戳（毫秒），不传永不过期
`permissions`	array<str>	❌	权限：USE 和/或 MANAGE（默认仅 USE）

响应字段：grantedCount(int, 本次处理的授权记录数)。

bash

curl -X POST "https://<gateway-domain>/openapi/grantAgentUsers" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"销售助手","userIds":[1001,1002],"permissions":["USE"]}'

revokeAgentUsers · 撤销用户/用户组的数字员工使用权限

撤销用户或用户组对指定数字员工的使用权限。需 MANAGE 权限。userIds 与 userGroupIds 二选一。

POST /openapi/revokeAgentUsers

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称
`userIds`	array<int>	❌	被撤销用户 ID 列表（与 userGroupIds 二选一）
`userGroupIds`	array<str>	❌	被撤销用户组 ID 列表

响应字段：revokedCount(int, 本次成功撤销的记录数)。

bash

curl -X POST "https://<gateway-domain>/openapi/revokeAgentUsers" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"销售助手","userIds":[1001,1002]}'

listAuthorizedAgents · 查询调用方有指定权限的数字员工名称列表

查询当前调用方拥有指定权限（USE/MANAGE）的数字员工名称列表。请求体可选，默认按 USE。

POST /openapi/listAuthorizedAgents

请求字段（可选）：permission(str, USE / MANAGE，默认 USE)。

响应字段：agentNames(array<str>, 有指定权限的数字员工名称列表)。

bash

curl -X POST "https://<gateway-domain>/openapi/listAuthorizedAgents" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"permission":"USE"}'

listAuthorizedUsers · 查询数字员工已授权的用户/用户组列表

查询某数字员工已授权的用户/用户组列表（需 APPLICATION_AGENT_VIEW）。

POST /openapi/listAuthorizedUsers

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称
`keyword`	str	❌	搜索关键词（按用户名或组名模糊匹配）
`granteeType`	str	❌	筛选：USER / USER_GROUP / 不传全部
`permission`	str	❌	权限过滤：USE / MANAGE

响应字段：authMode(str, SPECIFIED_USERS / ALL_USERS) / total(int) / items(array<AuthorizedUserItem>)。

items[]（AuthorizedUserItem）：id / granteeId / granteeType(USER/USER_GROUP) / userId / userGroupId / userName / userGroupName / memberCount / permissions / expireDate / grantedBy / gmtCreate / gmtModified。

bash

curl -X POST "https://<gateway-domain>/openapi/listAuthorizedUsers" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"销售助手","granteeType":"USER"}'

updateAgentAuthMode · 更新数字员工使用权限授权模式

切换数字员工的使用权限授权模式。需 MANAGE 权限。

POST /openapi/updateAgentAuthMode

请求字段：

字段	类型	必填	说明
`operatingObjectName`	str	✅	数字员工名称
`authMode`	str	✅	SPECIFIED_USERS=指定用户（需显式授权），ALL_USERS=所有用户（无需授权）

响应字段：updated(boolean, 是否更新成功)。

bash

curl -X POST "https://<gateway-domain>/openapi/updateAgentAuthMode" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"operatingObjectName":"销售助手","authMode":"ALL_USERS"}'

组织同步

createCustomOrg · 注册纯自定义组织

注册一个纯自定义组织，用于后续通过 syncOrgStructure 推送部门树（仅支持部门树同步，不支持成员关系同步）。

POST /openapi/createCustomOrg

请求字段：

字段	类型	必填	说明
`corpId`	str	✅	自定义组织标识，格式 `^[a-z0-9][a-z0-9\-]{2,63}$`（3-64 位）
`corpName`	str	❌	组织展示名称（不传与 corpId 相同，最长 128）

响应字段：

字段	类型	说明
`corpId`	str	注册成功的组织标识
`corpName`	str	组织展示名称
`platformType`	str	平台类型，固定为 custom

bash

curl -X POST "https://<gateway-domain>/openapi/createCustomOrg" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"corpId":"acme-corp","corpName":"Acme 公司"}'

syncOrgStructure · 推送组织架构同步

接收客户端推送的部门树和成员关系，创建异步同步任务，返回 taskId 供 querySyncResult 轮询。单次推送 departments + members 总量上限 50000。

POST /openapi/syncOrgStructure

请求字段：

字段	类型	必填	说明
`platformType`	str	✅	平台类型：saml / oauth2 / custom
`corpId`	str	✅	企业标识（需与 listAvailableConfigs 返回一致）
`ssoSettingsId`	str	❌	SSO 配置 ID（多个 IdP 共用 corpId 时必传；custom 不需）
`syncMembers`	boolean	❌	是否同步成员关系（默认 false；custom 强制 false）
`departments`	array<PushDepartmentItem>	✅	部门列表（至少一个根部门）
`members`	array<PushMemberItem>	❌	成员列表（syncMembers=true 时必须提供）

departments[]（PushDepartmentItem）：deptId(✅) / deptName(✅,最长128) / parentDeptId(null 为根部门) / order(默认0)。
members[]（PushMemberItem）：deptId(✅) / accountId(✅,需与 rbj_user_account.account_id 匹配) / name(可选)。

响应字段：

字段	类型	说明
`taskId`	number	异步同步任务 ID，用于 querySyncResult 轮询
`status`	str	任务初始状态（PENDING）

bash

curl -X POST "https://<gateway-domain>/openapi/syncOrgStructure" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"platformType":"custom","corpId":"acme-corp","syncMembers":false,"departments":[{"deptId":"d1","deptName":"总部","parentDeptId":null,"order":0}]}'

querySyncResult · 查询组织同步结果

根据 taskId 查询组织同步任务的执行状态和结果（状态：PENDING → RUNNING → COMPLETED / FAILED / TIMEOUT / CANCELED，建议轮询 3-5 秒）。

POST /openapi/querySyncResult

请求字段：

字段	类型	必填	说明
`taskId`	number	✅	同步任务 ID（由 syncOrgStructure 返回）

响应字段：

字段	类型	说明
`taskId`	number	任务 ID
`status`	str	任务状态（PENDING / RUNNING / COMPLETED / FAILED / TIMEOUT / CANCELED）
`platformType`	str	平台类型
`corpId`	str	企业标识
`submittedAt`	str	任务提交时间（ISO 8601）
`startedAt`	str	任务开始执行时间
`completedAt`	str	任务完成时间
`durationSeconds`	number	执行时长（秒）
`summary`	str	执行摘要（人可读）
`errorMessage`	str	错误信息（失败时有值）
`deptStats`	DeptStatsResponse	部门同步统计（完成时有值）
`memberStats`	MemberStatsResponse	成员同步统计（syncMembers=true 且完成时有值）

deptStats：totalExternal / created / renamed / moved / deleted / skipped（均 number）。
memberStats：totalExternal / relationshipAdded / relationshipRemoved / unchanged / failed（均 number）。

bash

curl -X POST "https://<gateway-domain>/openapi/querySyncResult" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{"taskId":123456}'

listAvailableConfigs · 枚举可用的组织同步配置

枚举当前租户下所有可用的组织同步配置，涵盖 wecom / saml / oauth2 / custom 四种平台类型。

POST /openapi/listAvailableConfigs

请求：无请求体参数。

响应字段：

字段	类型	说明
`configs`	array<OrgSyncConfigItem>	可用的组织同步配置列表

configs[]（OrgSyncConfigItem）：

字段	类型	说明
`platformType`	str	平台类型：wecom / saml / oauth2 / custom
`corpId`	str	企业标识（wecom=corpId, saml=idpEntityId, oauth2=clientId, custom=客户自定义）
`corpName`	str	企业展示名称
`ssoSettingsId`	str	SSO 配置 ID（custom 为 null）
`ssoSettingsName`	str	SSO 配置名称（custom 为 null）

bash

curl -X POST "https://<gateway-domain>/openapi/listAvailableConfigs" \
  -H "Authorization: Bearer <AccessToken>" \
  -H "Content-Type: application/json" \
  -d '{}'

最佳实践

✓

「调技能优先于调会话」——快捷技能是已经被你或管理员配好的“成品能力”，参数稳定、结果可预期。直接调会话相当于让对方现场和数字员工聊一通，结果飘。

✓

「先用 CLI 调通，再改成代码」——所有 OpenAPI 能力 CLI 都封装好了，先在终端验证参数和返回结构，再翻成代码。

「Token 不要写死在代码里」——读环境变量，部署时通过 secret manager 注入。

📌 配套阅读：CLI、编写自定义技能包、能力中心

发起对话

执行与控制

上下文管理

结果处理

技能

应用连接

账户信息

个人记忆

偏好设置

用量与计费

应用连接

任务并发

分享管理

开放集成

创建本体

本体模型

业务逻辑

分析视图

数据映射

校验与发布

企业技能

应用连接

用户

权限

IM 系统

用量

数据来源

数据源管理

数据采集器

通用

公告中心

智能排查

全量记录查看

OpenAPI ​

工作原理 ​

鉴权与通用规范 ​

网关地址 ​

AccessToken 类型 ​

租户 ID 确认 ​

请求规范 ​

响应规范 ​

多语言调用示例 ​

常见错误码 ​

注意事项 ​

接口总览 ​

系统与实例（2 个） ​

会话（7 个） ​

快捷技能（4 个） ​

我的资源（19 个） ​

企业知识库（16 个） ​

定时任务（8 个） ​

主对象数据（3 个） ​

用户、Credit 与账单（4 个） ​

用户与权限管理（15 个） ​

组织同步（4 个） ​

系统与实例 ​

checkHealth · 健康检查与鉴权探测 ​

getInstanceExpireTime · 查询租户标准包实例过期时间 ​

会话 ​

sendChatMessage · 发送会话消息 ​

getChatSession · 获取单个会话详情 ​

listChatSessions · 获取会话列表 ​

updateChatSession · 更新会话信息 ​

stopChatSession · 停止会话生成 ​

deleteChatSession · 删除会话 ​

uploadChatFile · 会话文件上传 ​

快捷技能 ​

listSkills · 查询技能列表 ​

getSkill · 获取技能详情 ​

runSkill · 异步执行技能 ​

getSkillRun · 查询技能异步执行结果 ​

我的资源 ​

createPersonalFile · 上传文件到我的资源 ​

createPersonalText · 上传纯文本到我的资源 ​

createPersonalVoiceMeeting · 上传离线会议到我的资源 ​

createPersonalDingtalkMeeting · 上传钉钉会议到我的资源 ​

createPersonalAliDingMeeting · 上传阿里钉会议到我的资源 ​

createPersonalAliDingDoc · 上传阿里钉在线文档到我的资源 ​

createPersonalAliDingKnowledgeBase · 创建阿里钉整体知识库到我的资源 ​

createPersonalFeishuMinute · 上传飞书妙记会议到我的资源 ​

OpenAPI

工作原理

鉴权与通用规范

网关地址

AccessToken 类型

租户 ID 确认

请求规范

响应规范

多语言调用示例

常见错误码

注意事项

接口总览

系统与实例（2 个）

会话（7 个）

快捷技能（4 个）

我的资源（19 个）

企业知识库（16 个）

定时任务（8 个）

主对象数据（3 个）

用户、Credit 与账单（4 个）

用户与权限管理（15 个）

组织同步（4 个）

系统与实例

checkHealth · 健康检查与鉴权探测

getInstanceExpireTime · 查询租户标准包实例过期时间

会话

sendChatMessage · 发送会话消息

getChatSession · 获取单个会话详情

listChatSessions · 获取会话列表

updateChatSession · 更新会话信息

stopChatSession · 停止会话生成

deleteChatSession · 删除会话

uploadChatFile · 会话文件上传

快捷技能

listSkills · 查询技能列表

getSkill · 获取技能详情

runSkill · 异步执行技能

getSkillRun · 查询技能异步执行结果

我的资源

createPersonalFile · 上传文件到我的资源

createPersonalText · 上传纯文本到我的资源

createPersonalVoiceMeeting · 上传离线会议到我的资源

createPersonalDingtalkMeeting · 上传钉钉会议到我的资源

createPersonalAliDingMeeting · 上传阿里钉会议到我的资源

createPersonalAliDingDoc · 上传阿里钉在线文档到我的资源

createPersonalAliDingKnowledgeBase · 创建阿里钉整体知识库到我的资源

createPersonalFeishuMinute · 上传飞书妙记会议到我的资源

createPersonalDirectory · 在我的资源下创建个人目录

listPersonalDirectoryContents · 下钻查询我的资源目录内容

getSource · 获取数据源详情

getSourceUploadSignature · 获取数据源文件 OSS 直传签名 URL

moveResource · 在个人目录间移动资源

renameSource · 重命名数据源

updateDirectory · 更新个人目录

retryDirectoryFailedSources · 重试个人目录下失败数据源

previewPersonalSource · 预览个人知识库知识

listOutputFiles · 查询当前用户产出列表

saveOutputFileToResource · 将产出批量保存为个人资源

企业知识库

listVisibleKnowledgeBases · 查询数字员工可见知识库列表

listVisibleKnowledgeBaseContents · 下钻查询可见知识库目录内容

listAdminKnowledgeBases · 后台查询/下钻企业知识库

submitSourceToKnowledgeBase · 将个人资源提交到企业知识库

createKnowledgeBaseFile · 上传文件到企业知识库

createKnowledgeBaseText · 上传纯文本到企业知识库

createKnowledgeBaseAliDingDoc · 上传阿里钉在线文档到企业知识库

createKnowledgeBaseDirectory · 创建企业知识库分类

getKnowledgeBaseSource · 获取企业知识库知识详情

listKnowledgeBaseDirectories · 获取企业知识库分类列表

updateKnowledgeBaseDirectory · 修改企业知识库分类

moveKnowledgeBaseResource · 在企业知识库目录间移动资源

renameKnowledgeBaseSource · 重命名企业知识库数据源

updateKnowledgeBaseSourceTags · 更新企业知识库数据源标签

retryKnowledgeBaseFailedSources · 重试企业知识库目录下失败数据源

previewKnowledgeBaseSource · 预览企业知识库知识

定时任务

createScheduledTask · 创建定时任务

updateScheduledTask · 更新定时任务

listScheduledTasks · 获取定时任务列表

executeScheduledTask · 立即执行定时任务