Create a Worker task using an explicit workflow version

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.

Request body

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

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.

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.

Successful response

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

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.

Last updated on