# 创建工作流版本

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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

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

## 调用前准备

1. 准备具有工作流版本创建权限的[个人访问令牌](../../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)和[目标工作区 ID](../../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。
2. 先调用[查询工作流详情](../get-workflow.md)，确认目标工作流已关联工作流定义（`moi_workflow_def_id` 非空）且 `source_type` 不为 `agent_automation_task`。

## 请求参数

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

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

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

:::::
:::::{tab-item} 参数说明

### 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `workflow_id` | string | 是 | 目标工作流 ID，可从[查询工作流列表](../list-workflows.md)取得。 |

### 请求体参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `workflow` | string | 是 | 序列化后的工作流定义 JSON 字符串，不能为空且必须为合法 JSON。若其中 `__input__` 或 `__save__` 为对象值，服务端持久化时会将其规范化编码为 JSON 字符串。 |
| `description` | string | 否 | 版本说明，服务端保存时会去除首尾空白。 |

:::::
::::::
:::::::

## 成功响应

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

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "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": ""
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 请求处理成功时为 `OK`。 |
| `msg` | string | 请求处理结果说明，成功时为 `OK`。 |
| `data` | object | 新建的工作流版本对象。 |
| `data.ID` | string | 工作流版本 ID，后续可用于[查询工作流版本详情](get-workflow-version.md)、[发布工作流版本](publish-workflow-version.md)或[删除工作流版本](delete-workflow-version.md)。 |
| `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` 为空字符串时会因缺少版本内容而失败。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 错误代码，例如 `ErrParamInvalid`、`ErrWorkspaceRequired`、`ErrForbidden`、`ErrNotFound`、`ErrWorkflowUpdateManagedByAutomation` 或 `ErrServer`。 |
| `msg` | string | 可读错误信息。 |

:::::
::::::
:::::::
