Execute skills

Submit a skill run request. The successful response is 202 Accepted, which only means that the request has been accepted, but does not mean that the skill has been executed.

POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/skills/{skill_id}/execute

Before you call

First query skill details] to confirm that the skill is active. Prepare the personal access token, target workspace ID, and skill ID that have access to the target workspace.

The example below uses:

• $AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.

• $WORKSPACE_ID: Execution workspace ID, passed through X-Workspace-ID Header.

• $SKILL_ID: ID of the skill to be performed.

Provide at least one of message, parts, variables, or resource_refs. Only skills in the active state can be executed. Execution also requires valid authenticated roles and runtime access authorization.

Request example

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/skills/$SKILL_ID/execute" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "请总结这段内容。",
    "idempotency_key": "<IDEMPOTENCY_KEY>"
  }'

Path parameters

Parameters	Type	Is it required	Description
workspace_id	string	Yes	Execution workspace ID.
skill_id	string	Yes	The skill ID to execute.

Query parameters

Parameters	Type	Is it required	Description
skill_workspace_id	string	No	The workspace to which the skill belongs; can only be the current workspace or system. If it is not provided, check the current workspace first, and then check the system skills.

Request body

Field	Type	Is it required	Description
agent_id	string	No	Optional execution agent ID. When specified, the agent must be active and have the current skill bound.
context_id	string	No	Context ID and text input.
message	string	No	Context ID and text input.
parts	array	No	Structured input fragment.
variables	object	No	Skill variables and parameters.
parameters	object	No	Skill variables and parameters.
resource_refs	array	No	Resource reference. Each must contain type and contain at least id or uri; can contain role, version, and config.
idempotency_key	string	No	Idempotent key.
metadata	object	No	Extended metadata. Variables, parameters, input fragments, and metadata cannot contain keys or run session references.

Successful response

Returns 202 on success. Use runtime_task_id or runtime_task_url to track subsequent run status and results (field only appears when runtime returns).

{
  "code": 0,
  "data": {
    "id": "exec_01",
    "workspace_id": "ws_01",
    "skill_id": "skill_01",
    "skill_version": 2,
    "runtime_task_id": "task_01",
    "runtime_task_url": "/runtime/tasks/task_01",
    "status": "accepted",
    "accepted_at": "2026-01-02T15:04:05Z"
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.id	string	Execution record ID, execution workspace, and skill ID.
data.workspace_id	string	Execution record ID, execution workspace, and skill ID.
data.skill_id	string	Execution record ID, execution workspace, and skill ID.
data.skill_version	integer	The skill version used in this submission.
data.agent_id	string	The associated agent and context; not returned if not provided.
data.context_id	string	The associated agent and context; not returned if not provided.
data.runtime_task_id	string	Runtime task ID and query address; returned when available.
data.runtime_task_url	string	Runtime task ID and query address; returned when available.
data.status	string	The current acceptance status, does not mean that the operation has been completed.
data.metadata	object	Metadata returned at runtime; returned when available.
data.accepted_at	string	Request processing time, using RFC 3339 format.

Error response

{
  "code": 2,
  "message": "<错误信息>"
}

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	The input is empty, the resource reference is invalid, the skill is not activated, or the specified agent does not have the skill bound to it.	Complete inputs, use active skills, and check resource and agent bindings.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
403	7（FORBIDDEN）	Valid role or runtime access is not authorized.	Check workspace roles and runtime usage permissions.
404	3（NOT_FOUND）	This skill does not exist in the current or rollback system directories.	Check skill ID and skill_workspace_id.
503	15（UNAVAILABLE）	Skill execution submitter, runtime access or authorization dependencies are not currently available.	Try again later.

Follow-up operations

After the call is completed, if you need to check the configuration, Query skill details.

Last updated on Sep 3, 2026