---
orphan: true
---

# Accept workflow candidate

Accept a candidate generated and validated by the workflow assistant. This saves the confirmation record needed for deployment; it does not deploy or run a workflow.

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

## Preparation before calling

[Generate and inspect a workflow candidate](build-with-api.md#track-generation-and-inspect-the-candidate) from a completed task. It must belong to the current workspace and caller.

Prepare a [personal access token](../../../../../guides/genesis/api-keys.md) with workflow creation permission in the target workspace and the [workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#copy-a-workspace-id).

## Request example

`$TASK_ID` comes from the generation task's `result.id`; `$ARTIFACT_ID` comes from the candidate artifact's `artifactId` in the same task. `$AI_STUDIO_API_KEY` and `$WORKSPACE_ID` identify the credential and target workspace.

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-candidates/accept" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "candidate_ref": {
      "task_id": "'"$TASK_ID"'",
      "artifact_id": "'"$ARTIFACT_ID"'"
    }
  }'
```

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `candidate_ref` | object | Yes | Server-side candidate reference to accept. |
| `candidate_ref.task_id` | string | Yes | Completed A2A task that generated the candidate. |
| `candidate_ref.artifact_id` | string | Yes | Workflow candidate artifact in that task. |

Submit only the reference. Do not submit candidate content, DSL, a form, canvas data, or `runtime_context`. The server reads and checks the original artifact; a client-created candidate cannot replace it.

## Successful response

Returns HTTP 200 and an acceptance record containing the full candidate. Acceptance does not mean a workflow has been created.

This excerpt shows the reference and acceptance time. The full response also includes `data.candidate`, described below.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "candidate_ref": {
      "task_id": "task_01",
      "artifact_id": "workflow_candidate_01"
    },
    "accepted_at": "2026-09-15T02:00:00Z"
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | Response description. |
| `data.candidate_ref` | object | Accepted candidate reference. |
| `data.candidate_ref.task_id` | string | Generation task ID. |
| `data.candidate_ref.artifact_id` | string | Candidate artifact ID. |
| `data.accepted_at` | string | Server-recorded acceptance time. |
| `data.candidate` | object | Candidate saved by the server. |
| `data.candidate.ok` | boolean | Whether the candidate is valid. |
| `data.candidate.candidate_id` | string | Candidate identifier. |
| `data.candidate.summary` | string | Summary, when available. |
| `data.candidate.message` | string | Description, when available. |
| `data.candidate.workflow` | object | Deployable workflow definition. |
| `data.candidate.runtime_fields` | object | Runtime input form, when configured. |
| `data.candidate.runtime_layout` | object | Form layout, when configured. |
| `data.candidate.diagnostics` | object[] | Compilation diagnostics, when available. |
| `data.candidate.diagnostics[].message` | string | Diagnostic message. |
| `data.candidate.diagnostics[].severity` | string | Severity, when available. |
| `data.candidate.diagnostics[].suggestion` | string | Suggested change, when available. |

`[]` in a field path denotes each array item; after a type it denotes an array. Candidates may also include source, compiler version, digests, and custom operator snapshots. Preserve the original response for inspection; do not resubmit these fields in the deployment request.

## Error response

Error display text may be localized.

```json
{
  "code": "ErrParamInvalid",
  "data": null,
  "msg": "候选 task_id 和 artifact_id 不能为空"
}
```

| HTTP status | Error code | Cause and action |
| --- | --- | --- |
| 400 | `ErrParamInvalid` | Missing reference, invalid candidate, or unsupported fields. Check the task and artifact source and submit only the reference. |
| 409 | `workflow_candidate_not_accepted` | Acceptance state does not satisfy the operation. Check the actual candidate and acceptance record; do not fabricate acceptance state. |
| 500 | `ErrServer` | Server processing failed. Save request time and response for administrator diagnosis. |
| 503 | `ErrServiceUnavailable` | A dependency is unavailable. Restore the service before continuing. |

## Follow-up operations

Use `data.candidate_ref` to [create a workflow with natural-language candidate deployment](create-workflow.md#natural-language-candidate-deployment).