Minctrl Docs
Guides

Design on the canvas

Author a governed process on the canvas — place nodes, give them risk tiers and gates, validate the graph live, and save it as a versioned process of your company.

In the admin, Processes → New process opens a blank canvas where you author a process as a graph of steps. This guide covers the pieces you work with, how live validation keeps the graph governable, and how a process is saved — with the API calls the canvas makes.

Nodes and edges

A canvas is nodes connected by edges. Each node is a step carrying an id, a kind, and its governance fields:

Node kindWhat it is
agentAn automated step. Carries a risk tier, a reversible flag and the tools (tool-ids) it calls.
gateA human sign-off point. Carries the human role (human) and the gate id (gate), and optionally a form the signer fills in (see Forms in the gate) and an approvals policy — {"required": 2, "distinct_people": true, "order": "any" | "sequential", "roles": [...]} — when it needs several signatures (see Escalation, delegation and N-of-M approvals). The run parks here for a verdict.
gatewayA branch/join. Routes the run down one edge (exclusive) or fans out (parallel).
terminalThe __start__ and __end__ of the graph.

Edges connect node ids as { source, target } pairs, with an optional branch label on a gateway's or gate's outgoing edges. The example files on minctrl.com/flows show complete graphs in this shape.

Start from text

Instead of a blank canvas you can describe the process and review the graph you get back (Draft in the admin):

curl -s -X POST "$API/process-templates/draft-from-text" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Screen a member for a knee replacement prior-auth, then get a nurse sign-off.",
    "generate": false
  }'

The response is {vertical, canvas, generated}; canvas holds nodes and edges to edit. With generate: false, a description that matches one of the bundled example graphs returns that example as the starting point; when nothing matches (or with generate: true), a new graph is constructed from the text and the response adds its violations. Nothing is saved until you save it.

Validate live — gate-removal reachability

As you edit, validate the graph against the governance invariants. This is the check that keeps a process governable: it flags an irreversible step that no human gate protects, a gate missing its human role or gate id, and a bad blast radius:

curl -s -X POST "$API/process-templates/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      { "id": "screen", "kind": "agent", "tier": "medium" },
      { "id": "signoff", "kind": "gate" }
    ],
    "edges": [{ "source": "screen", "target": "signoff" }]
  }'

The response is the linearized steps plus a violations list. This graph reports that the gate has no human role and no gate id; add "human": "Finance manager" and "gate": "gate:refund-signoff" to the gate node and the list is empty. The key property: if you remove a gate that sat in front of an irreversible step, validation reports that the irreversible step is now reachable without a human — so you can't accidentally ship an ungoverned flow.

Save the process

Save the graph as a version of a process in your company. Each save bumps the version for (company, slug), so history is kept:

curl -s -X POST "$API/process-templates/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "refund-approval",
    "name": "Refund approval",
    "nodes": [
      { "id": "screen", "kind": "agent", "tier": "medium" },
      { "id": "signoff", "kind": "gate", "human": "Finance manager", "gate": "gate:refund-signoff" }
    ],
    "edges": [{ "source": "screen", "target": "signoff" }]
  }'

Saving re-runs the same validation, stores the violations alongside the graph, and returns the saved version. A graph with violations is still saved, but a run of that version is refused with 422. List the latest version of each process in your company, or read one back:

curl -s "$API/process-templates/drafts" -H "Authorization: Bearer $TOKEN"
curl -s "$API/process-templates/drafts/refund-approval" -H "Authorization: Bearer $TOKEN"

A saved version is a draft. Without violations it can be submitted for review; once an owner or admin publishes it (with separation of duties on, one who did not author it), runs start from it with {"vertical": "refund-approval", "draft": true} (see Publishing processes and Run a governed process). Before that, its author can test-run it with "draft_version": <n>, "shadow": true. The tutorial builds, saves and runs a complete four-step process.

Export and import as JSON

Every saved version exports as a minctrl.process/v1 document — the graph plus the hash a run of it would pin — for review in version control or moving between environments:

curl -s "$API/process-templates/drafts/refund-approval/export" \
  -H "Authorization: Bearer $TOKEN" -o refund-approval.process.json

?version=N exports an older version. POST /process-templates/import with {"document": <file>} (and optionally "slug") stores the file as the next version; a file whose hash no longer matches its graph is refused with 422. This is the same format as the examples on minctrl.com/flows.

See the API reference for the full canvas, validation and process schemas.

On this page