Minctrl Docs

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 signoff on this run can't sign appeal-review too (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_visit counts the laps). The tutorial builds a straight process that reaches completed.

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

On this page