Run a governed process

A run executes a process template's canvas graph step by step. It proceeds on its own until governance decides a step needs a human — then it parks. This guide covers the start → park → resume loop and the two things people get wrong: the gate step-id and shadowing.

Start a run

curl -s -X POST "$API/process-runs/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "prior-auth",
    "inputs": { "member_id": "M-10293", "procedure_code": "27447" },
    "auto_resolve": true
  }'

• vertical — the template slug to run (from GET /process-templates/). Required.
• inputs — the seed facts steps and connectors read from.
• auto_resolve — run the autopilot: auto-execute steps the resolver clears. With it off, every step waits for you.

Why a run parks

A run parks when it reaches a gate — a step whose risk tier requires a human verdict (see the Governance model). The parked response names the gate step-id the run stopped on. Read the current state any time:

curl -s "$API/process-runs/$RUN_ID" -H "Authorization: Bearer $TOKEN"

To see which step-ids are gates before running, inspect the decorated canvas:

curl -s "$API/process-templates/prior-auth/canvas" -H "Authorization: Bearer $TOKEN"

Resume with the right gate step-id

The single most common mistake: passing a display label instead of the step-id. The gate field must be the step-id the run parked on — not the human-readable name.

curl -s -X POST "$API/process-runs/$RUN_ID/resume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gate": "signoff",
    "decision": "approved"
  }'

• gate — the gate step-id (the id the run parked on), e.g. signoff.
• decision — approved, denied, or a branch label for a gateway.

If the step-id doesn't match the parked gate the API returns 409 Conflict. Fetch the run again, read the parked gate step-id, and retry.

Keep irreversible tools shadowed

The loop

1. POST /process-runs/ → run executes, then parks at a gate.
2. GET /process-runs/{id} → read the parked gate step-id.
3. POST /process-runs/{id}/resume with that step-id + a decision → run continues.
4. Repeat until the run completes.