OpenAPI

OpenAPI turns WinNexo's frontend capabilities into an "AI capability plugin" for your existing systems. This complete API reference explains authentication and general conventions, then provides overview tables and each endpoint's path, request parameters, response parameters, and examples, organized by capability area.

See the Public Cloud OpenAPI documentation.

How It Works

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

Every call requires an identity credential (Authorization: Bearer <AccessToken>). See the "Authentication" section below for credential types.

Authentication & General Conventions

Gateway Address

• All endpoints share a common prefix: /openapi
• Full URL format: https://<gateway-domain>/openapi/<接口路径>
• <gateway-domain> is the gateway domain of your deployment. Contact your administrator to obtain it.

AccessToken Types

All endpoints authenticate via the Authorization: Bearer <AccessToken> header, handled uniformly by require_openapi_identity. Three token types are supported:

Token Type	Prefix	Description	Use Case
User API Token	wn_	Personal identity credential representing a specific user	Personal scripts, IDE plugins, CLI login
Deployment Token	wn_dpl_	Deployment-level credential, requires tenant/user info	Server-side integration, backend batch processing
Encrypted Token	@ENCRYPT__	Credential delivered as encrypted string	Specific hosted/encrypted delivery scenarios

To obtain and manage a user API Token, see UserToken in Personal Settings.

Tenant ID

• Single-tenant users: Tenant is inferred automatically; no explicit input needed.
• Multi-tenant users: Must explicitly specify the tenant using one of:
  • Query parameter: tenantId or tenant_id
  • Request header: X-Tenant-Id
• Returns ERR.Auth.TenantIdRequired if unspecified and cannot be inferred.

Request Conventions

• HTTP Methods: Write operations default to POST; read-only queries may use GET (some deletions use DELETE). Refer to each endpoint's "Endpoint Info" section.
• Required Headers:
  • Authorization: Bearer <AccessToken>
  • Content-Type: application/json
• Optional Headers:
  • X-Tenant-Id: Specify tenant for multi-tenant scenarios
  • X-Timezone: Specify timezone (e.g., Asia/Shanghai), affects time-related fields
• Field Naming: Request/response fields use camelCase uniformly.
• Prohibited Fields: Do not include tenantId / tenant_id or userId / user_id in request bodies — these are derived automatically by the auth chain. Explicit values will be ignored or cause errors.

Response Conventions

All endpoints return a POP gateway-compatible format: top-level fixed fields Code / Message / RequestId, with business fields expanded flat (no nested data wrapper).

Success Response:

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

Error Response:

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

Multi-Language Call Examples

Using createPersonalFile as an example to demonstrate calling conventions in various languages. For other endpoints, simply replace the path and request body.

cURL:

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):

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):

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):

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());

Common Error Codes

Error Code	Meaning	Suggested Action
ERR.Auth.UnsupportedAuthType	Unsupported auth type	Check token prefix and Authorization header format
ERR.Auth.TenantIdRequired	Tenant not specified and cannot be inferred	Pass tenantId or X-Tenant-Id for multi-tenant scenarios
ERR.Auth.TenantAccessDenied	No access to the specified tenant	Confirm the current user belongs to the target tenant
ERR.User.NotFound	User not found	Check if the user identifier is correct
ERR.Resource.NotFound	Resource not found	Check if the resource ID is correct or if it has been deleted
ERR.Robject.UserDirectory.NotAuthorized	No directory access permission	Confirm the Digital Worker has visibility/operation permission on the target directory
ERR.System.Error	Internal system error	Contact administrator with RequestId for investigation

Notes

• Idempotent calls: Write endpoints accept a clientToken (caller-generated) for idempotency identification.
• Digital Worker context: Most resource/knowledge/object endpoints require operatingObjectName (Digital Worker name, i.e., operating object name) to determine the operation context and permission scope.
• Large file uploads: Large files use OSS direct upload — first call getSourceUploadSignature to get a signed URL, upload directly, then register the resource. Small files in chat can use uploadChatFile for backend direct upload.
• Async task polling: runSkill returns a runId; poll execution status and results via getSkillRun.
• Version compatibility: New capabilities are backward-compatible; call paths remain unchanged, and historical endpoints continue to work.

Endpoint Overview

A total of 82 endpoints, organized by capability domain.

System & Instance (2)

Endpoint	Method	Path	Description
checkHealth	GET	/openapi/checkHealth	Health check and auth probe
getInstanceExpireTime	GET	/openapi/getInstanceExpireTime	Get instance expiration time

Chat (7)

Endpoint	Method	Path	Description
sendChatMessage	POST	/openapi/v1/chatMessages	Send a chat message
getChatSession	GET	/openapi/v1/chatSession	Get chat session details
listChatSessions	GET	/openapi/v1/chatSession/list	List chat sessions
updateChatSession	POST	/openapi/v1/chatSession/update	Update chat session info
stopChatSession	POST	/openapi/v1/chatSession/stop	Stop chat generation
deleteChatSession	DELETE	/openapi/v1/chatSession/delete	Delete a chat session
uploadChatFile	POST	/openapi/v1/uploadChatFile	Upload a chat file

Quick Skills (4)

Endpoint	Method	Path	Description
listSkills	POST	/openapi/listSkills	List skills
getSkill	POST	/openapi/getSkill	Get skill details
runSkill	POST	/openapi/runSkill	Run a skill asynchronously
getSkillRun	POST	/openapi/getSkillRun	Get async skill run result

My Resources (19)

Endpoint	Method	Path	Description
createPersonalFile	POST	/openapi/createPersonalFile	Create a personal file resource
createPersonalText	POST	/openapi/createPersonalText	Create a personal text note
createPersonalVoiceMeeting	POST	/openapi/createPersonalVoiceMeeting	Create a personal voice meeting record
createPersonalDingtalkMeeting	POST	/openapi/createPersonalDingtalkMeeting	Create a personal DingTalk meeting record
createPersonalAliDingMeeting	POST	/openapi/createPersonalAliDingMeeting	Create a personal AliDing meeting record
createPersonalAliDingDoc	POST	/openapi/createPersonalAliDingDoc	Create a personal AliDing document resource
createPersonalAliDingKnowledgeBase	POST	/openapi/createPersonalAliDingKnowledgeBase	Create a personal AliDing knowledge base resource
createPersonalFeishuMinute	POST	/openapi/createPersonalFeishuMinute	Create a personal Feishu Minutes resource
createPersonalDirectory	POST	/openapi/createPersonalDirectory	Create a personal resource directory
listPersonalDirectoryContents	POST	/openapi/listPersonalDirectoryContents	Drill down into personal resource directory contents
getSource	POST	/openapi/getSource	Get resource details
getSourceUploadSignature	POST	/openapi/getSourceUploadSignature	Get resource upload signature
moveResource	POST	/openapi/moveResource	Move a personal resource
renameSource	POST	/openapi/renameSource	Rename a personal resource
updateDirectory	POST	/openapi/updateDirectory	Update a personal resource directory
retryDirectoryFailedSources	POST	/openapi/retryDirectoryFailedSources	Retry failed resources in a directory
previewPersonalSource	POST	/openapi/previewPersonalSource	Preview a personal resource
listOutputFiles	POST	/openapi/listOutputFiles	List current user's outputs
saveOutputFileToResource	POST	/openapi/saveOutputFileToResource	Batch save outputs as personal resources

Knowledge Base (16)

Endpoint	Method	Path	Description
listVisibleKnowledgeBases	POST	/openapi/listVisibleKnowledgeBases	List knowledge bases visible to a Digital Worker
listVisibleKnowledgeBaseContents	POST	/openapi/listVisibleKnowledgeBaseContents	Drill down into visible knowledge base directory contents
listAdminKnowledgeBases	POST	/openapi/listAdminKnowledgeBases	Admin list/drill-down knowledge bases
submitSourceToKnowledgeBase	POST	/openapi/submitSourceToKnowledgeBase	Submit personal resource to knowledge base
createKnowledgeBaseFile	POST	/openapi/createKnowledgeBaseFile	Create a knowledge base file resource
createKnowledgeBaseText	POST	/openapi/createKnowledgeBaseText	Create a knowledge base text resource
createKnowledgeBaseAliDingDoc	POST	/openapi/createKnowledgeBaseAliDingDoc	Create a knowledge base AliDing document resource
createKnowledgeBaseDirectory	POST	/openapi/createKnowledgeBaseDirectory	Create a knowledge base directory
getKnowledgeBaseSource	POST	/openapi/getKnowledgeBaseSource	Get knowledge base resource details
listKnowledgeBaseDirectories	POST	/openapi/listKnowledgeBaseDirectories	List knowledge base directories
updateKnowledgeBaseDirectory	POST	/openapi/updateKnowledgeBaseDirectory	Update a knowledge base directory
moveKnowledgeBaseResource	POST	/openapi/moveKnowledgeBaseResource	Move a knowledge base resource
renameKnowledgeBaseSource	POST	/openapi/renameKnowledgeBaseSource	Rename a knowledge base resource
updateKnowledgeBaseSourceTags	POST	/openapi/updateKnowledgeBaseSourceTags	Update knowledge base resource tags
retryKnowledgeBaseFailedSources	POST	/openapi/retryKnowledgeBaseFailedSources	Retry failed resources in knowledge base
previewKnowledgeBaseSource	POST	/openapi/previewKnowledgeBaseSource	Preview a knowledge base resource

