Create workflow

Create a workflow definition in the current workspace. Creating a workflow does not start a job automatically. dsl_yaml must contain a deployable root and at least one valid node; an empty chain: [] example cannot be deployed. Deploy naturally generated workflows using an accepted candidate reference.

POST https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments

Preparation before calling

Prepare a personal access token with permission to create workflows and a target workspace ID. For manual authoring, prepare workflow DSL; for natural-language authoring, prepare an accepted workflow candidate.

Request body

Replace $AI_STUDIO_API_KEY, $WORKSPACE_ID, and the workflow name and DSL in the examples with actual values.

Input examples

One-time run

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "daily-import",
    "dsl_yaml": "workflow:\\n  name: daily-import\\n  root: main\\nroot:\\n  chain: []\\n",
    "execution_mode": "one_shot"
  }'

Dynamic service

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "order-query-service",
    "dsl_yaml": "workflow:\\n  name: order-query-service\\n  root: main\\nroot:\\n  chain: []\\n",
    "execution_mode": "dynamic_service",
    "dynamic_service": {
      "service_name": "order-query-service"
    }
  }'

Scheduled run

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "daily-import",
    "dsl_yaml": "workflow:\\n  name: daily-import\\n  root: main\\nroot:\\n  chain: []\\n",
    "execution_mode": "cron",
    "cron_expression": "0 2 * * *"
  }'

Volume trigger

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "volume-import",
    "dsl_yaml": "workflow:\\n  name: volume-import\\n  root: main\\nroot:\\n  chain: []\\n",
    "execution_mode": "volume_trigger",
    "volume_trigger": {
      "volume_id": 1001,
      "enabled": true
    }
  }'

Parameter reference

Creating a workflow requires name. Omitting source_type selects manual_dsl, which requires dsl_yaml. For a natural-language candidate, set source_type=nl2dsl and provide the accepted candidate_ref, without dsl_yaml. Do not send workflow_id or runtime_context when creating a workflow; use Update workflow to modify an existing workflow.

One-time run

Parameter	Type	Required	Description
name	string	Yes	Workflow name.
description	string	No	Workflow description.
dsl_yaml	string	Conditional	Required for manual DSL; omit for natural-language candidate deployment.
execution_mode	string	No	Execution mode. Defaults to one_shot.
source_type	string	No	manual_dsl (default) or nl2dsl. DSL using a Memory Governance WorkItem must use memory_governance.
candidate_ref	object	For nl2dsl	Accepted generation candidate reference.
candidate_ref.task_id	string	For nl2dsl	A2A generation task ID.
candidate_ref.artifact_id	string	For nl2dsl	Candidate artifact ID from the same task.
runtime_fields	object	No	Runtime input form configuration.
runtime_layout	object	No	Runtime input form layout configuration.
default_values	object	No	Default values for the runtime input form.
design_graph	object	No	Workflow design-graph configuration.
compute_resource_id	string	No	Associated compute resource ID.

Dynamic service

Parameter	Type	Required	Description
name	string	Yes	Workflow name.
dsl_yaml	string	Conditional	Required for manual DSL; omit for natural-language candidate deployment.
execution_mode	string	Yes	Set to dynamic_service.
dynamic_service	object	Yes	Dynamic-service configuration.
dynamic_service.service_name	string	No	Dynamic service name.
dynamic_service.input_schema	string	No	Schema for dynamic-service input.
dynamic_service.output_schema	string	No	Schema for dynamic-service output.
dynamic_service.result_mode	string	No	Result mode for the dynamic service.
dynamic_service.runtime_spec_json	string	No	JSON text of runtime configuration for the dynamic service.

For other optional fields, see the One-time run tab.

Scheduled run

Parameter	Type	Required	Description
name	string	Yes	Workflow name.
dsl_yaml	string	Conditional	Required for manual DSL; omit for natural-language candidate deployment.
execution_mode	string	Yes	Set to cron.
cron_expression	string	Yes	Cron expression.

For other optional fields, see the One-time run tab.

Volume trigger

