Create a workflow version

Creates a new draft (draft) version for a workflow, incrementing the version number by 1 from the workflow definition’s latest version. This operation saves the draft version record without publishing it, updating trigger bindings, or starting a job run; call Publish a workflow version after verification to publish it.

POST https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/{workflow_id}/versions

Before you begin

  1. Prepare a personal access token with workflow version creation permission and the target workspace ID.

  2. Call Get workflow details to verify that the target workflow has a bound workflow definition (moi_workflow_def_id is non-empty) and that source_type is not agent_automation_task.

Request parameters

Replace $AI_STUDIO_API_KEY, $WORKSPACE_ID, and $WORKFLOW_ID with actual values, and pass a serialized valid JSON string in workflow.

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/$WORKFLOW_ID/versions" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "{\"name\":\"daily-import\",\"nodes\":[]}",
    "description": "Add input field validation"
  }'

Path parameters

Parameter

Type

Required

Description

workflow_id

string

Yes

Target workflow ID, obtained from List workflows.

Body parameters

Parameter

Type

Required

Description

workflow

string

Yes

Serialized workflow definition JSON string; must be non-empty valid JSON. Object-valued __input__ or __save__ maps are normalized into JSON-encoded strings before persistence.

description

string

No

Version description; leading and trailing whitespace are trimmed before saving.

Successful response

Returns HTTP 200 and the newly created draft version object. Version object keys use PascalCase on the JSON wire.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "ID": "ver-002",
    "WorkspaceID": "ws-001",
    "UserID": "user-001",
    "WorkflowDefinitionID": "def-001",
    "Version": 2,
    "WorkflowJSON": "{\"name\":\"daily-import\",\"nodes\":[]}",
    "Status": "draft",
    "CreatedBy": "user-001",
    "CreatedAt": "2026-10-14T09:00:00Z",
    "PublishedAt": "0001-01-01T00:00:00Z",
    "Type": 1,
    "InputSchema": "",
    "OutputSchema": "",
    "ResultMode": 0,
    "Description": "Add input field validation",
    "RuntimeSpecJSON": ""
  }
}

Field

Type

Description

code

string

OK when the request succeeds.

msg

string

Result message; OK when the request succeeds.

data

object

Newly created workflow version object.

data.ID

string

Workflow version ID, used in Get workflow version details, Publish a workflow version, or Delete a workflow version.

data.WorkspaceID

string

Workspace ID that owns the version.

data.UserID

string

User ID of the workflow owner.

data.WorkflowDefinitionID

string

Workflow definition ID that owns the version.

data.Version

integer

Positive integer version number starting from 1.

data.WorkflowJSON

string

Saved workflow definition JSON string.

data.Status

string

Version status; fixed to draft upon creation (enum values: draft, published, deprecated).

data.CreatedBy

string

User ID of the actor who created the version.

data.CreatedAt

string

Version creation time in RFC 3339 format.

data.PublishedAt

string

Version publication time in RFC 3339 format; retains the zero time 0001-01-01T00:00:00Z while in draft status.

data.Type

integer

Version type code: 1 for workflow, 2 for dynamic API service; fixed to 1 when created by this endpoint.

data.InputSchema

string

Saved input schema JSON string; "" when unset.

data.OutputSchema

string

Saved output schema JSON string; "" when unset.

data.ResultMode

integer

Result mode code: 0 for unspecified, 1 for single response, 2 for streaming.

data.Description

string

Version description; "" when omitted.

data.RuntimeSpecJSON

string

Saved runtime specification JSON string; "" when unset.

Error response

Returns 400 (ErrParamInvalid) when workflow is not valid JSON, 404 (ErrNotFound) when the workflow does not exist or has no bound workflow definition, and 409 (ErrWorkflowUpdateManagedByAutomation) when the workflow is managed by an agent automation task. Submitting an empty workflow string also fails because version JSON is required.

{
  "code": "ErrParamInvalid",
  "msg": "Bad Request"
}

Field

Type

Description

code

string

Error code, such as ErrParamInvalid, ErrWorkspaceRequired, ErrForbidden, ErrNotFound, ErrWorkflowUpdateManagedByAutomation, or ErrServer.

msg

string

Human-readable error message.

Last updated on