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.

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

Preparation before calling

Generate and inspect a workflow candidate from a completed task. It must belong to the current workspace and caller.

Prepare a personal access token with workflow creation permission in the target workspace and the 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.

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.

{
  "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.

{
  "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.

Last updated on Sep 15, 2026