# List workflow versions

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

Lists all version records under the specified workflow definition across `draft`, `published`, and `deprecated` statuses. Items are returned in ascending `Version` order (ties broken by `ID`) without pagination.

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

## Before you begin

1. Prepare a [personal access token](../../../../../../guides/genesis/api-keys.md#creating-and-managing-personal-access-tokens) with workflow version read permission and the [target workspace ID](../../../../../../guides/ai-studio/resource-center/workspace.md#copy-the-workspace-id).
2. Call [List workflows](../list-workflows.md) to obtain the target workflow ID.

## Request parameters

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

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl "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"
```

:::::
:::::{tab-item} Parameters

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `workflow_id` | string | Yes | Target workflow ID, obtained from [List workflows](../list-workflows.md). |

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

## Successful response

Returns HTTP `200` and the `data.items` version array; if the workflow definition has no version records yet, `data.items` is `[]`. Version object keys use PascalCase on the JSON wire.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "items": [
      {
        "ID": "ver-001",
        "WorkspaceID": "ws-001",
        "UserID": "user-001",
        "WorkflowDefinitionID": "def-001",
        "Version": 1,
        "WorkflowJSON": "{\"name\":\"daily-import\",\"nodes\":[]}",
        "Status": "published",
        "CreatedBy": "user-001",
        "CreatedAt": "2026-10-14T08:00:00Z",
        "PublishedAt": "2026-10-14T08:05:00Z",
        "Type": 1,
        "InputSchema": "",
        "OutputSchema": "",
        "ResultMode": 0,
        "Description": "Initial published version",
        "RuntimeSpecJSON": ""
      },
      {
        "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": ""
      }
    ]
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` when the request succeeds. |
| `msg` | string | Result message; `OK` when the request succeeds. |
| `data` | object | Payload returned by this query. |
| `data.items` | array of object | Workflow version list ordered by ascending `Version`. |
| `data.items[].ID` | string | Workflow version ID, used in [Get workflow version details](get-workflow-version.md), [Publish a workflow version](publish-workflow-version.md), [Deprecate a workflow version](deprecate-workflow-version.md), or [Delete a workflow version](delete-workflow-version.md). |
| `data.items[].WorkspaceID` | string | Workspace ID that owns the version. |
| `data.items[].UserID` | string | User ID of the workflow owner. |
| `data.items[].WorkflowDefinitionID` | string | Workflow definition ID that owns the version. |
| `data.items[].Version` | integer | Positive integer version number starting from `1`, used in [Get workflow version by number](get-workflow-version-by-number.md). |
| `data.items[].WorkflowJSON` | string | Saved workflow definition JSON string. |
| `data.items[].Status` | string | Version status: `draft`, `published`, or `deprecated`. |
| `data.items[].CreatedBy` | string | User ID of the actor who created the version. |
| `data.items[].CreatedAt` | string | Version creation time in RFC 3339 format. |
| `data.items[].PublishedAt` | string | Version publication time in RFC 3339 format; `0001-01-01T00:00:00Z` when unpublished. |
| `data.items[].Type` | integer | Version type code: `1` for workflow, `2` for dynamic API service. |
| `data.items[].InputSchema` | string | Saved input schema JSON string; `""` when unset. |
| `data.items[].OutputSchema` | string | Saved output schema JSON string; `""` when unset. |
| `data.items[].ResultMode` | integer | Result mode code: `0` for unspecified, `1` for single response, `2` for streaming. |
| `data.items[].Description` | string | Version description; `""` when unset. |
| `data.items[].RuntimeSpecJSON` | string | Saved runtime specification JSON string; `""` when unset. |

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

## Error response

Returns `404` (`ErrNotFound`) when the workflow does not exist or has no bound workflow definition, or `403` (`ErrForbidden`) when the current identity lacks read permission.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "ErrNotFound",
  "msg": "Not Found"
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Error code, such as `ErrWorkspaceRequired`, `ErrForbidden`, `ErrNotFound`, or `ErrServer`. |
| `msg` | string | Human-readable error message. |

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