Create a run

The server resolves all components (with environment overrides applied), builds the dependency DAG, and begins rendering and executing revisions.

Concurrency: only one run can be active per application+environment at a time. If a run is already in an active state (PENDING, QUEUED, PLANNING, PLANNED, or APPLYING), the new run is queued and will start automatically when the current run completes or is canceled.

Scope: run:write

Authorization

bearerAuth

AuthorizationBearer <token>

Personal Access Token (PAT) or Service Access Token (SAT). Pass the token in the Authorization header: Bearer admp_...

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

application_id*application_id

The application to run (UUID).

Formatuuid

environment_id*environment_id

The target environment (UUID).

Formatuuid

message?message

Optional message describing this run.

Lengthlength <= 1024

source_run_id?source_run_id

Optional: run from a prior run's configuration snapshots instead of from the current component HEAD. When set, each revision is seeded from the source run's revision for the same component (catalog_item_id, version, resolved_values, source_id, working_directory). This is the rollback mechanism: re-plan and re-apply a known-good configuration against the current infrastructure state.

change_set_id?change_set_id

Optional: run the entries and variable changes captured in a change set. When set, the component set and variable overlay are sourced from the change set instead of the application's full component list. The change set must be OPEN and target the same (application, environment).

Response Body

`application/json`

curl -X POST "https://api.admiral.io/api/v1/runs" \  -H "Content-Type: application/json" \  -d '{    "application_id": "48ac72d0-a829-4896-a067-dcb1c2b0f30c",    "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4"  }'

{  "run": {    "id": "7e8f9a0b-1c2d-3e4f-5a6b-7c8d9e0f1a2b",    "display_id": "run-3k7m9p2q4rvw",    "application_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",    "environment_id": "e5f6a7b8-9012-3cde-f456-789012345678",    "status": "RUN_STATUS_SUCCEEDED",    "message": "Deploy v2.4.1 with updated ingress rules",    "triggered_by": {      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",      "display_name": "Alex Chen",      "email": "[email protected]"    },    "revision_summary": {      "total": 3,      "succeeded": 3    },    "created_at": "2025-11-20T14:00:00Z",    "completed_at": "2025-11-20T14:12:00Z"  }}

Authorization

Request Body

Response Body

200application/json

`application/json`