Parameter	Type	Required	Description
name	string	Yes	Workflow name.
dsl_yaml	string	Conditional	Required for manual DSL; omit for natural-language candidate deployment.
execution_mode	string	Yes	Set to volume_trigger.
volume_trigger	object	No	Volume-trigger configuration. volume_id is required when the runtime input form does not provide a volume ID.
volume_trigger.volume_id	integer	Conditional	Required when the runtime input form does not provide a volume ID.
volume_trigger.enabled	boolean	No	Whether to enable the volume trigger.
volume_trigger.auto_dispatch_enabled	boolean	No	Whether to automatically dispatch volume-triggered runs.
volume_trigger.vars_json	string	No	JSON text of variables used by the volume trigger.
volume_trigger.max_concurrency	integer	No	Maximum concurrency for volume-triggered runs.

For other optional fields, see the One-time run tab.

Natural-language candidate deployment

This example requires a valid workflow candidate that has already been accepted. Save data.candidate_ref.task_id and data.candidate_ref.artifact_id from the acceptance response as $TASK_ID and $ARTIFACT_ID.

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "ticket-analysis",
    "source_type": "nl2dsl",
    "candidate_ref": {
      "task_id": "'"$TASK_ID"'",
      "artifact_id": "'"$ARTIFACT_ID"'"
    },
    "execution_mode": "one_shot",
    "default_values": {
      "text": "Text to process"
    }
  }'

The server reads the definition from the candidate. Do not submit dsl_yaml, runtime_fields, runtime_layout, or design_graph. To change nodes or the form, generate and accept a revised candidate.

default_values supplies defaults for the candidate’s runtime form; names and types must match that form. A one_shot deployment requires values for all required runtime fields at deployment time. Missing values prevent deployment; they cannot be deferred until job startup. The example assumes a required string field text; replace it according to the actual runtime_fields.fields. Dynamic-service invocation inputs are supplied per call and are excluded from this deployment completeness check.

The candidate must belong to the current workspace and caller, come from a completed task, and have a matching server-side acceptance record. Deploying an unaccepted candidate returns HTTP 409 with workflow_candidate_not_accepted. Arbitrary YAML, candidate objects, or invented IDs cannot replace the reference.

Successful response

Returns 200 on success. The service saves the workflow definition but does not start a job automatically. Save data.workflow.id for viewing, updating, or starting the workflow.

Response example

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workflow": {
      "id": "wf-001",
      "name": "daily-import",
      "source_type": "manual_dsl",
      "execution_mode": "one_shot",
      "draft_id": "draft-001",
      "status": "ready"
    },
    "deployment": {
      "workflow_app_id": "wf-001",
      "workflow_def_id": "def-001",
      "workflow_version_id": "ver-001",
      "workflow_name": "daily-import",
      "version": 1,
      "execution_mode": "one_shot"
    }
  }
}

Field reference

Common fields

Field	Type	Description
code	string	OK when successful.
msg	string	OK when successful.
data	object	Response data.

Workflow summary

data.workflow is the summary of the created workflow.

Field	Type	Description
id	string	Workflow ID.
name	string	Workflow name.
source_type	string	Workflow source type.
execution_mode	string	Saved execution mode.
draft_id	string	Workflow draft ID.
status	string	Current workflow status.

Deployment details

data.deployment contains the published workflow version and execution-mode resource.

Field	Type	Description
workflow_app_id	string	Workflow application ID.
workflow_def_id	string	Workflow definition ID.
workflow_version_id	string	Workflow version ID.
workflow_name	string	Workflow name.
version	integer	Workflow version number.
execution_mode	string	Published execution mode.

Conditional fields

Field	Type	Returned when
data.workflow.cron_expression	string	The workflow is scheduled.
data.workflow.candidate_id	string	A candidate version exists.
data.deployment.previous_workflow_version_id	string	Updating an existing workflow version.
data.deployment.disabled_cron_task_ids	array of string	Replacing a scheduled task.
data.deployment.volume_trigger	object	The workflow uses a volume trigger.
data.deployment.cron_task	object	The workflow is scheduled.
data.deployment.dynamic_service	object	The workflow uses a dynamic service.
data.warnings	array of string	Deployment produces warnings.

Error response

Response example

{
  "code": "ErrParamInvalid",
  "msg": "Request parameters are invalid",
  "data": null
}

Field reference

Field	Type	Description
code	string	Error code.
msg	string	Error description.
data	null	Empty on error.

Follow-up operations

Save data.workflow.id. To verify the created workflow, View workflow details; to run it immediately, Start workflow job.

Last updated on Oct 19, 2026