<span id="按显式工作流版本创建-worker-任务"></span>

# Create a Worker task using an explicit workflow version

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

`POST /workspaces/{id}/tasks` is a Worker compatibility endpoint calling the shared workflow execution service. Exactly one nonempty `X-Workspace-ID` must match the path workspace. It creates neither automation rules nor schedules.

<span id="请求体"></span>

## Request body

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```json
{
  "task": {
    "name": "sample-run",
    "workflow_version_id": "version-example",
    "data": "{\"text\":\"sample\"}",
    "vars": "{}"
  }
}
```

:::::
:::::{tab-item} Parameters

| Fields | Type | Required | Description |
| --- | --- | --- | --- |
| `task` | object | Yes | Object described below |
| `task.name` | string | Yes | The handler requires nonempty input; no global uniqueness or surrounding-whitespace rules are implied |
| `task.workflow_version_id` | string | Yes | Explicit published version ID in the current workspace, not a workflow application ID |
| `task.data` | string | No | Encoded JSON object string. Omitted/blank means an empty object. Arrays, null, and invalid JSON are rejected |
| `task.vars` | string | No | Also an encoded JSON object string, not a direct JSON object |

The body permits one complete JSON value and rejects unknown fields. cron_expression, transient, trace, or other extra fields in the body/task trigger the strict DTO unknown-field rejection. Do not describe unknown fields as ignored.

:::::
::::::
:::::::

<span id="执行条件与副作用"></span>

## Execution conditions and side effects

The version must resolve to exactly one workflow application with a deployment definition and latest-version reference. The target version must belong to that definition, be published, and have nonempty workflow content. Suspended/disabled applications reject execution. Dynamic-service versions still validate the input schema.

The permission boundary resolves application/resource facts, checks the principal, authorizes, and injects the effective role. Selecting a task name and version uses one_shot delivery. Even a Cron application creates an independent single-run child execution rather than creating/replacing a schedule. Full resource discovery and runtime policy still require review; one service test does not establish authorization of every Catalog dependency.

The shared execution chain prepares Mowl task/case, persists execution and lineage in a transaction, and reads them back. It wakes execution only after commit. A wake-up failure may occur after records have committed. Query existing runs before resubmitting. There is no request idempotency key or guaranteed retry deduplication.

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "task": {
    "id": "worker-task-example",
    "name": "sample-run",
    "workflow_version_id": "version-example",
    "workflow_execution_id": "execution-example"
  }
}
```

:::::
:::::{tab-item} Fields

HTTP 200 returns `task` directly, without an outer code/msg/data envelope:



| Field | Type | Subsequent use |
| --- | --- | --- |
| `task.id` | string | Mowl/Worker task ID, not an agent authoring task ID |
| `task.name` | string | Requested task name |
| `task.workflow_version_id` | string | Requested explicit version ID |
| `task.workflow_execution_id` | string | Product workflow execution ID for execution details and results |

There is no response state field. Worker protobuf zero values or client defaults do not prove running, completion, or successful output. Common parameter and undeployed errors return 400/ErrParamInvalid; missing workspace returns 400/ErrWorkspaceRequired. Other authorization, resource, execution-identity, dependency, storage, and wake-up errors follow shared workflow mappings.

:::::
::::::
:::::::
