Quickstart
Register, import an example process (or save your own), publish it, start a run that parks at a human gate, then sign the gate — with curl for every step.
This walks the full loop: register → put a process in your company → publish it → start a
run (it parks) → sign the gate. Every step is a single curl call.
A new company has no processes. You add one in one of four ways: import a
minctrl.process/v1 JSON file, import a BPMN 2.0 model, describe the process in text and
save the draft you get back, or build it on the canvas. This quickstart imports one of the
example processes published on minctrl.com/flows.
Base URL
Replace $API with your Minctrl API base URL (e.g. https://api.minctrl.com).
All endpoints except /auth/* and /health require Authorization: Bearer <token>.
The examples use jq.
1. Register
Registration creates your user and a company, and makes you its owner. The response contains a token.
TOKEN=$(curl -s -X POST "$API/auth/register" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "a-strong-password",
"company_name": "Acme Ops"
}' | jq -r .token)2. Import an example process
Every page under minctrl.com/flows has a process file at
https://minctrl.com/examples/<slug>.process.json. Download the prior-authorization
example and post it, unchanged, to the import endpoint. The body wraps the file as
document:
curl -s -o prior-auth.process.json https://minctrl.com/examples/prior-auth.process.json
jq -n --slurpfile doc prior-auth.process.json '{document: $doc[0]}' \
| curl -s -X POST "$API/process-templates/import" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data-binary @- \
| jq '{slug, version, hash, executable_violations}'The process is now saved in your company as prior-auth, version 1 — a draft. hash
identifies the exact graph a run will be pinned to; executable_violations is empty, so it
can be submitted for review and published. The file's hash must match its graph: a file
edited after export is refused with 422.
To store it under your own name, add "slug": "prior-auth-acme" next to document.
Importing again under the same slug saves the next version.
Or start from your own process
Save a graph you wrote yourself with POST /process-templates/ (see
Design on the canvas), import a BPMN model
(Import / export BPMN), or build it in the admin under
Processes. Every path stores a versioned process in your company; the rest of this page
works the same with its slug.
You can read the saved process back, including which steps are gates:
curl -s "$API/process-templates/drafts/prior-auth" -H "Authorization: Bearer $TOKEN" \
| jq '[.canvas.nodes[] | select(.kind == "gate") | {id, gate, human}]'3. Publish it
The import is a draft: runs start only from a published version. Its author (you) submits it for review, and an owner or admin publishes it after reading the diff.
With separation of duties on — the default — the publisher must not be the version's author, and the importer of an example is its author. Working alone, turn it off first (you are the owner; the change is recorded in the audit chain). It also lets one person sign two gates of the same run, which step 5 needs:
curl -s -X PUT "$API/governance/policy" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"separation_of_duties": false}'Then submit, read the diff and publish:
curl -s -X POST "$API/process-templates/drafts/prior-auth/versions/1/submit" \
-H "Authorization: Bearer $TOKEN"
curl -s "$API/process-templates/drafts/prior-auth/diff?version=1" \
-H "Authorization: Bearer $TOKEN" | jq '{against, changes}'
curl -s -X POST "$API/process-templates/drafts/prior-auth/versions/1/publish" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"against": null}' | jq '{version, state, sod, by_author}'"sod": false, "by_author": true is in the audit entry too: a version its author published.
With a team, keep separation of duties on and have another owner or admin run the last two
calls with their own token (see Publishing processes).
Test before you publish
The author can run an unpublished version as a shadow test run — every connector
shadowed, nothing leaves Minctrl — by adding "draft_version": 1, "shadow": true to the
run in step 4.
4. Start a run — it parks
Start a run of your process. vertical is the process slug and draft: true says it is a
process saved in your company; the run starts from the published version and is pinned to
it for its whole life.
RUN_ID=$(curl -s -X POST "$API/process-runs" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"vertical": "prior-auth",
"draft": true,
"inputs": {
"member_id": "M-10293",
"procedure_code": "27447",
"diagnosis": "M17.0",
"risk": "fails criteria"
}
}' | jq -r .id)The run executes until it reaches the first human gate, then parks:
curl -s "$API/process-runs/$RUN_ID" -H "Authorization: Bearer $TOKEN" \
| jq '{status, parked_at, step: .trace.parked_step}'{ "status": "awaiting_human", "parked_at": "gate:medical-director-signoff", "step": "signoff" }risk steers the example's branches: "fails criteria" takes the medical-necessity path
to the medical director's gate. See Example processes for how routing
works when no connectors are bound.
5. Sign the gate
A person with the manager role or above records a verdict on the gate the run parked on.
gate is the step-id from trace.parked_step (signoff) or the parked_at label;
decision is the verdict, or a branch label. A denied verdict must carry a non-blank
feedback (the reason is recorded with the signature); without it the API answers 422.
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": "Chart reviewed; criteria not met."
}' | jq '{status, parked_at, step: .trace.parked_step}'The run continues from the gate. In this example it next transmits the determination
(shadowed, see below), moves to monitoring and parks again at the appeal-review gate
(appeal-review). Two things to know before you sign that one:
- Separation of duties: with it on (the default) whoever signed
signoffon this run can't signappeal-reviewtoo (409); have another manager sign it. If you turned it off in step 3, you can sign both. - This example loops. Without your systems connected, the monitoring step leads back to
the appeal-review gate on every lap, so the run keeps parking there
(
trace.parked_visitcounts the laps). The tutorial builds a straight process that reachescompleted.
Nothing irreversible fires
Steps marked reversible: false (here, transmitting the determination) run in shadow
— no real call — unless you bind a connector to their tool-id and opt it in. See
Connect a step to your API.
Next steps
- Publishing processes — review, diff, rollback.
- Example processes — six examples run end to end.
- Connect a step to your API — bind a tool-id to your system.
- Run a governed process — gates, park/resume, versions.
- Governance model — why a step parks (or doesn't).