Scheduled Tasks (8)

Endpoint	Method	Path	Description
createScheduledTask	POST	/openapi/createScheduledTask	Create a scheduled task
updateScheduledTask	POST	/openapi/updateScheduledTask	Update a scheduled task
listScheduledTasks	POST	/openapi/listScheduledTasks	List scheduled tasks
executeScheduledTask	POST	/openapi/executeScheduledTask	Execute a scheduled task immediately
getScheduledTaskExecutionDetail	POST	/openapi/getScheduledTaskExecutionDetail	Get scheduled task execution details
getScheduledTaskExecutionRecords	POST	/openapi/getScheduledTaskExecutionRecords	Get scheduled task execution records
getScheduledTaskPushOptions	POST	/openapi/getScheduledTaskPushOptions	Get scheduled task push options
getScheduledTaskUnderstandDetail	POST	/openapi/getScheduledTaskUnderstandDetail	Get scheduled task understanding details

Primary Object Data (3)

Endpoint	Method	Path	Description
queryPrimaryObjectData	POST	/openapi/queryPrimaryObjectData	Paginated query of primary object data
togglePrimaryObjectFavorite	POST	/openapi/togglePrimaryObjectFavorite	Follow/unfollow a primary object
replaceObjectBindings	POST	/openapi/replaceObjectBindings	Replace object bindings

User, Credit & Billing (4)

Endpoint	Method	Path	Description
getUserInfo	GET	/openapi/getUserInfo	Get current user info
updateUserInfo	POST	/openapi/updateUserInfo	Update current user info
getUserCreditUsage	POST	/openapi/getUserCreditUsage	Get user Credit usage
listBilling	POST	/openapi/listBilling	List billing records

User & Permission Management (15)

Endpoint	Method	Path	Description
createUser	POST	/openapi/createUser	Create a user
updateUser	POST	/openapi/updateUser	Update a user
getUser	POST	/openapi/getUser	Get user details
listUsers	POST	/openapi/listUsers	List users
removeUser	POST	/openapi/removeUser	Remove a user
resetPassword	POST	/openapi/resetPassword	Reset user password
getTokenInfo	POST	/openapi/getTokenInfo	Get Token info
enableToken	POST	/openapi/enableToken	Enable user Token
disableToken	POST	/openapi/disableToken	Disable user Token
resetToken	POST	/openapi/resetToken	Reset user Token
grantAgentUsers	POST	/openapi/grantAgentUsers	Grant Digital Worker user permissions
revokeAgentUsers	POST	/openapi/revokeAgentUsers	Revoke Digital Worker user permissions
listAuthorizedAgents	POST	/openapi/listAuthorizedAgents	List authorized Digital Workers
listAuthorizedUsers	POST	/openapi/listAuthorizedUsers	List authorized users
updateAgentAuthMode	POST	/openapi/updateAgentAuthMode	Update Digital Worker auth mode

Organization Sync (4)

Endpoint	Method	Path	Description
createCustomOrg	POST	/openapi/createCustomOrg	Create a custom organization
syncOrgStructure	POST	/openapi/syncOrgStructure	Sync organization structure
querySyncResult	POST	/openapi/querySyncResult	Query organization sync result
listAvailableConfigs	POST	/openapi/listAvailableConfigs	List available org sync configurations

System & Instance

checkHealth · Health Check & Auth Probe

OpenAPI entry health check. Can be used to verify whether authentication is working and inspect the current caller/tenant/Digital Worker in effect.

GET /openapi/checkHealth

Request: No request body parameters.

Response fields:

Field	Type	Description
callerType	str	Caller type: user / aliyun_main / aliyun_ram / service
authSource	str	Auth source: bearer / aliyun_gateway
userId	int	Platform user ID
tenantId	int	Active tenant ID
digitalEmployeeName	str	Digital Worker name in effect for the current request (operating object); empty if none specified and tenant has no Digital Workers

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

getInstanceExpireTime · Query Tenant Standard Package Instance Expiration

Query the tenant standard package instance expiration time via OpenAPI.

POST /openapi/getInstanceExpireTime

Request: No request body parameters.

Response fields:

Field	Type	Description
tenantId	int	System tenant ID
instanceId	str	Instance ID
instanceExpireTime	str	Instance expiration time (ISO format)
instanceStatus	str	Instance status
found	bool	Whether a standard package instance was found

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

Chat

sendChatMessage · Send a Chat Message

Send a message to a chat session. Creates a new session if no sessionId is provided.

POST /openapi/v1/chatMessages

Request fields:

Field	Type	Required	Description
content	str	✅	User message body
contentType	str	❌	Message type: Text / Markdown (default Text)
sessionId	str	❌	Session ID; creates a new session if omitted
digitalEmployeeName	str	❌	Digital Worker name
files	list[FileRef]	❌	File reference list
stream	bool	❌	Whether to stream response (default True)
reuseLastSession	bool	❌	When no sessionId is provided, whether to reuse the Digital Worker's most recent session (default False)

Response: Returns only the generic wrapper fields {"Code":"200","Message":"success","RequestId":"req-xxx"} (streaming content is delivered via the stream channel).

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

getChatSession · Get Chat Session Details

Get details of a single chat session via OpenAPI.

GET /openapi/v1/chatSession

Query parameters:

Parameter	Type	Required	Description
sessionId	string	❌	Session ID

Response fields:

Field	Type	Description
session	ConversationInfo	Session information
messages	list[ConversationMessageInfo]	Recent messages list

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

listChatSessions · List Chat Sessions

OpenAPI chat session list endpoint.

GET /openapi/v1/chatSession/list

Query parameters:

Parameter	Type	Required	Description
tenant_id	string	❌	Tenant ID
page_size	string	❌	Page size
page	string	❌	Page number
keyword	string	❌	Keyword
digital_employee_name	string	❌	Digital Worker name

Response fields:

Field	Type	Description
data	list[ConversationInfo]	Session list
total	int	Total count matching criteria
page	int	Current page number
pageSize	int	Page size
hasMore	bool	Whether more data is available

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 · Update Chat Session Info

Update chat session title and other information.

POST /openapi/v1/chatSession/update

Request fields:

Field	Type	Required	Description
sessionId	str	❌	Session ID
title	str	❌	New session title

Response fields:

Field	Type	Description
session	ConversationInfo	Updated session information

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

stopChatSession · Stop Chat Generation

Stop the reply currently being generated for a specified session.

POST /openapi/v1/chatSession/stop

Query parameters:

Parameter	Type	Required	Description
sessionId	string	❌	Session ID

Request fields:

Field	Type	Required	Description
Reason	str	❌	Stop reason (for auditing)

Response fields:

Field	Type	Description
sessionId	str	Session ID
messageId	str	ID of the stopped message
status	str	Final message status
finishReason	str	Finish reason
partialContent	str	Partially generated content

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

deleteChatSession · Delete a Chat Session

OpenAPI delete chat session endpoint.

DELETE /openapi/v1/chatSession/delete

Query parameters:

Parameter	Type	Required	Description
sessionId	string	❌	Session ID

Response fields:

Field	Type	Description
sessionId	str	Session ID
deleted	bool	Whether deletion was successful
hardDelete	bool	Whether it was a hard delete

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

uploadChatFile · Upload Chat File

Backend direct upload endpoint for chat scenario files.

POST /openapi/v1/uploadChatFile

Request: No request body parameters (file uploaded via multipart form).

Response fields:

