Minctrl Docs
Tutorials

Your first governed flow

From zero to a completed governed run — write a small process, validate it, save it, run it, watch it park at a human gate, sign it, and read the audit chain — with the reason behind each step.

This tutorial takes you from nothing to a completed governed run of a process you write yourself, and explains why each step exists. You will write a four-step refund process, see validation reject an ungoverned version of it, save it, run it, sign its gate, and read the record the run leaves behind.

The Quickstart is the shorter path (it imports a ready example); Example processes are larger flows to import and run. This page stops at each step to explain the idea behind it.

What you need

A Minctrl API base URL in $API, and curl + jq. Registration creates everything else.

Why governance, not just automation

Automating a regulated process usually forces a bad trade: either a person touches every step (slow, expensive) or agents run unsupervised (fast, hard to defend). Minctrl lets agents do the reversible work and parks the run for a human verdict on the steps that can't be undone. Everything that happens is written to a hash-chained audit record.

Step 1 — Register

TOKEN=$(curl -s -X POST "$API/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"<your-password>","company_name":"Acme Ops"}' \
  | jq -r .token)

Why it matters. Registration creates a company and makes you its owner. The company is the isolation boundary: your token identifies both you and your company, and every process, run and audit entry you create belongs to it. A new company starts with no processes — the next steps add the first one.

Step 2 — Write the process

A process is a graph of nodes (steps) and edges. This one checks a refund request, asks a finance manager to approve it, then issues the refund:

cat > refund.json <<'EOF'
{
  "nodes": [
    { "id": "__start__", "kind": "terminal" },
    { "id": "check", "kind": "agent", "label": "Check the refund against policy",
      "tier": "low", "reversible": true, "tools": [] },
    { "id": "signoff", "kind": "gate", "label": "A finance manager approves the refund",
      "human": "Finance manager", "gate": "gate:refund-signoff",
      "tier": "high", "reversible": false, "interrupt_before": true },
    { "id": "pay", "kind": "agent", "label": "Issue the refund",
      "tier": "high", "reversible": false, "tools": ["payments"] },
    { "id": "__end__", "kind": "terminal" }
  ],
  "edges": [
    { "source": "__start__", "target": "check" },
    { "source": "check", "target": "signoff" },
    { "source": "signoff", "target": "pay" },
    { "source": "pay", "target": "__end__" }
  ]
}
EOF

Why it matters. The graph that drives execution also carries the governance: each step has a risk tier and a reversible flag, and the gate node names the human role (human) and the gate id (gate) a run will park on. pay is irreversible — money that left can't be called back — so it sits behind the gate.

Step 3 — Validate (why a flow can't be silently ungoverned)

curl -s -X POST "$API/process-templates/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @refund.json | jq .violations
[]

Now remove the gate and connect check straight to pay:

jq '.nodes |= map(select(.id != "signoff"))
    | .edges = [{"source":"__start__","target":"check"},
                {"source":"check","target":"pay"},
                {"source":"pay","target":"__end__"}]' refund.json \
  | curl -s -X POST "$API/process-templates/validate" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @- | jq .violations
["step None_1 ('Issue the refund'): irreversible action not preceded by a human gate"]

Why it matters. Validation enforces the invariants that make governance real: an irreversible step must have a human gate in front of it, and a gate must carry its human role and gate id. A process with violations can be saved as a draft, but a run of it is refused with 422 — so an ungoverned flow can't run by accident. (See Design on the canvas.)

Step 4 — Save it

jq '{slug: "refund-approval", name: "Refund approval"} + .' refund.json \
  | curl -s -X POST "$API/process-templates/" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @- | jq '{slug, version, violations}'

Why it matters. Each save is a new immutable version of (company, slug), and it is a draft: it does not run for real until it is published (Step 5). A run is pinned to one version for its whole life, so editing the process later never changes a run that is already waiting for a signature. GET /process-templates/drafts lists the latest version of every process in your company, its state, and published_version.

Step 5 — Publish it

Working through this tutorial alone, turn separation of duties off first: with it on (the default) the author of a version may not publish it, and you are the author.

curl -s -X PUT "$API/governance/policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"separation_of_duties": false}'

curl -s -X POST "$API/process-templates/drafts/refund-approval/versions/1/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"note": "First version of the refund flow."}'

curl -s "$API/process-templates/drafts/refund-approval/diff?version=1" \
  -H "Authorization: Bearer $TOKEN" | jq '{against, changes, steps: .steps.added | length}'

curl -s -X POST "$API/process-templates/drafts/refund-approval/versions/1/publish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"against": null}' | jq '{version, state, sod, by_author}'

Why it matters. Runs start only from the published version, so a change to what the autopilot does is a decision someone signs off. In a team you keep separation of duties on and the person who changes the process is not the one who publishes it: another owner or admin reads the diff and publishes (your own publish is then refused with 403). Alone, the entry records "sod": false, "by_author": true — the record says plainly that the author published it. Before publishing, the author can also test a version as a shadow run ("draft_version": 1, "shadow": true). See Publishing processes.

Step 6 — Run it (the autopilot does the reversible work)

RUN=$(curl -s -X POST "$API/process-runs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "refund-approval",
    "draft": true,
    "inputs": { "order_id": "O-1001", "amount": 120 }
  }')
RUN_ID=$(echo "$RUN" | jq -r .id)
echo "$RUN" | jq '{status, parked_at, step: .trace.parked_step, graph_version, graph_hash}'

Why it matters. vertical is your process slug and draft: true says it is a process saved in your company; the run starts from its published version. With auto_resolve (on by default) the resolver executes the steps it can clear — here, check — and stops at the first step that needs a person. The response records which version and hash the run is pinned to.

Step 7 — The gate: why the run parks

The run came back with status: "awaiting_human", parked_at: "gate:refund-signoff" and trace.parked_step: "signoff".

Why it matters. The run reached a gate whose step is irreversible, so it parks: its state is persisted and it waits. Parking is durable, so it can wait minutes or days without holding a request open — a governed process fits a real person's working day instead of a timeout.

Step 8 — Sign the gate

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

Why it matters. Signing needs the manager role or above; your role is recorded with the signature. The verdict is recorded against the gate and the run continues from there — steps that already ran are not called again. pay now executes, in shadow (no real payment) because no connector has opted the payments tool in, and the run reaches completed.

Name the gate by its step-id (signoff) or its parked_at label (gate:refund-signoff). A gate that names neither leaves the run parked on the same gate, so check status and trace.parked_step in the response.

Step 9 — The audit chain: why it's all defensible

curl -s "$API/audit-chain?run_id=$RUN_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '[.[] | {seq, kind}]'
curl -s "$API/audit-chain/verify" -H "Authorization: Bearer $TOKEN"

Why it matters. The run start and every signature are entries in your company's audit chain, written in the same transaction as the change they record; saving and importing processes are recorded too. Each entry is hash-linked to the one before, so verify reports the first entry that was edited or deleted. The run's own trace.events (from GET /process-runs/{id}) shows each step: what auto-executed, what parked, who signed.

What you built

A process you wrote and published, where an agent did the reversible work, a person signed the step that can't be undone, and the whole run left a verifiable record:

write → validate → save → submit → publish → run → gate → park → sign → audit

Where to go next

On this page