Minctrl Docs
SDKs

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-sdk

The 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:

GroupMethodsRoutes
client.authregister, login, me/auth/register, /auth/login, /auth/me
client.templateslist, canvas, bpmn (bundled example graphs, by name)/process-templates/, /process-templates/{vertical}/canvas, /process-templates/{vertical}/bpmn
client.connectorslist, upsert, test, delete/connectors/, /connectors/{tool_id} (+ /test)
client.runsstart, 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

On this page