Field	Type	Description
objectName	str	OSS object path
fileUrl	str	File remote_url (stored path)
filePublicUrl	str	File public access URL (valid for 1 hour)
uploadSignatureUrl	str	Signed upload URL (empty for this endpoint as it's backend direct upload)
fileRecordId	str	File record ID
contentType	str	File MIME type
fileName	str	File name

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

Quick Skills

listSkills · List Skills

OpenAPI skill list query.

POST /openapi/listSkills

Request fields:

Field	Type	Required	Description
filterType	str	❌	Filter type: ALL / BUILTIN / CUSTOM / DRAFT / ALL_WITH_DRAFTS (default ALL)
tags	list[str]	❌	Filter by tags; matches if any tag hits
keyword	str	❌	Keyword search; fuzzy matches name or description
page	int	❌	Page number (default 1)
pageSize	int	❌	Page size, 1-100 (default 20)
operatingObjectName	str	❌	Digital Worker name; must be provided together with bindStatus
bindStatus	str	❌	Binding status: BOUND / UNBOUND; must be provided together with operatingObjectName

Response fields:

Field	Type	Description
items	list[OpenAPISkillItem]	Skill list
total	int	Total count of matching skills
page	int	Current page number
pageSize	int	Page size

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 · Get Skill Details

OpenAPI skill detail query.

POST /openapi/getSkill

Request fields:

Field	Type	Required	Description
skillCode	str	❌	Skill code (globally unique); takes priority over skillName
skillName	str	❌	Skill name; used when skillCode is not provided; must be unique within tenant
viewMode	str	❌	View mode: draft / published (default)
includeSkillFiles	bool	❌	Whether to return the full file tree (default false)

Response fields (excerpt):

Field	Type	Description
skillHubDefinitionId	int	Skill definition ID
skillCode	str	Skill code (globally unique)
name	str	Skill name (i18n-resolved)
displayName	str	Display name
description	str	Skill description
tags	list[str]	Tag list
sourceType	str	Source type: BUILTIN / CUSTOM
globalAccess	bool	Whether globally accessible
executeMode	str	Execution mode
inputConfig	str	Input configuration raw text
inputConfigFormatted	list[dict]	Structured input schema array
detailLogic	str	Detailed skill logic
skillMdSummary	str	SKILL.md summary
versionNumber	str	Version number
versionCount	int	Total version count
status	str	Skill status: ACTIVE / DRAFT
hasDraftChanges	bool	Whether unpublished draft changes exist
createdTime	str	Creation time ISO8601
updatedTime	str	Modification time ISO8601
arguments	list[ArgumentSchema]	Simplified parameter schema describing what runSkill.arguments needs
skillFiles	list[dict]	Skill file nested tree (only when includeSkillFiles=True)

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

runSkill · Run Skill Asynchronously

Submit a skill for async execution. Returns a runId for subsequent polling via getSkillRun.

POST /openapi/runSkill

Request fields:

Field	Type	Required	Description
skillCode	str	❌	Skill code (globally unique); takes priority over skillName
skillName	str	❌	Skill name; used when skillCode is not provided; must be unique within tenant
arguments	dict[str, Any]	❌	Skill input parameter dictionary; schema described by getSkill's arguments field
clientToken	str	❌	Idempotency token, caller-generated (current version only records to metadata)

Response fields:

Field	Type	Description
runId	str	Async task ID for getSkillRun queries
skillCode	str	Skill code actually executed
skillName	str	Skill name
status	str	Task status: returns Running on submission
createdAt	str	Task creation time, ISO8601 UTC format

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 · Get Async Skill Run Result

OpenAPI async skill execution result query entry.

POST /openapi/getSkillRun

Request fields:

Field	Type	Required	Description
runId	str	❌	Async task ID returned by runSkill
includeLogs	bool	❌	Whether to include execution logs (default false)

Response fields:

Field	Type	Description
runId	str	Async task ID
skillCode	str	Skill code
skillName	str	Skill name
status	str	Execution status: Running / Succeeded / Failed / Cancelled
progress	int	Progress percentage (meaningful only during Running)
progressMessage	str	Progress description
result	dict[str, Any]	Execution result; returned only on Succeeded; contains content list
usage	dict[str, Any]	LLM token usage statistics; returned only on Succeeded
logs	list[dict[str, Any]]	Execution log list (only when includeLogs=true)
errorCode	str	Error code; returned only on Failed
errorMessage	str	Error description; returned only on Failed
createdAt	str	Task creation time ISO8601
startedAt	str	Task start time ISO8601
finishedAt	str	Task end time ISO8601; only available in terminal states

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

My Resources

createPersonalFile · Upload File to My Resources

Upload a file to the current Digital Worker's "My Resources".

POST /openapi/createPersonalFile

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)
name	str	✅	Resource display name
filePath	str	✅	File OSS persistent address
filePublicUrl	str	❌	File public access URL (signed)
fileName	str	❌	Original file name (with extension)
fileExt	str	❌	File extension (e.g., pdf, docx)
fileRecordId	str	❌	File record ID
directoryId	str	❌	Target directory ID
description	str	❌	Resource description

Response fields:

Field	Type	Description
sourceId	str	New resource ID
name	str	Resource display name
status	str	Resource status
scope	str	Resource scope, fixed as PERSONAL
directoryId	str	Bound directory ID
gmtCreate	str	Creation time ISO8601

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 · Upload Plain Text to My Resources

Upload plain text to the current Digital Worker's "My Resources".

POST /openapi/createPersonalText

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)
name	str	✅	Resource display name
textContent	str	✅	Plain text body
directoryId	str	❌	Target directory ID
description	str	❌	Resource description

Response fields:

Field	Type	Description
sourceId	str	New resource ID
name	str	Resource display name
status	str	Resource status (initially PENDING; FAILED on failure)
scope	str	Resource scope, fixed as PERSONAL
directoryId	str	Bound directory ID
gmtCreate	str	Creation time ISO8601

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

createPersonalVoiceMeeting · Upload Offline Meeting to My Resources

Upload offline meeting audio to the current Digital Worker's "My Resources".

POST /openapi/createPersonalVoiceMeeting

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)
name	str	✅	Resource display name
fileUrl	str	✅	Offline meeting audio file URL
directoryId	str	❌	Target directory ID
description	str	❌	Resource description

Response fields:

Field	Type	Description
sourceId	str	New resource ID
name	str	Resource display name
status	str	Resource status (initially PENDING; FAILED on failure)
scope	str	Resource scope, fixed as PERSONAL
directoryId	str	Bound directory ID
gmtCreate	str	Creation time ISO8601

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 · Upload DingTalk Meeting to My Resources

Upload a DingTalk meeting to the current Digital Worker's "My Resources".

POST /openapi/createPersonalDingtalkMeeting

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)
name	str	✅	Resource display name
roomCode	str	✅	DingTalk meeting room code
credentialId	str	❌	Credential ID (uses system default if not provided)
directoryId	str	❌	Target directory ID
description	str	❌	Resource description
notes	str	❌	Meeting notes content, used for supplementary analysis

Response fields:

Field	Type	Description
sourceId	str	New resource ID
name	str	Resource display name
status	str	Resource status
scope	str	Resource scope, fixed as PERSONAL
directoryId	str	Bound directory ID
gmtCreate	str	Creation time ISO8601

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 · Upload AliDing Meeting to My Resources

Upload an AliDing meeting to the current Digital Worker's "My Resources".

POST /openapi/createPersonalAliDingMeeting

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)
name	str	✅	Resource display name
ossUrl	str	✅	Public audio/video OSS address
shanjiUrl	str	✅	Original Shanji link
directoryId	str	❌	Target directory ID
description	str	❌	Resource description
notes	str	❌	Meeting notes content, used for supplementary analysis

Response fields:

Field	Type	Description
sourceId	str	New resource ID
name	str	Resource display name
status	str	Resource status
scope	str	Resource scope, fixed as PERSONAL
directoryId	str	Bound directory ID
gmtCreate	str	Creation time ISO8601

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 · Upload AliDing Online Document to My Resources

Upload an AliDing online document to the current Digital Worker's "My Resources".

POST /openapi/createPersonalAliDingDoc

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)
name	str	✅	Resource display name (recommended to use DingTalk document title)
filePublicUrl	str	✅	AliDing online document public access URL
directoryId	str	❌	Target directory ID
description	str	❌	Resource description

Response fields:

Field	Type	Description
sourceId	str	New resource ID
name	str	Resource display name
status	str	Resource status (initially PENDING; FAILED on on_create failure)
scope	str	Resource scope, fixed as PERSONAL
directoryId	str	Bound directory ID (null when using default root directory)
filePublicUrl	str	Document public URL (echoed from input)
gmtCreate	str	Creation time ISO8601

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 · Create AliDing Knowledge Base in My Resources

Create an AliDing knowledge base in the current Digital Worker's "My Resources".

POST /openapi/createPersonalAliDingKnowledgeBase

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)
kbUrl	str	✅	AliDing knowledge base public access URL
kbName	str	❌	Knowledge base display name; auto-filled from remote root node name if omitted
directoryId	str	❌	Target directory ID
objectBindings	list[ObjectBinding]	❌	Multi-value object binding list; written to KB metadata, passed through to child sources during sync
syncConfig	SyncConfig	❌	Scheduled sync configuration; treated as disabled if omitted

