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 kind | What it is |
|---|---|
agent | An automated step. Carries a risk tier, a reversible flag and the tools (tool-ids) it calls. |
gate | A 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. |
gateway | A branch/join. Routes the run down one edge (exclusive) or fans out (parallel). |
terminal | The __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.
Run a governed process
Start a run of a process saved in your company, understand why it parks, resume it on the right gate, and keep irreversible tools shadowed.
Import / export BPMN
Round-trip a process with BPMN 2.0 — export a saved process to XML, or import a model from Camunda, Signavio or Bizagi, see where it is ungoverned, and save it as a process of your company.