Guest Machines
API referenceWorkflows

Change a workflow run's remaining plan

POST/api/v1/workflows/runs/{run_id}/plan

At a pending completed-step review, append structured steps or replace only the unstarted suffix. Completed results and the original plan remain intact; the request creates a new plan version for this run.

Copy expected_plan_version from the current plan. A 409 means the plan changed; retrieve it again before retrying.

request_id makes the write idempotent. Reusing it with different content is rejected with 409.

An append needs at least one step. Replace-remaining may use an empty list to end after the reviewed step. Omit output to retain the current output template; explicit null clears it.

Required access

Credentials: automation account, 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 person or automation account that initiated the run may prepare a standalone change. Every new target is authorized under that original runner's current authority, never the editor's.

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

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.

A version-fenced edit to the part of a run that has not started.

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/plan" \  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "expected_plan_version": 1,    "request_id": "6b01b954-acde-4ebb-ae32-5b557a5cc225",    "operation": "append",    "steps": [      {        "key": "verify",        "kind": "agent",        "agent_id": "22222222-2222-2222-2222-222222222222"      }    ],    "reason": "Verify the completed draft before publishing."  }'
{  "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 GET

Retrieve the workflow run's current definition, immutable plan-version history, recent step-review history, and any pending post-step review. Capability flags say whether this caller is the designated reviewer or the run initiator.

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.