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. Its surface mirrors the real API routes one-to-one — grouped as auth, templates, connectors, and runs — so anything you can do with the API reference you can do in a few typed lines of Python.

Install

pip install minctrl-sdk

The only runtime dependency is httpx.

Quickstart

Create a client, authenticate, and run the governed cycle: a run proceeds on its own until governance parks it on a gate, then you resume it with the gate step-id.

import minctrl

client = minctrl.MinctrlClient("https://app.minctrl.com")

# Authenticate — attach the returned token to the client.
session = client.auth.login("jane.doe@acme-health.com", "<your-password>")
client.token = session["token"]

# Start a run. inputs are the seed facts steps and connectors read from.
run = client.runs.start(
    vertical="aml",
    inputs={"member_id": "M-10293", "customer_name": "Jane Q. Public"},
)

# The run parks when governance needs a human. Sign the gate STEP-ID
# (not the "gate:" display label) to continue.
if run.get("status") == "parked":
    client.runs.resume(run["run_id"], gate="bsa-gate", decision="approved")

Gate = step-id

runs.resume(...) takes the gate step-id the run parked on — the id in the parked run's state — not the gate:-prefixed display label. Passing the label will not resolve the parked gate.

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 directly onto the API:

Group	Methods	Routes
`client.auth`	`register`, `login`, `me`	`/auth/register`, `/auth/login`, `/auth/me`
`client.templates`	`list`, `canvas`, `bpmn`	`/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("jane.doe@acme-health.com", "<your-password>")["token"]