Response fields:

Field	Type	Description
directoryId	str	New knowledge base root directory ID
name	str	Knowledge base display name
status	str	Root directory status (RUNNING after creation; transitions to READY or FAILED after sync)
kbUrl	str	Knowledge base URL (echoed from input)
operatingObjectName	str	Owner Digital Worker name (echoed from input)
gmtCreate	str	Creation time ISO8601

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 · Upload Feishu Minutes Meeting to My Resources

Upload a Feishu Minutes meeting to the current Digital Worker's "My Resources".

POST /openapi/createPersonalFeishuMinute

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)
name	str	✅	Resource display name
minuteToken	str	✅	Feishu Minutes token (unique identifier)
credentialId	str	✅	Credential ID (linked to rbj_credential table)
directoryId	str	❌	Target directory ID
description	str	❌	Resource description

Response fields:

Field	Type	Description
sourceId	str	New resource ID
name	str	Resource display name
status	str	Resource status
scope	str	Resource scope, fixed as PERSONAL
directoryId	str	Bound directory ID
gmtCreate	str	Creation time ISO8601

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 · Create Personal Directory in My Resources

Create a personal directory (category) under "My Resources".

POST /openapi/createPersonalDirectory

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)
name	str	✅	Directory name
parentDirectoryId	str	❌	Parent directory ID
description	str	❌	Directory description

Response fields:

Field	Type	Description
directoryId	str	New directory ID
name	str	Directory name
path	str	Full directory path (auto-calculated)
description	str	Directory description
parentDirectoryId	str	Parent directory ID (returns backfilled ID when default root directory is used)
operatingObjectName	str	Owner Digital Worker name
directoryKind	str	Directory KB type: normal / aliding_kb_root / aliding_kb_internal
gmtCreate	int	Creation timestamp (milliseconds)
gmtModified	int	Modification timestamp (milliseconds)

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

listPersonalDirectoryContents · Drill Down Personal Resource Directory Contents

Drill down to query subdirectories and resources under a "My Resources" directory.

POST /openapi/listPersonalDirectoryContents

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)
directoryId	str	✅	Directory ID
page	int	❌	Page number (default 1)
pageSize	int	❌	Page size, 1-100 (default 20)
sortField	str	❌	Sort field: name / gmt_create / gmt_modified (default name)
sortOrder	str	❌	Sort direction: asc / desc (default asc)
sourceTypes	list[str]	❌	Resource type filter

Response fields:

Field	Type	Description
items	list[PersonalDirectoryContentItem]	Unified paginated list of directory contents (subdirectories + resources)
total	int	Total count (before pagination)
page	int	Current page number
pageSize	int	Page size

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 · Get Data Source Details

OpenAPI data source detail query.

POST /openapi/getSource

Request fields:

Field	Type	Required	Description
sourceId	str	❌	Data source ID (unique within tenant)
includeDetails	bool	❌	Whether to return details (default false)

Response fields:

Field	Type	Description
sourceId	str	Data source ID
sourceType	str	Data source type
sourceKind	str	Data source kind: normal / aliding_kb_doc
name	str	Data source name
description	str	Data source description
status	str	Data source status
scope	str	Visibility scope: PERSONAL / TENANT
objectType	str	Primary object type (compatibility field)
objectId	str	Primary object ID (compatibility field)
operatingObjectName	str	Operating object name
objectBindings	list[ObjectBindingItem]	Multi-value object binding list
skillOutputId	str	Skill output ID
sourceTags	str	Resource tags JSON string
hasSettings	bool	Whether settings configuration exists
hasNotes	bool	Whether notes exist
hasStructuredTables	bool	Whether structured tables exist
hasUnstructuredDocs	bool	Whether unstructured documents exist
gmtCreate	str	Creation time ISO8601
gmtModified	str	Modification time ISO8601
settings	dict	Data source configuration (only when includeDetails=True)
notes	str	Notes (only when includeDetails=True)
structuredTables	list[str]	Structured table name list (only when includeDetails=True)
unstructuredDocs	list[UnstructuredDocItem]	Unstructured document details (only when includeDetails=True; excludes content)

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

getSourceUploadSignature · Get Data Source File OSS Direct Upload Signature URL

Get an OSS direct upload signature URL for data source files, used for large file uploads.

POST /openapi/getSourceUploadSignature

Request fields:

Field	Type	Required	Description
filename	str	✅	File name (with extension, e.g., report.pdf)
operatingObjectName	str	❌	Agent namespace identifier (Digital Worker name)
expires	int	❌	Signature URL expiration time (seconds), default 3600
contentType	str	❌	File Content-Type (auto-inferred if not provided)
scope	str	❌	Ownership scope: source (personal, maps to PERSONAL) / knowledge (enterprise KB, maps to TENANT)

Response fields:

Field	Type	Description
objectName	str	OSS object name
fileUrl	str	File OSS internal URL
filePublicUrl	str	File public access URL
uploadSignatureUrl	str	Signed upload URL (PUT method)
fileRecordId	str	File record ID
method	str	Upload HTTP method (fixed as PUT)
expiresIn	int	Signature URL validity duration (seconds)
contentType	str	File Content-Type

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

moveResource · Move Resource Between Personal Directories

Move a resource between personal directories.

POST /openapi/moveResource

Request fields:

Field	Type	Required	Description
sourceDirectoryId	str	✅	Source directory ID (current personal directory of the resource)
targetDirectoryId	str	✅	Target directory ID (personal directory to move the resource to)
sourceId	str	✅	ID of the resource to move

Response fields:

Field	Type	Description
success	bool	Whether the move was successful
sourceId	str	Resource ID (echoed from input)
sourceDirectoryId	str	Source directory ID (echoed from input)
targetDirectoryId	str	Target directory ID (echoed from input)

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 · Rename Data Source

Rename a data source (lightweight operation).

POST /openapi/renameSource

Request fields:

Field	Type	Required	Description
sourceId	str	✅	Data source ID (unique within tenant)
newName	str	✅	New data source name

Response fields:

Field	Type	Description
sourceId	str	Data source ID
name	str	Renamed data source name
status	str	Data source status
gmtModified	str	Last modification time, ISO8601 format

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

updateDirectory · Update Personal Directory

Update personal directory basic information.

POST /openapi/updateDirectory

Request fields:

Field	Type	Required	Description
directoryId	str	✅	Directory unique identifier (business ID, not primary key ID)
name	str	❌	New directory name; omit to skip update
description	str	❌	New directory description; omit to skip update
parentId	int	❌	New parent directory primary key ID; omit to skip update
path	str	❌	New directory path; cascades update to current directory and all subdirectories

Response fields:

Field	Type	Description
success	bool	Whether update was successful
directoryId	str	Directory unique identifier (echoed from input)

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

retryDirectoryFailedSources · Retry Failed Data Sources in Personal Directory

Get failed data sources in a personal directory and batch retry (recursively includes subdirectories).

POST /openapi/retryDirectoryFailedSources

Request fields:

Field	Type	Required	Description
directoryId	str	✅	Directory ID (recursively includes failed resources in subdirectories)

Response fields:

Field	Type	Description
directoryId	str	Directory ID
failedCount	int	Total failed resources in the directory
enqueuedCount	int	Number successfully enqueued for retry
skippedCount	int	Number skipped (not FAILED or no permission)
enqueuedIds	list[str]	List of source_ids successfully enqueued
failedSources	list[FailedSourceItem]	List of failed data sources detected in the directory

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

previewPersonalSource · Preview Personal Knowledge

Preview the content of a specific resource in the personal knowledge base (only allows previewing own resources, PERSONAL type directories).

POST /openapi/previewPersonalSource

Request fields:

Field	Type	Required	Description
sourceId	str	✅	Resource ID (data source unique identifier)

Response fields:

Field	Type	Description
previewType	str	Preview type: OSS_IMM / IMAGE / AUDIO / VIDEO / HTML / DING_TALK / VOICE_MEETING / CONTENT
previewUrl	str	Preview URL (used for OSS_IMM, DING_TALK, VOICE_MEETING)
content	str	Text content (used for CONTENT type)
fileName	str	File name (used for OSS_IMM type)
fileExt	str	File extension (used for OSS_IMM type)
publicUrl	str	Public download URL

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

listOutputFiles · List Current User's Outputs

List the current user's outputs.

POST /openapi/listOutputFiles

Request: No request body parameters.

Response fields:

Field	Type	Description
items	list[ListOutputFilesRecord]	Output list
total	int	Total count of matching outputs
page	int	Current page number
pageSize	int	Page size

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

