--- title: "Resume a paused plan (Enterprise only)" method: POST path: "/api/v1/plan/{id}/resume" tags: ["Multi-Agent Planning"] --- # Resume a paused plan (Enterprise only) `POST /api/v1/plan/{id}/resume` ## Request - Base URL: `https://orchestrator.getaxonflow.com` - URL: `https://orchestrator.getaxonflow.com/api/v1/plan/{id}/resume` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Resume execution of a plan that is paused at an approval gate. Used with `confirm` and `step` execution modes. - `confirm` mode: Every step requires explicit approval - `step` mode: First step auto-executes, subsequent steps require approval Set `approved: true` to approve and execute the next step, or `approved: false` to reject and abort the plan. The resume acts on the workflow bound to the plan when it entered `confirm` or `step` mode (#4249), read under the caller's tenant (the tenant that executed the plan). A plan that entered its mode before that binding existed is resumed through the workflow named for its mode under the plan's tenant, and refused when that selection is not the one live workflow. The plan's steps run in order (#4249). The step that runs is the plan's NEXT step: the lowest-numbered step that has not run. The resume approves (`approved: true`) or rejects (`approved: false`) that step's pending gate and no other; a step already approved through the plan-level approve route runs. A later step's gate, whoever wrote it, is read only at that step's turn. In `step` mode the first resume runs the ungated first step, and records it before it runs (a `workflow_steps` row with decision `allow`, no approval status and the reason `step_mode_first_step_ungated`), so a later gate cannot make the resume skip it. A step-mode plan in flight at the upgrade to this release has that record written for it (reason `backfilled_at_upgrade`), at the orchestrator's start or at its next resume; until the upgrade's migration 187 has run, such a plan's resume answers 409. A resume never runs a step past a gate that is not approved. It answers 403 when the caller is not of the plan's tenant and cannot see the plan's workflow; 404 when the caller is of the plan's tenant and the workflow is not visible to it (for example, another tenant of the organization executed the plan, or the workflow was deleted); and 409, running nothing, when: - the plan is not in `confirm` or `step` mode; - the plan's workflow is still being set up: it was marked executing and its executor has not returned. An executor that fails fails the plan; a plan left in this state (for example after a process stop) is ended with `POST /api/v1/plan/{id}/cancel`; - the plan's workflow has ended (a rejection or an expiry aborts it); `approved: false` then fails the plan instead; - the plan's next step's gate is pending (the error names the step to approve), has no approval, or was rejected or expired, or its approval is refused because it is no longer pending; - a `confirm` workflow has no gate row, or no gate row names the plan's next step; - every step of the plan has already run; - the plan's first step is already recorded by a concurrent resume; - (a `step` plan in flight at the upgrade) whether its first step ran cannot be decided yet, because migration 187 has not run; - the pending step's approval has expired (`approval_expired`), as the workflow step approve answers it; - (a plan without a binding) a workflow named for the plan has ended, or more than one is running. It answers 503, approving and running nothing, when the approval's state cannot be read (`approval_state_unreadable`), as the workflow step approve answers it. It answers 500 when a step ran but its completion could not be recorded; the step's row still reads not completed, so the next resume runs that step again (at-least-once). A step-mode first step whose record was written but whose run never finished is run by the next resume the same way. **Requires:** Enterprise license. ## Path parameters - `id` string, required ## Request body - object - `approved` boolean: Whether to approve the pending step ## Response `200` Plan resumed - ResumePlanResponse - `plan_id` string - `status` 'awaiting_approval' | 'completed' | 'failed': Status after resuming - `result` unknown - `approved` boolean: True when the resume was driven by an approval; false when the resume rejected the pending decision. Mirrors the decision the caller submitted on /resume. - `message` string: Human-readable summary of the resume outcome (e.g. "Step 3 approved; plan continuing to step 4"). - `next_step` integer: 1-based index of the next step the orchestrator will run after the resume completes. Absent when the plan is already terminal. - `next_step_name` string: Name of the step at `next_step` (mirrors PlanStep.name). Useful for callers rendering "Continuing to: …" UI. - `step_result` unknown - `total_steps` integer: Total number of steps in the plan, so callers can render "Step N of M" without a separate plan-status lookup. - `ignored_foreign_gate_rows` integer: Gate rows on the plan's workflow whose step id is not one of the plan's own step gates (written by another caller of the workflow's gate route). The resume neither approves, rejects nor waits on them. Present on an approving resume that read the workflow's gate rows. - `workflow_id` string: WCP workflow id this plan is bound to. Surfaced here so callers don't need a separate /plans/{id} round-trip after resume to learn the workflow id. ## Other responses - `403`: Enterprise license required; or (#4249) the caller's tenant cannot see the plan's workflow (`this plan belongs to another tenant`); or the resumed step was withheld by policy (`error` begins "Step withheld by policy"): the step is decided when it runs, and anything but an allow fails it and the plan. A policy approval requirement on the step is refused as `approval_required` rather than held again (#4249). - `404`: Plan not found or not awaiting approval - `409`: The resume runs nothing (#4249). The `error` names why; the cases are listed in the operation's description. - `413`: The request body is over 1 MiB (1,048,576 bytes), refused whole before it is decoded, in this route's `{success, error}` envelope: `error` begins `request_too_large: `. Nothing is gated, planned or run (#4249). - `503`: The approval's state could not be read, so nothing is approved and nothing runs (`approval_state_unreadable`, #4249). --- [API](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/revisions/f408ef3ec9dd?raw)