# 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.

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

## Before you call

First [query skill details](get-skill.md)] 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

```bash
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).

```json
{
  "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

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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](get-skill.md).