saveOutputFileToResource · Batch Save Outputs as Personal Resources

Batch save output items as personal resources (link reference or copy).

POST /openapi/saveOutputFileToResource

Request fields:

Field	Type	Required	Description
itemIds	list[str]	❌	Output item ID list, max 50 per batch
mode	Literal["link","copy"]	❌	Save mode: link — link reference, copy — copy into storage
directoryId	str	❌	Target personal directory ID

Response fields:

Field	Type	Description
results	list[SaveOutputFileToResourceItem]	Per-item results, same order as input itemIds; individual failures don't affect others

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"}'

Knowledge Base

listVisibleKnowledgeBases · List Knowledge Bases Visible to a Digital Worker

Query the top-level enterprise knowledge base directories visible to a Digital Worker.

POST /openapi/listVisibleKnowledgeBases

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)

Response fields:

Field	Type	Description
items	list[VisibleKnowledgeBaseItem]	Top-level enterprise knowledge base directories visible to the Digital Worker
total	int	Count returned (not paginated)

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

listVisibleKnowledgeBaseContents · Drill Down Visible Knowledge Base Directory Contents

Drill down to query subdirectories and resources under a knowledge base directory visible to a Digital Worker.

POST /openapi/listVisibleKnowledgeBaseContents

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name (operating object name)
directoryId	str	✅	Directory ID (required, must be within the Digital Worker's linked_directories and subdirectories scope)
page	int	❌	Page number (default 1)
pageSize	int	❌	Page size, 1-100 (default 20)
sortField	str	❌	Sort field: name / gmt_create / gmt_modified (default name)
sortOrder	str	❌	Sort direction: asc / desc (default asc)
sourceTypes	list[str]	❌	Resource type filter (when provided, only returns resources)

Response fields:

Field	Type	Description
items	list[VisibleKnowledgeBaseContentItem]	Unified paginated list of directory contents
total	int	Total count (before pagination)
page	int	Current page number
pageSize	int	Page size

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 · Admin List/Drill-Down Knowledge Bases

Admin enterprise knowledge base list / drill-down query.

POST /openapi/listAdminKnowledgeBases

Request fields:

Field	Type	Required	Description
directoryId	str	❌	Directory ID (provide when drilling down)
page	int	❌	Page number (default 1)
pageSize	int	❌	Page size, 1-100 (default 20)
sortField	str	❌	Sort field: name / gmtCreate / gmtModified (default name)
sortOrder	str	❌	Sort direction: asc / desc (default asc)
keyword	str	❌	Search keyword; only effective when directoryId is empty/root
sourceTypes	list[str]	❌	Resource type filter; only effective when drilling down

Response fields:

Field	Type	Description
items	list[AdminKnowledgeBaseItem]	Content list (KB list: directories only; drill-down: directories + resources)
total	int	Total count matching criteria
page	int	Current page number
pageSize	int	Page size

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 · Submit Personal Resource to Knowledge Base

Submit a personal resource to the enterprise knowledge base (tenant directory).

POST /openapi/submitSourceToKnowledgeBase

Request fields:

Field	Type	Required	Description
sourceId	str	✅	Personal resource ID to submit (must be scope=PERSONAL and current user is creator)
targetDirectoryId	str	✅	Target enterprise knowledge base directory ID (must be TENANT type directory)

Response fields:

Field	Type	Description
sourceId	str	Resource ID (unchanged after migration)
scope	str	Resource scope after submission, fixed as TENANT on success
targetDirectoryId	str	Target enterprise knowledge base directory ID the resource is now bound to

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 · Upload File to Knowledge Base

Upload a file to the enterprise knowledge base (requires KB management permission).

POST /openapi/createKnowledgeBaseFile

Request fields:

Field	Type	Required	Description
operatingObjectName	str	❌	Digital Worker name (operating object name)
name	str	✅	Resource display name
filePath	str	✅	File OSS persistent address
filePublicUrl	str	❌	File public access URL (signed)
fileName	str	❌	Original file name (with extension)
fileExt	str	❌	File extension (e.g., pdf, docx)
fileRecordId	str	❌	File record ID
directoryId	str	❌	Target category ID
description	str	❌	Resource description
knowledgeId	str	❌	Knowledge base ID
sourceTags	str	❌	Resource tags (JSON string list)

Response fields:

Field	Type	Description
sourceId	str	New resource ID
name	str	Resource display name
status	str	Resource status
scope	str	Resource scope, fixed as TENANT
directoryId	str	Bound directory ID
gmtCreate	str	Creation time ISO8601

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 · Upload Plain Text to Knowledge Base

Upload plain text to the enterprise knowledge base (requires KB management permission).

POST /openapi/createKnowledgeBaseText

Request fields:

Field	Type	Required	Description
operatingObjectName	str	❌	Digital Worker name
name	str	✅	Resource display name
textContent	str	✅	Plain text body
directoryId	str	❌	Target category ID
description	str	❌	Resource description
knowledgeId	str	❌	Knowledge base ID
sourceTags	str	❌	Resource tags (JSON string list)

Response fields: sourceId / name / status / scope(TENANT) / directoryId / gmtCreate (same as createKnowledgeBaseFile).

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

createKnowledgeBaseAliDingDoc · Upload AliDing Online Document to Knowledge Base

Upload an AliDing online document to the enterprise knowledge base (requires KB management permission).

POST /openapi/createKnowledgeBaseAliDingDoc

Request fields:

Field	Type	Required	Description
operatingObjectName	str	❌	Digital Worker name
name	str	✅	Resource display name (recommended to use DingTalk document title)
filePublicUrl	str	✅	AliDing online document public access URL
directoryId	str	❌	Target category ID
description	str	❌	Resource description
knowledgeId	str	❌	Knowledge base ID
sourceTags	str	❌	Resource tags (JSON string list)

Response fields: sourceId / name / status / scope(TENANT) / directoryId / filePublicUrl / gmtCreate.

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 · Create Knowledge Base Category

Create a knowledge base category (tenant directory, requires KB management permission).

POST /openapi/createKnowledgeBaseDirectory

Request fields:

Field	Type	Required	Description
name	str	✅	Category name (enterprise knowledge base directory name)
parentDirectoryId	str	❌	Parent category ID; placed under tenant root if omitted
description	str	❌	Category description

Response fields:

Field	Type	Description
directoryId	str	New category ID
name	str	Category name
path	str	Full category path (auto-calculated)
description	str	Category description
parentDirectoryId	str	Parent category ID; returns null when placed under root
directoryKind	str	Directory KB type: normal / aliding_kb_root / aliding_kb_internal
gmtCreate	int	Creation timestamp (milliseconds)
gmtModified	int	Modification timestamp (milliseconds)

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

getKnowledgeBaseSource · Get Knowledge Base Resource Details

Get details of a specific resource in the enterprise knowledge base (requires KB view permission).

POST /openapi/getKnowledgeBaseSource

Request fields:

Field	Type	Required	Description
sourceId	str	❌	Resource ID (data source unique identifier)

Response fields:

Field	Type	Description
sourceId	str	Resource ID
sourceType	str	Resource type (TEXT / FILE / ONLINE_DOC, etc.)
name	str	Resource name
description	str	Resource description
status	str	Processing status (READY / RUNNING / FAILED, etc.)
statusMessage	str	Status additional info (e.g., failure reason)
sourceKind	str	Resource KB type: aliding_kb_doc / normal
sourceTags	str	Resource tags (JSON string list)
directoryId	str	Category ID
directoryPath	str	Full category path
gmtCreate	int	Creation timestamp (milliseconds)
gmtModified	int	Modification timestamp (milliseconds)

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

listKnowledgeBaseDirectories · List Knowledge Base Categories

Get the enterprise knowledge base category list (subdirectory tree, requires KB view permission).

POST /openapi/listKnowledgeBaseDirectories

Request fields:

Field	Type	Required	Description
directoryId	str	❌	Parent category ID; returns all category tree under root if omitted
sortField	str	❌	Sort field: name / gmt_create / gmt_modified (default gmt_create)
sortOrder	str	❌	Sort direction: asc / desc (default desc)

Response fields:

Field	Type	Description
directories	list[dict[str, Any]]	Category tree (nested, contains directoryId/name/description/path/directoryKind/gmtCreate/gmtModified/children)
totalCount	int	Total category count

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

updateKnowledgeBaseDirectory · Update Knowledge Base Category

Update a knowledge base category (tenant directory, requires KB management permission).

POST /openapi/updateKnowledgeBaseDirectory

Request fields:

Field	Type	Required	Description
directoryId	str	✅	Category ID to update
name	str	❌	New category name; omit to skip update
description	str	❌	New category description; omit to skip update
parentDirectoryId	str	❌	New parent category ID; omit to skip move; must be an existing KB directory in the current tenant

Response fields:

Field	Type	Description
success	bool	Whether update was successful
directoryId	str	Category ID (echoed from input)

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

moveKnowledgeBaseResource · Move Resource Between Knowledge Base Directories

Move a resource between enterprise knowledge base directories (requires KB management permission).

POST /openapi/moveKnowledgeBaseResource

Request fields:

Field	Type	Required	Description
sourceDirectoryId	str	✅	Source directory ID
targetDirectoryId	str	✅	Target directory ID
sourceId	str	✅	ID of the resource to move
knowledgeId	str	✅	Target knowledge base ID

Response fields: sourceId / sourceDirectoryId / targetDirectoryId / knowledgeId (all echoed from input).

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 · Rename Knowledge Base Data Source

Rename a data source in the enterprise knowledge base (requires KB management permission).

POST /openapi/renameKnowledgeBaseSource

Request fields:

Field	Type	Required	Description
sourceId	str	✅	Data source ID (unique within tenant)
newName	str	✅	New data source name

Response fields: sourceId / name / status / gmtModified (same as renameSource).

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

updateKnowledgeBaseSourceTags · Update Knowledge Base Data Source Tags

Update resource tags for a knowledge base data source (requires KB management permission).

POST /openapi/updateKnowledgeBaseSourceTags

Request fields:

Field	Type	Required	Description
sourceId	str	✅	Data source ID (unique within tenant)
sourceTags	str	❌	Resource tags (JSON string list)

Response fields:

Field	Type	Description
sourceId	str	Data source ID
sourceTags	str	Updated resource tags
gmtModified	str	Last modification time, ISO8601 format

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

retryKnowledgeBaseFailedSources · Retry Failed Data Sources in Knowledge Base Directory

Get failed data sources in a knowledge base directory and batch retry (recursively includes subdirectories).

POST /openapi/retryKnowledgeBaseFailedSources

Request fields:

Field	Type	Required	Description
directoryId	str	✅	Enterprise knowledge base directory ID (recursively includes subdirectories)

Response fields: directoryId / failedCount / enqueuedCount / skippedCount / enqueuedIds / failedSources (same as retryDirectoryFailedSources; failedSources is list[KbFailedSourceItem]).

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

previewKnowledgeBaseSource · Preview Knowledge Base Resource

Preview the content of a specific resource in the enterprise knowledge base (requires DEVELOPMENT_KB_VIEW permission, TENANT type directories).

POST /openapi/previewKnowledgeBaseSource

Request fields:

Field	Type	Required	Description
sourceId	str	✅	Resource ID (data source unique identifier)

Response fields: previewType / previewUrl / content / fileName / fileExt / publicUrl (same as previewPersonalSource).

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

Scheduled Tasks

createScheduledTask · Create Scheduled Task

Create a scheduled task.

POST /openapi/createScheduledTask

Request fields:

Field	Type	Required	Description
name	str	✅	Task name (max 50 characters)
description	list[SegmentItem]	❌	Task description (segments format), supports text/web_search/mention/skill types
digitalEmployeeName	str	❌	Digital Worker name
triggerConfig	TriggerConfigRequest	❌	Trigger configuration including trigger mode, cron expression, etc.; timezone/language auto-injected by server
taskDetail	TaskDetailRequest	❌	Task detail (understanding result passback) including task understanding, related semantics, objects, and skills
isOpen	bool	❌	Whether publicly accessible (default true)
segments	list[SegmentItem]	❌	Rich text message segments, supports @object (type=mention) and /skill (type=skill)

Response fields:

Field	Type	Description
taskId	str	New task ID

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

updateScheduledTask · Update Scheduled Task

Update an existing scheduled task definition.

POST /openapi/updateScheduledTask

Request fields:

Field	Type	Required	Description
taskId	str	✅	Task ID
name	str	❌	Task name (max 50 characters)
description	list[SegmentItem]	❌	Task description (segments format), supports text/web_search/mention/skill
digitalEmployeeName	str	❌	Digital Worker name
triggerConfig	TriggerConfigRequest	❌	Trigger configuration (trigger mode, cron, etc.); timezone/language auto-injected by server
taskDetail	TaskDetailRequest	❌	Task detail (understanding result passback)
isOpen	bool	❌	Whether publicly accessible
segments	list[SegmentItem]	❌	Rich text message segments, supports @object and /skill

Response fields:

Field	Type	Description
taskId	str	Task ID (echoed)
updated	bool	Whether an actual update occurred

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

listScheduledTasks · List Scheduled Tasks

Get the current user's scheduled task list.

POST /openapi/listScheduledTasks

Request fields:

Field	Type	Required	Description
page	int	❌	Page number (default 1)
pageSize	int	❌	Page size (1-100, default 20)
keyword	str	❌	Task name fuzzy search
digitalEmployeeName	str	❌	Filter by Digital Worker name

Response fields:

Field	Type	Description
items	list[ScheduledTaskItem]	Task list
total	int	Total count matching criteria
page	int	Current page number
pageSize	int	Page size
hasMore	bool	Whether more data is available

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

executeScheduledTask · Execute Scheduled Task Immediately

Immediately execute a specified scheduled task, creating a manually triggered execution record and returning task execution metadata that can be passed through to the Chat chain.

POST /openapi/executeScheduledTask

Request fields:

Field	Type	Required	Description
taskId	str	✅	Task ID

Response fields:

Field	Type	Description
executionId	str	Execution record ID
taskExecution	ScheduledTaskExecutionPayload	Execution metadata that can be passed through to Chat metadata.task_execution

taskExecution (ScheduledTaskExecutionPayload) structure:

Field	Type	Description
taskId	str	Task ID
executionId	str	Execution record ID
taskUnderstand	str	Task understanding content
operatingObjectName	str	Digital Worker name
skillCodes	array<str>	Associated skill code list
enableWebSearch	boolean	Whether web search is enabled
billingId	str	Billing ID for Chat callback to end billing
tenantId	str	Task tenant ID
userId	str	Task user ID
taskName	str	Task name
model	str	Execution model tier: model_max(flagship)/model_plus(standard)/model_flash(lite)

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

getScheduledTaskExecutionDetail · Get Scheduled Task Execution Details

Get the full details of a single execution record.

POST /openapi/getScheduledTaskExecutionDetail

Request fields:

Field	Type	Required	Description
executionId	str	✅	Execution record ID

Response fields:

Field	Type	Description
executionId	str	Execution ID
taskId	str	Task ID
triggerType	str	Trigger type
digitalEmployeeName	str	Digital Worker name
triggerInfo	dict[str, Any]	Trigger information
status	str	Execution status
skillCodes	list[str]	Associated skill code list
title	str	Execution result title
content	str	Full execution content
outputContent	str	Structured output content
errorMessage	str	Error message
metadata	dict[str, Any]	Metadata
files	list[dict[str, Any]]	Output file list
startedAt	str	Start time ISO8601
completedAt	str	Completion time ISO8601
creator	str	Creator
gmtCreate	str	Creation time ISO8601

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

getScheduledTaskExecutionRecords · Get Scheduled Task Execution Records

Query execution record timeline aggregated by operating object for all tasks.

POST /openapi/getScheduledTaskExecutionRecords

Request fields:

Field	Type	Required	Description
digitalEmployeeName	str	✅	Digital Worker name

Response fields:

Field	Type	Description
tasks	list[ScheduledTaskTimeline]	Timeline of all scheduled tasks

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

getScheduledTaskPushOptions · Get Scheduled Task Push Configuration Options

Query push channels and methods available for scheduled task notifications for the current user.

POST /openapi/getScheduledTaskPushOptions

Request fields:

Field	Type	Required	Description
digitalEmployeeName	str	✅	Digital Worker name

Response fields:

Field	Type	Description
channels	array<ScheduledTaskPushChannelOption>	Push channel list
emptyHint	str	Hint when no third-party accounts are bound

channels[] (ScheduledTaskPushChannelOption) structure:

Field	Type	Description
channelType	str	Channel enum value
channelName	str	Channel display name
methods	array<ScheduledTaskPushMethodOption>	Push method list

methods[] (ScheduledTaskPushMethodOption) structure:

Field	Type	Description
method	str	Push method: channel_bot/direct
name	str	Push method display name
enabled	boolean	Whether selectable
disabledReason	str	Reason for being grayed out

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

getScheduledTaskUnderstandDetail · Get Scheduled Task Understanding Details

Use LLM to understand natural language user input, extracting semantic entities, related objects, and related skills.

POST /openapi/getScheduledTaskUnderstandDetail

Request fields:

Field	Type	Required	Description
userInput	str	✅	Natural language task description
digitalEmployeeName	str	❌	Digital Worker name, used to filter available skills
segments	list[SegmentItem]	❌	Rich text message segments, supports @object (type=mention) and /skill (type=skill)

Response fields:

Field	Type	Description
taskUnderstand	str	Refined task understanding
relatedSemantics	list[SemanticEntityOpen]	Related semantic entity list
relatedObjects	list[RelatedObjectOpen]	Related object list
relatedSkills	list[RelatedSkillOpen]	Related skill list

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

Primary Object Data

queryPrimaryObjectData · Paginated Query of Primary Object Data

Paginated query of primary object data via OpenAPI.

POST /openapi/queryPrimaryObjectData

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Operating object name (e.g., customer_1)
page	int	❌	Page number (default 1)
pageSize	int	❌	Page size, 1-100 (default 20)
keyword	str	❌	Keyword search (matches name; also matches description when defined in schema)
onlyFavorites	bool	❌	Return only followed primary objects (default false)

Response fields:

Field	Type	Description
total	int	Total count
page	int	Current page number
pageSize	int	Page size
items	list[dict[str, Any]]	Primary object data list (fields vary by schema definition)

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 · Follow/Unfollow Primary Objects

Batch follow or unfollow primary objects.

POST /openapi/togglePrimaryObjectFavorite

Request fields:

Field	Type	Required	Description
objectType	str	✅	Object type (e.g., customer, project)
operatingObjectName	str	✅	Operating object name (e.g., customer_1)
objectIds	list[str]	✅	Primary object business ID list
action	Literal["add","remove"]	✅	Action: add — follow, remove — unfollow

Response fields:

Field	Type	Description
results	list[TogglePrimaryObjectFavoriteResult]	Processing result for each object
favoriteCount	int	User's total follow count (for that object type)

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 · Replace Data Source Object Bindings

Fully replace a data source's object bindings (delete then insert within the same transaction).

POST /openapi/replaceObjectBindings

Request fields:

Field	Type	Required	Description
sourceId	str	✅	Data source ID (unique within tenant)
objectBindings	list[ObjectBindingItem]	✅	New object binding list (full replacement; pass empty to clear all bindings)

Response fields:

Field	Type	Description
sourceId	str	Data source ID
objectBindings	list[ObjectBindingItem]	Object binding list after replacement

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

User, Credit & Billing

getUserInfo · Get Current User Info

Get current user information via OpenAPI.

GET /openapi/getUserInfo

Request: No request body parameters.

Response fields:

Field	Type	Description
userId	int	User ID
userCode	str	User code
isAdmin	bool	Whether super admin
tenantId	int	Current tenant ID
tenantName	str	Current tenant name
tenantType	TenantType	Current tenant type
crmType	str	Current tenant CRM type
tenantList	list[TenantInfo]	List of tenants the user belongs to
name	str	User name
avatar	str	User avatar URL
languagePreference	str	User language preference
profileRole	str	User role
profileRoleInfo	str	User role description (when profileRole is Others)
offering	str	User service description
parsedOffering	str	User service parsed result (JSON)
selfIntroduction	str	User self-introduction
isSystemTenant	bool	Whether the current login tenant is the system tenant (tenantId=10000)

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

updateUserInfo · Update Current User Info

Update basic information of the currently logged-in user.

POST /openapi/updateUserInfo

Request fields:

Field	Type	Required	Description
name	str	❌	User name
avatar	str	❌	User avatar URL
languagePreference	str	❌	Language preference: zh-CN, en-US
profileRoleInfo	str	❌	User role description (when profileRole is Others), max 100 characters
offering	str	❌	User service description, max 1000 characters
selfIntroduction	str	❌	User self-introduction, max 1000 characters

Response fields:

Field	Type	Description
success	bool	Whether update was successful
message	str	Result description
user	UserInfo	Updated user information

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

getUserCreditUsage · Query User Credit Consumption

Query user's consumed Credit in real-time via OpenAPI.

POST /openapi/getUserCreditUsage

Request: No request body parameters.

Response fields:

Field	Type	Description
tenantId	int	Tenant ID
userId	int	User ID
creditLimit	Decimal	User Credit limit
usedCredits	Decimal	Used Credit (real-time)
remainingCredits	Decimal	Remaining Credit (real-time)
shadowCreditLimit	Decimal	Shadow Credit limit
shadowUsedCredits	Decimal	Used shadow Credit (real-time)
shadowRemainingCredits	Decimal	Remaining shadow Credit (real-time)

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

listBilling · List Billing Records

Query billing records via OpenAPI.

POST /openapi/listBilling

Request fields:

Field	Type	Required	Description
userId	int	❌	User ID (optional filter)
operation	str	❌	Operation type (optional filter)
status	str	❌	Status (optional filter)
startTime	datetime	❌	Start time range
endTime	datetime	❌	End time range
bizType	str	❌	Business source type (optional filter)
bizId	str	❌	Business source ID (optional filter)
ignoreZero	bool	❌	Whether to filter out billing records with zero Credit consumption (default true)
page	int	❌	Page number (default 1)
pageSize	int	❌	Page size (default 20)

Response fields:

Field	Type	Description
list	list[BillingItemResponse]	Billing list
total	int	Total count
page	int	Page number
pageSize	int	Page size

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

User & Permission Management

createUser · Create User and Join Tenant

Intelligently create a WINNEXO self-built account user and join the current tenant (if account already exists, directly joins).

POST /openapi/createUser

Request fields:

Field	Type	Required	Description
accountId	str	✅	WINNEXO login account (unique identifier)
displayName	str	✅	User display name (unique within tenant)
roleCodes	array<str>	❌	System roles: SUPER_ADMIN / SYSTEM_ADMIN / SEMANTIC_ADMIN / SKILL_ADMIN / KB_ADMIN / AGENT_ADMIN / APPLICATION_USER (default APPLICATION_USER)
passwordEncrypted	str	❌	RSA-OAEP-SHA256 encrypted base64 ciphertext; uses system default password if omitted

Response fields:

Field	Type	Description
userId	int	Platform user ID
accountId	str	WINNEXO login account
displayName	str	User display name
isNewUser	boolean	Whether this is a newly created user
isDefaultPassword	boolean	Whether using system default password (recommend notifying user to change when true)

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 · Update User Info (Including Enable/Disable)

Update user display name, roles, enable/disable status, and user groups. All fields except userId are optional (omit to skip; at least one must be changed); roleCodes/userGroupIds are full replacements.

POST /openapi/updateUser

Request fields:

Field	Type	Required	Description
userId	int	✅	Target user ID
displayName	str	❌	New display name (must not be empty if provided)
roleCodes	array<str>	❌	New role list (full replacement, at least one)
isActive	boolean	❌	Enable/disable (false=disable, true=enable)
userGroupIds	array<str>	❌	New user group ID list (full replacement)

Response fields: userId(int, the modified user ID). HTTP 200 indicates success.

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

getUser · Get User Details

Query user details. Provide either userId or accountId (if both provided, userId takes precedence).

POST /openapi/getUser

Request fields:

Field	Type	Required	Description
userId	int	❌	User ID (provide either this or accountId)
accountId	str	❌	WINNEXO login account (provide either this or userId)

Response fields:

Field	Type	Description
userId	int	User ID
accountId	str	WINNEXO login account
displayName	str	User display name
isActive	boolean	Enable/disable status
roleCodes	array<str>	System role code list
userGroupIds	array<str>	User group ID list
gmtCreate	str	Time joined tenant
lastLoginTime	str	Last login time

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

listUsers · Paginated Query of Tenant Members

Paginated query of tenant member list with status, role, and keyword filtering.

POST /openapi/listUsers

Request fields:

Field	Type	Required	Description
page	int	❌	Page number (default 1)
pageSize	int	❌	Page size (max 100, default 20)
keyword	str	❌	Search keyword (fuzzy matches display name and account)
isActive	boolean	❌	Enable/disable status filter
roleCodes	array<str>	❌	Filter by roles

Response fields: total(int) / page(int) / pageSize(int) / items(array<ListUsersItemResponse>).

items[]: userId / accountId / displayName / isActive / roleCodes / gmtCreate / lastLoginTime.

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

removeUser · Remove User from Tenant

Remove a user from the current tenant (preserves user entity), also removing their role/user group associations and Digital Worker authorizations. Includes last super admin protection.

POST /openapi/removeUser

Request fields:

Field	Type	Required	Description
userId	int	✅	User ID to remove

Response fields: userId(int, the removed user ID). HTTP 200 indicates success.

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

resetPassword · Reset User Password

Admin resets user password; resets to system default password if passwordEncrypted is omitted. Only supports WINNEXO self-built accounts.

POST /openapi/resetPassword

Request fields:

Field	Type	Required	Description
userId	int	✅	Target user ID
passwordEncrypted	str	❌	RSA-OAEP-SHA256 encrypted new password base64 ciphertext; resets to default if omitted

Response fields: userId(int) / isDefaultPassword(boolean, whether reset to system default password).

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

getTokenInfo · Query User Token Status

Query a user's INSTANCE Token status (only callable with personal Token). Empty userId queries self; super admin/system admin can query other users in the same tenant.

POST /openapi/getTokenInfo

Request fields (optional):

Field	Type	Required	Description
userId	int	❌	Target user ID (empty for self; admin can operate on behalf)

Response fields:

Field	Type	Description
enabled	boolean	Whether Token is enabled (has ACTIVE status)
tokenMasked	str	Masked Token value
gmtCreate	str	Token creation time (ISO 8601)

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

enableToken · Enable API Token

Enable a user's INSTANCE Token (idempotent). Plaintext is returned only on first enablement. Only callable with personal Token.

POST /openapi/enableToken

Request fields (optional): userId(int, empty for self; admin can operate on behalf).

Response fields:

Field	Type	Description
token	str	Token plaintext (returned only this once; store securely)
tokenMasked	str	Masked Token value

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

disableToken · Disable API Token

Disable a user's INSTANCE Token (ACTIVE → INACTIVE, idempotent). Only callable with personal Token.

POST /openapi/disableToken

Request fields (optional): userId(int, empty for self).

Response fields: disabled(boolean, whether operation succeeded).

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

resetToken · Reset API Token

Reset a user's INSTANCE Token: the old ACTIVE Token is permanently invalidated (RESET), and a new ACTIVE Token is generated. Only callable with personal Token.

POST /openapi/resetToken

Request fields (optional): userId(int, empty for self).

Response fields:

Field	Type	Description
token	str	New Token plaintext (returned only this once)
tokenMasked	str	Masked new Token value

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

grantAgentUsers · Authorize Users/Groups to Use a Digital Worker

Authorize users or user groups to use a specified Digital Worker (updates if already exists). Requires MANAGE permission. Provide either userIds or userGroupIds.

POST /openapi/grantAgentUsers

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name
userIds	array<int>	❌	Authorized user ID list (provide either this or userGroupIds)
userGroupIds	array<str>	❌	Authorized user group ID list (16-char hex)
expireDate	int	❌	Authorization expiration timestamp (milliseconds); never expires if omitted
permissions	array<str>	❌	Permissions: USE and/or MANAGE (default USE only)

Response fields: grantedCount(int, number of authorization records processed).

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 · Revoke Users/Groups Digital Worker Usage Permission

Revoke user or user group usage permissions for a specified Digital Worker. Requires MANAGE permission. Provide either userIds or userGroupIds.

POST /openapi/revokeAgentUsers

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name
userIds	array<int>	❌	User ID list to revoke (provide either this or userGroupIds)
userGroupIds	array<str>	❌	User group ID list to revoke

Response fields: revokedCount(int, number of records successfully revoked).

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

listAuthorizedAgents · List Digital Workers with Specified Permission

Query the list of Digital Worker names where the current caller has a specified permission (USE/MANAGE). Request body is optional; defaults to USE.

POST /openapi/listAuthorizedAgents

Request fields (optional): permission(str, USE / MANAGE, default USE).

Response fields: agentNames(array<str>, Digital Worker names with the specified permission).

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

listAuthorizedUsers · List Authorized Users/Groups for a Digital Worker

Query the list of authorized users/user groups for a Digital Worker (requires APPLICATION_AGENT_VIEW).

POST /openapi/listAuthorizedUsers

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name
keyword	str	❌	Search keyword (fuzzy matches user name or group name)
granteeType	str	❌	Filter: USER / USER_GROUP / omit for all
permission	str	❌	Permission filter: USE / MANAGE

Response fields: 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.

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

updateAgentAuthMode · Update Digital Worker Authorization Mode

Switch the Digital Worker's usage permission authorization mode. Requires MANAGE permission.

POST /openapi/updateAgentAuthMode

Request fields:

Field	Type	Required	Description
operatingObjectName	str	✅	Digital Worker name
authMode	str	✅	SPECIFIED_USERS = specified users (requires explicit authorization), ALL_USERS = all users (no authorization required)

Response fields: updated(boolean, whether update was successful).

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

Organization Sync

createCustomOrg · Register Custom Organization

Register a custom organization for subsequent department tree pushes via syncOrgStructure (only supports department tree sync, not member relationship sync).

POST /openapi/createCustomOrg

Request fields:

Field	Type	Required	Description
corpId	str	✅	Custom organization identifier, format ^[a-z0-9][a-z0-9\-]{2,63}$ (3-64 characters)
corpName	str	❌	Organization display name (same as corpId if omitted, max 128)

Response fields:

Field	Type	Description
corpId	str	Successfully registered organization identifier
corpName	str	Organization display name
platformType	str	Platform type, fixed as custom

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

syncOrgStructure · Push Organization Structure Sync

Receive client-pushed department tree and member relationships, create an async sync task, and return a taskId for polling via querySyncResult. Single push limit: departments + members total max 50000.

POST /openapi/syncOrgStructure

Request fields:

Field	Type	Required	Description
platformType	str	✅	Platform type: saml / oauth2 / custom
corpId	str	✅	Enterprise identifier (must match listAvailableConfigs response)
ssoSettingsId	str	❌	SSO configuration ID (required when multiple IdPs share corpId; not needed for custom)
syncMembers	boolean	❌	Whether to sync member relationships (default false; forced false for custom)
departments	array<PushDepartmentItem>	✅	Department list (at least one root department)
members	array<PushMemberItem>	❌	Member list (required when syncMembers=true)

departments[] (PushDepartmentItem): deptId(✅) / deptName(✅, max 128) / parentDeptId(null for root) / order(default 0).
members[] (PushMemberItem): deptId(✅) / accountId(✅, must match rbj_user_account.account_id) / name(optional).

Response fields:

Field	Type	Description
taskId	number	Async sync task ID for querySyncResult polling
status	str	Initial task status (PENDING)

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 · Query Organization Sync Result

Query the execution status and result of an organization sync task by taskId (states: PENDING → RUNNING → COMPLETED / FAILED / TIMEOUT / CANCELED; recommended polling interval: 3-5 seconds).

POST /openapi/querySyncResult

Request fields:

Field	Type	Required	Description
taskId	number	✅	Sync task ID (returned by syncOrgStructure)

Response fields:

Field	Type	Description
taskId	number	Task ID
status	str	Task status (PENDING / RUNNING / COMPLETED / FAILED / TIMEOUT / CANCELED)
platformType	str	Platform type
corpId	str	Enterprise identifier
submittedAt	str	Task submission time (ISO 8601)
startedAt	str	Task start time
completedAt	str	Task completion time
durationSeconds	number	Execution duration (seconds)
summary	str	Execution summary (human-readable)
errorMessage	str	Error message (present on failure)
deptStats	DeptStatsResponse	Department sync statistics (present on completion)
memberStats	MemberStatsResponse	Member sync statistics (present when syncMembers=true and completed)

deptStats: totalExternal / created / renamed / moved / deleted / skipped (all number).
memberStats: totalExternal / relationshipAdded / relationshipRemoved / unchanged / failed (all number).

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

listAvailableConfigs · List Available Organization Sync Configurations

Enumerate all available organization sync configurations under the current tenant, covering wecom / saml / oauth2 / custom platform types.

POST /openapi/listAvailableConfigs

Request: No request body parameters.

Response fields:

Field	Type	Description
configs	array<OrgSyncConfigItem>	Available organization sync configuration list

configs[] (OrgSyncConfigItem):

Field	Type	Description
platformType	str	Platform type: wecom / saml / oauth2 / custom
corpId	str	Enterprise identifier (wecom=corpId, saml=idpEntityId, oauth2=clientId, custom=client-defined)
corpName	str	Enterprise display name
ssoSettingsId	str	SSO configuration ID (null for custom)
ssoSettingsName	str	SSO configuration name (null for custom)

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

Best Practices

✓

"Prefer skills over chat" — Quick Skills are pre-configured "finished capabilities" set up by you or an admin, with stable parameters and predictable results. Calling chat directly is like having someone conduct a live conversation with a Digital Worker — results can vary.

✓

"Validate with CLI first, then convert to code" — All OpenAPI capabilities are wrapped in CLI commands. Verify parameters and response structures in the terminal first, then translate to code.

i

"Don't hardcode tokens" — Read from environment variables and inject via secret manager at deployment time.

---

📌 Related Reading: CLI, Custom Skills, Capability Center