创建工作流版本

为指定工作流创建新的草稿(draft)版本,版本号按当前工作流定义的最新版本号递增 1。该操作仅保存草稿版本记录,不会自动发布版本、更新触发配置或启动作业运行;确认无误后可调用发布工作流版本将其发布。

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

调用前准备

  1. 准备具有工作流版本创建权限的个人访问令牌和目标工作区 ID。

  2. 先调用查询工作流详情,确认目标工作流已关联工作流定义(moi_workflow_def_id 非空)且 source_type 不为 agent_automation_task。

请求参数

将 $AI_STUDIO_API_KEY、$WORKSPACE_ID 和 $WORKFLOW_ID 替换为实际值,并在 workflow 字段中传入序列化后的合法 JSON 字符串。

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": "新增输入字段校验"
  }'

路径参数

参数

类型

是否必填

说明

workflow_id

string

是

目标工作流 ID,可从查询工作流列表取得。

请求体参数

参数

类型

是否必填

说明

workflow

string

是

序列化后的工作流定义 JSON 字符串,不能为空且必须为合法 JSON。若其中 __input__ 或 __save__ 为对象值,服务端持久化时会将其规范化编码为 JSON 字符串。

description

string

否

版本说明,服务端保存时会去除首尾空白。

成功响应

返回 HTTP 200 及新建的草稿版本对象。版本对象的字段名在 JSON 响应中保持 PascalCase 大小写。

{
  "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": "新增输入字段校验",
    "RuntimeSpecJSON": ""
  }
}

字段

类型

说明

code

string

请求处理成功时为 OK。

msg

string

请求处理结果说明,成功时为 OK。

data

object

新建的工作流版本对象。

data.ID

string

工作流版本 ID,后续可用于查询工作流版本详情、发布工作流版本或删除工作流版本。

data.WorkspaceID

string

版本所属工作区 ID。

data.UserID

string

工作流所有者用户 ID。

data.WorkflowDefinitionID

string

版本所属的工作流定义 ID。

data.Version

integer

正整数版本号,从 1 开始递增。

data.WorkflowJSON

string

保存的工作流定义 JSON 字符串。

data.Status

string

版本状态,新建时固定为 draft(完整枚举为 draft、published、deprecated)。

data.CreatedBy

string

创建该版本的用户 ID。

data.CreatedAt

string

版本创建时间,采用 RFC 3339 格式。

data.PublishedAt

string

版本发布时间,采用 RFC 3339 格式;草稿状态下保留零值时间 0001-01-01T00:00:00Z。

data.Type

integer

版本类型编码:1 表示工作流,2 表示动态 API 服务;本接口创建时固定为 1。

data.InputSchema

string

保存的输入 Schema JSON 字符串;未设置时为空字符串 ""。

data.OutputSchema

string

保存的输出 Schema JSON 字符串;未设置时为空字符串 ""。

data.ResultMode

integer

结果模式编码:0 表示未指定,1 表示单次返回,2 表示流式返回。

data.Description

string

版本说明;未提供时为空字符串 ""。

data.RuntimeSpecJSON

string

保存的运行规范 JSON 字符串;未设置时为空字符串 ""。

错误响应

workflow 不是合法 JSON 时返回 400(ErrParamInvalid);工作流不存在或未绑定工作流定义时返回 404(ErrNotFound);工作流由智能体自动化任务托管时返回 409(ErrWorkflowUpdateManagedByAutomation);workflow 为空字符串时会因缺少版本内容而失败。

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

字段

类型

说明

code

string

错误代码,例如 ErrParamInvalid、ErrWorkspaceRequired、ErrForbidden、ErrNotFound、ErrWorkflowUpdateManagedByAutomation 或 ErrServer。

msg

string

可读错误信息。

最后更新于