<span id="恢复历史工作流候选为新提案"></span>

# Restore a historical workflow candidate as a new proposal

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

Restore a compiled historical candidate as a new pending plan. See [Common information](objects.md) for objects, variables, and environment boundaries.

```text
POST https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-candidates/restore
```

<span id="调用前准备"></span>

## Before you call this API

Prepare a personal access token with workflow operation privileges for the target workspace. Use conversations, tasks, and artifacts from the same environment. Install jq and set example variables.

<span id="请求体"></span>

## Request body

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

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-candidates/restore" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg v0 "$WORKFLOW_CONTEXT_ID" --arg v1 "$RESTORE_REQUEST_ID" --arg v2 "$RESTORE_TASK_ID" --arg v3 "$RESTORE_ARTIFACT_ID" '{"context_id":$v0,"request_id":$v1,"candidate_ref":{"task_id":$v2,"artifact_id":$v3}}')"
```

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

Select a valid compiled candidate from a completed task in the same conversation; failed source records cannot be restored. The server appends a new artifact and pending proposal under the source task, resets test_status to not_run, and preserves restored_from. task_id may stay unchanged, but artifact_id and proposal_id change; use new returned references afterward. Recovery neither accepts, publishes, nor overwrites saved applications and preserves original target binding. The same request identifier and selection may replay. Always retain both; do not rely on conflicts when reusing an identifier for different artifacts of one task. New proposals expire24 hours after creation.

| Fields | Type | Required | Description |
| --- | --- | --- | --- |
| `context_id` | string | Yes | Generation conversation ID matching the source task. |
| `request_id` | string | Yes | Stable identifier saved for this recovery; change it when changing source. |
| `candidate_ref` | object | Yes | Complete reference retained from the same history entry or task artifact. |
| `candidate_ref.task_id` | string | Yes | Source task ID, not the workflow application ID. |
| `candidate_ref.artifact_id` | string | Yes | Candidate artifact ID within that task. |

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

<span id="成功响应"></span>

## Successful response

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "workflow_restore_b5c5286c71c60c1371946c8568e7f916",
    "candidate_ref": {
      "task_id": "task-1",
      "artifact_id": "workflow_candidate_b5c5286c71c60c1371946c8568e7f916"
    },
    "candidate": {
      "ok": true,
      "candidate_id": "workflow_candidate_b5c5286c71c60c1371946c8568e7f916",
      "proposal_id": "workflow_restore_b5c5286c71c60c1371946c8568e7f916_proposal",
      "summary": "candidate",
      "message": "waiting for explicit acceptance",
      "workflow": {
        "name": "candidate",
        "root": "root",
        "nets": {
          "root": {
            "nodes": {
              "__end": {
                "id": "mowl:end",
                "in_connector": {
                  "type": "simple",
                  "nodes": [
                    "__start"
                  ]
                }
              },
              "__start": {
                "id": "mowl:start",
                "out_connector": {
                  "type": "simple",
                  "nodes": [
                    "__end"
                  ]
                }
              }
            }
          }
        }
      },
      "runtime_fields": {
        "fields": [
          {
            "field_id": "source_ref",
            "label": "",
            "widget": ""
          },
          {
            "field_id": "prompt",
            "label": "",
            "widget": ""
          }
        ]
      },
      "catalog_revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "snapshot_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "syntax_version": "workflow-go/v1",
      "compiler_version": "workflow-go-compiler/v2",
      "source_code": "package workflow\nfunc Build() {}\n\n",
      "restored_from": {
        "task_id": "task-1",
        "artifact_id": "workflow_candidate_beae4775c142fe6e5dccdced956154fe"
      },
      "test_status": "not_run"
    },
    "status": "pending",
    "created_at": "2026-08-31T01:00:00Z"
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response information. |
| `data` | object | Result of this operation. |
| `data.id` | string | New history event ID. |
| `data.candidate_ref` | object | New candidate artifact reference in the source task. |
| `data.candidate` | object | New candidate snapshot. |
| `data.candidate.proposal_id` | string | New pending proposal ID. |
| `data.candidate.restored_from` | object | Original source task/artifact reference. |
| `data.candidate.test_status` | string | not_run on initial recovery; retest before confirmation. |
| `data.status` | string | pending initially; replay returns persisted proposal state. |
| `data.created_at` | string | Creation time. |

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

<span id="错误响应"></span>

## Error response

Handle HTTP status and business fields. History and recovery have dedicated errors; see [Errors and environments](objects.md#错误与环境). Retain identity, source references, and operation identifiers, then check state before proceeding. Do not automatically switch workspace, candidate, or confirmation key.
