Python SDK
A typed, httpx-based Python client for the Minctrl API — run the governed start → park → resume loop from your own code.
The Python SDK (minctrl-sdk) is a small, hand-written client over
httpx. Each method is one API route, grouped as
auth, templates, connectors, and runs. It covers part of the
API reference; the gaps are listed below.
Install
pip install minctrl-sdkThe only runtime dependency is httpx.
Not wrapped yet: your own processes
The SDK was written when Minctrl shipped built-in processes. It does not yet wrap importing
or saving a process (POST /process-templates/import, POST /process-templates/,
GET /process-templates/drafts), and runs.start sends only vertical, inputs and
auto_resolve — no draft — so it can only start a bundled example by name.
client.templates reads only those bundled graphs. Until the SDK catches up, import and
start the run with httpx as below, then use the SDK for the rest.
Quickstart
Create a client, authenticate, import an example, and run the governed cycle: a run proceeds on its own until governance parks it on a gate, then you resume it on that gate.
import httpx
import minctrl
API = "https://app.minctrl.com"
client = minctrl.MinctrlClient(API)
# Authenticate — attach the returned token to the client.
session = client.auth.login("[email protected]", "<your-password>")
client.token = session["token"]
headers = {"Authorization": f"Bearer {client.token}"}
# Import the AML example into your company (not wrapped by the SDK yet).
doc = httpx.get("https://minctrl.com/examples/aml.process.json").json()
httpx.post(f"{API}/process-templates/import", json={"document": doc},
headers=headers).raise_for_status()
# Start a run of the saved process (draft=True is not wrapped by runs.start yet).
run = httpx.post(f"{API}/process-runs", headers=headers, json={
"vertical": "aml", "draft": True,
"inputs": {"customer_name": "Jane Q. Public", "risk": "high"},
}).raise_for_status().json()
# The run parks when governance needs a person. trace.parked_step is the step-id to sign.
if run["status"] == "awaiting_human":
client.runs.resume(run["id"], gate=run["trace"]["parked_step"],
decision="onboarding approved")Which gate to name
runs.resume(...) takes the step-id the run parked on (trace.parked_step) or its
parked_at label. The run id is run["id"]. Check status after a resume: a gate or
decision that matches nothing leaves the run parked where it was.
Irreversible tools stay shadowed
Even with auto_resolve=True (the default), a connector bound to an
irreversible tool-id runs in shadow — no real call is made — unless its
config sets reversible=True. The autopilot never fires a live irreversible
action on your behalf.
Client surface
Every group maps onto these routes:
| Group | Methods | Routes |
|---|---|---|
client.auth | register, login, me | /auth/register, /auth/login, /auth/me |
client.templates | list, canvas, bpmn (bundled example graphs, by name) | /process-templates/, /process-templates/{vertical}/canvas, /process-templates/{vertical}/bpmn |
client.connectors | list, upsert, test, delete | /connectors/, /connectors/{tool_id} (+ /test) |
client.runs | start, get, resume, list | /process-runs/, /process-runs/{run_id} (+ /resume) |
The client always sends and expects JSON, follows redirects, and raises a typed
minctrl.MinctrlError (with .status and .detail) on any non-2xx response.
Binding a connector
Bind a process tool-id to one of your own HTTP endpoints. Keep reversible=False
so an irreversible screen stays shadowed until you explicitly opt in.
from minctrl import ConnectorConfig
client.connectors.upsert(
"sanctions-screen",
ConnectorConfig(
base_url="https://screening.vendor.com",
method="POST",
path="/v1/screen",
auth_type="bearer",
auth_token="<your-token>",
body_map={"full_name": "customer_name"},
signal_rule={"path": "match_score", "op": "lt", "value": 0.85,
"pass": "clear", "fail": "hit"},
reversible=False,
),
)Authentication
Every method except auth.register and auth.login requires a bearer token. Set
it at construction or after logging in — the SDK sends it as
Authorization: Bearer <token> on each request:
# At construction:
client = minctrl.MinctrlClient("https://app.minctrl.com", token="<token>")
# Or after login:
client.token = client.auth.login("[email protected]", "<your-password>")["token"]With an API key
A script or an integration uses a company API key instead of a person's session —
MinctrlClient(base_url, api_key="mk_live_…"), or MINCTRL_API_KEY in the environment. A
key never signs a gate. See API keys and service accounts.
Triggers
client.triggers lists, creates, updates, rotates and deletes webhook and schedule
triggers — with an owner's session or a key that has triggers:manage. A webhook's url
and a generated secret are in the create response only. See
Triggers.
Test suites
client.tests.run(slug, version) runs a process's test suite against a version (a key needs
processes:test) and returns the result: status (passed | failed | error), summary
and per case its status and first divergence. client.tests.passed(result) is true only for
passed. runs, result and cases read (processes:read); compare(slug, a, b) lines up
two versions. See Testing processes.
See also
- API reference — every operation and model, generated from the OpenAPI schema.
- Run a governed process — the start → park → resume loop in depth.
TypeScript SDK
A typed, fetch-based TypeScript client for the Minctrl API — run the governed start → park → resume loop from Node or the browser.
Governance model
How Minctrl decides when a step runs on its own and when it parks for a human — risk-tiered gates, the judge panel, calibrated confidence, and a tamper-evident audit trail.