Answer a pending run interaction
/api/v1/runs/{run_id}/interaction/respondAtomically consume the exact pending user-input or tool-approval interaction, persist the attributed decision, and request that the run resume.
A 409 means the interaction changed or was already consumed. Retrieve the interaction again and review the current request; do not blindly replay the old decision.
A 202 response means the decision is durable. resume_status can still be failed; in that case the run remains safely paused and the ordinary resume operation can retry dispatch without changing the recorded decision.
High-risk approvals include a server-chosen confirm_label. Copy that exact value into confirmation when approving. Denials never require typed confirmation.
Required access
Credentials: delegated token, user session
Scope: runs:edit
Only the user identity persisted as the run's actor may answer. A delegated token can answer its own user's run; service principals and organization admins acting for another user cannot.
Authorization
DelegatedToken A token issued to an external application acting for a specific user, prefixed gsmc_dt_. Carries that user's identity for attribution and ownership, and stays capped at member role however privileged the user is.
In: header
Path Parameters
Header Parameters
Selects the active organization for a credential that belongs to more than one. Service-principal keys are bound to a single organization and ignore it.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Answer the exact pending user-input interaction.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/runs/0/interaction/respond" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "kind": "user_input", "interaction_id": "mctrl_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "answers": [ { "question_index": 0, "source": "selected", "suggestion_index": 0 } ] }'{ "accepted": true, "resume_status": "dispatched", "run": { "id": 1, "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba", "invocable_type": "agent", "actor_principal_type": "agent", "service_principal_id": "0d57b427-9ed2-4a5e-b0bd-32c8ce299b8e", "oauth_client_id": "727760ca-b97d-449c-90e5-7773c8142d5d", "parent_run_id": 1, "root_run_id": 1, "call_depth": 0, "agent_config_revision": 1, "agent_config_digest": "string", "tool_approval_mode": "auto", "tool_approval_mode_revision": 1, "status": "awaiting_plan_approval", "created_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z", "duration_seconds": 0, "last_heartbeat": "2019-08-24T14:15:22Z", "input_data": {}, "output_data": {}, "artifacts": [ {} ], "verification_status": "not_evaluated", "verification_summary": "string", "verification_checks_passed": 0, "verification_checks_total": 0, "verification_evaluated_at": "2019-08-24T14:15:22Z", "error": "string", "error_category": "string", "error_code": "string", "error_retryable": true, "limit_detail": { "error": "limit_exceeded", "limit_type": "budget.hard_stop", "scope": "call_tree", "message": "string", "scope_id": "string", "limit": 0, "actual": 0, "retry_after_seconds": 0, "resets_at": "2019-08-24T14:15:22Z" }, "tool_retry_intervention": { "code": "string", "message": "string", "retryable": true, "suggested_action": "string", "tool_label": "string", "policy_event_type": "string", "attempt_count": 1, "failure_class": "authentication", "last_error_code": "string", "retry_disposition": "authentication_required", "circuit_state": "closed", "retry_not_before": "2019-08-24T14:15:22Z" }, "tool_outcome_blocker": { "blocker_id": "string", "reason": "tool.outcome_uncertain", "retry_not_before": "2019-08-24T14:15:22Z", "review": { "schema_version": 1, "review_core": { "schema_version": 1, "action_label": "string", "target_summary": "string", "attempted_at": "2019-08-24T14:15:22Z", "attempt_count": 1, "failure_class": "authentication", "error_code": "string", "uncertainty_reason": "string", "evidence": [ { "kind": "string", "label": "string", "content_digest": "stringstringstringstringstringstringstringstringstringstringstringstrin" } ] }, "attestable": true, "review_digest": "string", "evidence_links": [ { "kind": "tool_call_audit", "label": "string", "resource_id": "string" } ] }, "resolution_committed": false, "resume_pending": false, "resolution_id": "e25ae328-69b8-4e08-9f09-52d881051e39", "resolution": "abandon_operation" }, "tool_outcome_wake_state": "string", "tool_calls_count": 0, "tool_attempts_count": 0, "tokens_used": 0, "input_tokens": 0, "output_tokens": 0, "model": "string", "cost_usd": 0, "cost_pricing_fallback": true, "sandbox_duration_ms": 0, "sandbox_cost_cents": 0, "sandbox_id": "string", "desktop_stream_url": "string", "child_group_id": 1, "child_scope_key": "string", "child_scope_label": "string", "child_group_count": 0, "project_tag": "string", "ticket_tag": "string", "cost_center_tag": "string" }}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}Retrieve a pending run interaction GET
Retrieve the exact durable question or tool-approval request a run is currently waiting for. The interaction is null when the run is not awaiting a human decision.
Retrieve a run plan GET
Retrieve the active governance plan, its current enforcement position, and the optimistic-concurrency fence needed to replace it.