Publish a workflow version

Publishes a draft workflow version to published status, records PublishedAt, and deprecates any other published versions under the same workflow definition within the same transaction. Calling this endpoint does not automatically start a workflow run.

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

Before you begin

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

  2. Obtain the target version ID from Create a workflow version or List workflow versions, verify that its Status is draft, and confirm that the workflow is not managed by an agent automation task.

Request parameters

Replace $AI_STUDIO_API_KEY, $WORKSPACE_ID, $WORKFLOW_ID, and $VERSION_ID with actual values.

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/$WORKFLOW_ID/versions/$VERSION_ID/publish" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Path parameters

Parameter

Type

Required

Description

workflow_id

string

Yes

Target workflow ID, obtained from List workflows.

version_id

string

Yes

Draft version ID to publish (Status must be draft), obtained from Create a workflow version or List workflow versions.

Successful response

Returns HTTP 200 and the published workflow version object with Status set to published and PublishedAt set to the publication timestamp. 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": "published",
    "CreatedBy": "user-001",
    "CreatedAt": "2026-10-14T09:00:00Z",
    "PublishedAt": "2026-10-14T09:15: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

Published workflow version object.

data.ID

string

Workflow version ID.

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 after publication; published on success.

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

Timestamp of this publication in RFC 3339 format.

data.Type

integer

Version type code: 1 for workflow, 2 for dynamic API service.

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 unset.

data.RuntimeSpecJSON

string

Saved runtime specification JSON string; "" when unset.

Error response

Returns 404 (ErrNotFound) when the workflow or version does not exist, and 409 (ErrWorkflowUpdateManagedByAutomation) when the workflow is managed by an agent automation task. Calling this endpoint on a version whose Status is already published or deprecated fails because only draft versions can be published.

{
  "code": "ErrWorkflowUpdateManagedByAutomation",
  "msg": "workflow is managed by an automation task; edit the automation task instead"
}

Field

Type

Description

code

string

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

msg

string

Human-readable error message.

Last updated on