Triggering a workflow run

A run is created by posting to the runs endpoint with the workflow identifier and its declared inputs. Inputs are validated against the workflow's schema before the run is accepted, so an invalid request fails immediately rather than part-way through execution.

curl -X POST https://api.stackheal.example/v1/runs \
  -H "Authorization: Bearer $STACKHEAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "wf.disk_reclaim",
    "tenant": "acme",
    "inputs": {
      "asset_id": "srv_web07",
      "ticket_ref": "10482"
    }
  }'

Run states

• queued — accepted and waiting for a runner.
• running — executing steps.
• awaiting_approval — paused at an approval step, with the approver and deadline on the record.
• verified — completed and the verification assertion passed.
• unverified — completed but the assertion did not pass. Requires a human decision.
• failed — a step failed and the retry policy was exhausted.
• abandoned — stopped by policy, suppression, or an approval timeout.

Reading status

Poll the run endpoint, or subscribe to outbound webhooks for run events. Webhooks are preferable for anything that needs to react promptly; polling is fine for reconciliation jobs.