Guest Machines
API referenceWorkflows

Respond to a workflow step review

POST/api/v1/workflows/runs/{run_id}/reviews/{review_id}/respond

Approve the completed result and continue, revise an agent step with feedback while retaining its prior result, or replace the remaining plan and continue.

Revise requires feedback and is supported for agent steps only. Every prior attempt and review remains in history.

Replan accepts a nested plan change using the same request_id and expected_plan_version. It may instead accept a newer plan that the run initiator prepared through the plan-edit operation.

An accepted response resumes the run asynchronously. If it has not resumed, retry the same response with the same request_id.

Required access

Credentials: delegated token, user session, user API key

User API keys use the owner’s current permissions, subject to any key restrictions. Capability scopes below apply to automation account keys and delegated tokens.

Scope: workflows:read, runs:edit

Only the exact active member named by the pending review may respond. Automation accounts cannot attest as a person. A reviewer may submit a structured replan: its steps run with the original runner's current authority, and both the reviewer and the original runner must be able to run every step it writes.

Authorization

AuthorizationBearer <token>

A user-owned key prefixed gsmc_uk_, bound to one organization. It follows its owner's current membership, role and resource permissions, optionally restricted to read-only access. No X-Org-Id header is needed; a conflicting organization is rejected. Credential creation, personal connection setup and human attestations require a signed-in session. Runs are private to the calling user; sharing an agent grants access to your own personal memory of it, never to the agent's own memory.

In: header

Path Parameters

run_id*Run Id
review_id*Review Id
Formatuuid

Header Parameters

X-Org-Id?|

Selects the active organization for a direct user session that has more than one membership. Automation account keys and delegated tokens are each bound to one organization and ignore it.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Resolve one exact post-step review.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/workflows/runs/0/reviews/497f6eca-6276-4993-bfeb-53cbbbba6f08/respond" \  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "expected_plan_version": 1,    "request_id": "36e4cd2b-801f-44f4-a86c-9335755bf4fb",    "decision": "revise",    "feedback": "Correct the unsupported revenue assumption."  }'
{  "version": 0,  "definition": {    "steps": [      {        "key": "string",        "name": "string",        "run_if": "string",        "on_error": {          "action": "continue",          "max_attempts": 3,          "backoff": "exponential",          "backoff_delay_seconds": 1,          "fallback_agent_id": "ea74c5a8-d285-4937-959b-1e318178db0b"        },        "limits": {          "max_duration_seconds": 1        },        "files": [          {            "source": {              "kind": "input",              "input_alias": "string",              "step": "string",              "selector": {                "file_name": "string",                "primary": true              },              "iteration": 1            },            "target_alias": "string",            "required": true          }        ],        "kind": "agent",        "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",        "instruction": "string",        "input": {},        "responder_user_id": "0f708b4a-8382-4a27-a010-8a6f70d21699"      }    ],    "loop": {      "from_step": "string",      "until": "string",      "max_iterations": 3    },    "output": null,    "review_after_steps": false  },  "versions": [    {      "version": 0,      "parent_version": 0,      "operation": "append",      "review_id": "30a1a187-4023-4077-a8f3-f5ec83d3ab6b",      "reason": "string",      "created_by_user_id": "209f54c4-4c33-43bc-9c6a-ef4c65ad7473",      "created_by_service_principal_id": "632f5796-7464-468a-9dc3-9734cb79d1af",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "reviews": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "workflow_run_step_id": 0,      "step_key": "string",      "step_index": 0,      "step_kind": "agent",      "review_round": 0,      "plan_version": 0,      "reviewer_user_id": "f624c54b-252a-4ffd-965c-527b0a3ed08d",      "status": "cancelled",      "decision": "approve",      "feedback": "string",      "applied_plan_version": 0,      "responded_by_user_id": "0cddcf68-90fa-4e26-8c15-e4f34c3446b0",      "responded_by_service_principal_id": "6a6dea7e-e2f3-4659-9fd3-ef77f51e5c93",      "created_at": "2019-08-24T14:15:22Z",      "resolved_at": "2019-08-24T14:15:22Z"    }  ],  "review_count": 0,  "reviews_truncated": false,  "pending_review": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "workflow_run_step_id": 0,    "step_key": "string",    "step_index": 0,    "step_kind": "agent",    "review_round": 0,    "plan_version": 0,    "reviewer_user_id": "f624c54b-252a-4ffd-965c-527b0a3ed08d",    "created_at": "2019-08-24T14:15:22Z"  },  "can_respond": false,  "can_edit_plan": false}

Retrieve a workflow run plan version GET

Retrieve the complete definition for one immutable plan version. Version snapshots are fetched individually so the base plan response stays compact.

Rerun a workflow run from a step POST

Repeat a failed or cancelled workflow run from one of its steps. The new run reuses the results of the steps before `from_step` and runs the rest again, as the caller. It uses the revision the original run used unless `use_latest_revision` is set.