Confirm saving a skill candidate

Import a server-saved skill candidate into the current workspace and, when explicitly selected, attempt to add it to its originating agent. Saving and binding occur in separate transaction phases.

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-runtime-tasks/{task_id}/skills/confirm

Before you call this API

Prepare a structured skill candidate from a trusted source and review its instructions and files. Use its original task_id/call_id/source_digest. Target workspace, current principal, and original run must match. Natural-language chat, manually assembled display content, or another task’s candidate are not substitutes. See candidate identity for provenance and permissions.

Request parameters

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agent-runtime-tasks/$TASK_ID/skills/confirm" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  --data '{"call_id":"<candidate-call-id>","source_digest":"<candidate-source-digest>","bind_current":false}'

Parameter

Type

Required

Description

workspace_id

string

Yes

Target workspace, matching X-Workspace-ID.

task_id

string

Yes

Original run task ID that produced the candidate, not an automation task definition or skill ID.

X-Workspace-ID

string

Yes

Target workspace in the current environment.

X-API-Key

string

Yes

Personal access token used in this example; current workspace access and candidate ownership checks also apply.

call_id

string

Yes

Original Skill Creator tool-call identifier, supplied in the JSON request body.

source_digest

string

Yes

Complete digest returned by the server candidate, used unchanged in the JSON request body.

bind_current

boolean

Yes

false saves only; true saves and then attempts binding to the candidate’s agent. Send an explicit boolean; omission, null, and strings are invalid.

Submit only call_id/source_digest/bind_current in the body, without display, a target agent_id, or file contents. Replace both candidate placeholders before calling.

Results

{
  "code": 0,
  "data": {
    "skill_id": "skill-example",
    "workspace_id": "ws-example",
    "agent_id": "agent-example",
    "bound": false
  }
}

Field

Type

Description

code

integer

0 on success.

data.skill_id

string

Skill identifier for this candidate. GET returns the reserved ID even before saving.

data.workspace_id

string

Workspace where the skill is saved.

data.agent_id

string

Target agent that owns the original candidate, not the operator.

data.bound

boolean

Whether the requested binding step completed in this call. bind_current=false returns false without unbinding anything. Reread with GET for current state.

Interpret the result

bind_current=false does not unbind an existing skill. Reread GET for current binding state. With bind_current=true, binding can fail after the skill has been saved; an error does not mean saving was rolled back. For package-managed agents, binding may load a new package version rather than merely write one binding reference.

See saving, binding, and recovery, actual errors and environments, and AI Studio.

Last updated on