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¶
Prepare a personal access token with workflow version creation permission and the target workspace ID.
Call Get workflow details to verify that the target workflow has a bound workflow definition (
moi_workflow_def_idis non-empty) and thatsource_typeis notagent_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 |
|---|---|---|---|
|
string |
Yes |
Target workflow ID, obtained from List workflows. |
Body parameters
Parameter |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Serialized workflow definition JSON string; must be non-empty valid JSON. Object-valued |
|
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 |
|---|---|---|
|
string |
|
|
string |
Result message; |
|
object |
Newly created workflow version object. |
|
string |
Workflow version ID, used in Get workflow version details, Publish a workflow version, or Delete a workflow version. |
|
string |
Workspace ID that owns the version. |
|
string |
User ID of the workflow owner. |
|
string |
Workflow definition ID that owns the version. |
|
integer |
Positive integer version number starting from |
|
string |
Saved workflow definition JSON string. |
|
string |
Version status; fixed to |
|
string |
User ID of the actor who created the version. |
|
string |
Version creation time in RFC 3339 format. |
|
string |
Version publication time in RFC 3339 format; retains the zero time |
|
integer |
Version type code: |
|
string |
Saved input schema JSON string; |
|
string |
Saved output schema JSON string; |
|
integer |
Result mode code: |
|
string |
Version description; |
|
string |
Saved runtime specification JSON string; |
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 |
|---|---|---|
|
string |
Error code, such as |
|
string |
Human-readable error message. |