Python SDK (modulex-python)

The Python SDK (PyPI package modulex-python, import name modulex) is the official async client for the ModuleX REST API. It is async-only: there is one client class, Modulex, backed by an httpx.AsyncClient, and every resource method is a coroutine you await. This page covers installation, client construction, authentication, environment-variable fallbacks, the request lifecycle, and the two facts that make the Python SDK different from the JavaScript SDK — its environment-variable fallbacks and its Python-only subscriptions resource. For the full route-to-method coverage table and every cross-SDK naming difference, see the SDK parity matrix. For consuming run streams and answering human-in-the-loop prompts, see Streaming & HITL. For the exception tree and retry policy, see Errors & retries.

The Python SDK speaks snake_case on the wire in both directions — request bodies and query parameters are snake_case, and responses are snake_case Pydantic models. Unlike the JavaScript SDK, it does no camelCase-to-snake_case translation. Keys such as workflow_id, top_k, and cron_expression are passed through verbatim.

Requirements

Requirement	Value
Python	`>=3.9`
Runtime dependencies	`httpx>=0.27`, `httpx-sse>=0.4`, `pydantic>=2.7`
Current SDK version	`1.0.0`
API base URL (default)	`https://api.modulex.dev`

The SDK is built on asyncio. All examples below run inside an async def entered with asyncio.run(...).

Install

pip install modulex-python

uv add modulex-python

poetry add modulex-python

The import name is modulex, not modulex-python:

import

from modulex import Modulex

ModuleX install extras such as [all] or per-integration extras are currently empty. Installing them emits a pip warning and pulls in only the core package, so omit extras until they ship. Integrations are loaded server-side and do not require client-side extras. See Installing & using integrations and Known limitations.

Authenticate

Every request authenticates with two headers, set automatically by the client from your constructor arguments or environment:

Authorization: Bearer <mx_live_*> — your API key as a Bearer token. This is the auth header. There is no X-Authorization header.
X-Organization-ID: <org_id> — the organization the request runs in. It is sent only when an organization is resolved (constructor, environment, or per-request override).

Create an API key in the app under settings, then construct the client with it. The same auth scheme applies to cURL and the JavaScript SDK — see API authentication and the auth model for the full picture.

curl https://api.modulex.dev/auth/me \
  -H "Authorization: Bearer mx_live_your_api_key" \
  -H "X-Organization-ID: org_7f3a2b10"

import asyncio
from modulex import Modulex

async def main():
    async with Modulex(
        api_key="mx_live_your_api_key",
        organization_id="org_7f3a2b10",
    ) as client:
        me = await client.auth.me()
        print(me.id, me.email, me.primary_organization_id)

asyncio.run(main())

import { Modulex } from "modulex-js";

const client = new Modulex({
  apiKey: "mx_live_your_api_key",
  organizationId: "org_7f3a2b10",
});

const me = await client.auth.me();
console.log(me.id, me.email);

The backend also accepts X-API-KEY as an alternative to Authorization: Bearer, but the Python SDK never sends it. You can add arbitrary headers through default_headers, but the SDK will not let you override Authorization or Content-Type (see Header construction).

Construct the client

Modulex is the single entry point. Only api_key is positional; everything else is keyword-only.

signature

Modulex(
    api_key: str | None = None,
    *,
    organization_id: str | None = None,
    base_url: str | None = None,
    timeout: float = 30.0,
    max_retries: int = 3,
    default_headers: dict[str, str] | None = None,
)

str | None

default:"None"

Your mx_live_* API key, sent as Authorization: Bearer <api_key>. Required via this argument or the MODULEX_API_KEY environment variable. If neither is set, the constructor raises ValueError immediately: api_key is required: pass api_key=... or set the MODULEX_API_KEY environment variable.

str | None

default:"None"

The default organization context, sent as the X-Organization-ID header. Falls back to the MODULEX_ORGANIZATION_ID environment variable. When unset, the header is omitted; org-scoped routes then return 400 with X-Organization-ID header is required. Every org-scoped method also accepts a per-request organization_id= keyword that overrides this default for that one call.

str | None

default:"https://api.modulex.dev"

The API base URL. Falls back to the MODULEX_BASE_URL environment variable, then to the default. A trailing slash is stripped. See Base URLs & versioning — ModuleX has no /v1 path segment.

float

default:"30.0"

Per-request httpx timeout in seconds, applied on every call. No environment fallback (constructor-only). The read timeout is disabled for SSE streams.

int

default:"3"

Retry budget for transient failures on idempotent (GET/HEAD) requests. No environment fallback. See Retries, timeouts & backoff and Errors & retries.

dict[str, str] | None

default:"empty"

Extra headers merged into every request. They are merged before the auth and content-type headers, so they can override User-Agent but cannot override Authorization or Content-Type. No environment fallback.

Environment-variable fallbacks

The Python SDK reads three environment variables. This is a deliberate difference from the JavaScript SDK, which reads none and requires every value in the constructor. The resolution order is explicit argument → environment variable → default.

Constructor argument	Environment variable	Default	If missing
`api_key`	`MODULEX_API_KEY`	none	raises `ValueError`
`organization_id`	`MODULEX_ORGANIZATION_ID`	`None`	header omitted
`base_url`	`MODULEX_BASE_URL`	`https://api.modulex.dev`	uses default
`timeout`	— (none)	`30.0`	uses default
`max_retries`	— (none)	`3`	uses default
`default_headers`	— (none)	empty	uses default

With the three environment variables set, the client takes no arguments at all:

env-only

import asyncio
from modulex import Modulex

# MODULEX_API_KEY, MODULEX_ORGANIZATION_ID, MODULEX_BASE_URL read from the environment.
async def main():
    async with Modulex() as client:
        workflows = await client.workflows.list()
        print(workflows.total)

asyncio.run(main())

Only api_key, organization_id, and base_url have environment fallbacks. timeout, max_retries, and default_headers are constructor-only. Cross-reference this divergence on the JavaScript SDK page and the parity matrix.

Async client lifecycle

The client owns a shared httpx.AsyncClient connection pool. Use it as an async context manager so the pool is closed for you on exit.

import asyncio
from modulex import Modulex

async def main():
    async with Modulex(api_key="mx_live_your_api_key", organization_id="org_7f3a2b10") as client:
        me = await client.auth.me()
        print(me.username)
    # connection pool is closed here

asyncio.run(main())

import asyncio
from modulex import Modulex

async def main():
    client = Modulex(api_key="mx_live_your_api_key", organization_id="org_7f3a2b10")
    try:
        me = await client.auth.me()
        print(me.username)
    finally:
        await client.close()

asyncio.run(main())

The context manager methods are __aenter__ (returns the client) and __aexit__ (calls close()). close() awaits httpx.AsyncClient.aclose() on the shared pool. Construct the client once per process and reuse it across calls; do not create a new client per request.

Wire conventions and typed responses

snake_case both ways

Request bodies and query parameters are built as snake_case dictionaries and sent verbatim — there is no casing-translation layer. Responses are snake_case as well. Pass and read keys exactly as the API defines them: workflow_id, knowledge_base_id, top_k, cron_expression, make_default.

Pydantic v2 models with a dict-compatibility shim

Every response is a Pydantic v2 model. You can read fields with typed attribute access or legacy dict access on the same object:

access

res = await client.executions.run(workflow_id="wf_7f3a2b10", input={"q": "hi"})

res.run_id            # typed attribute access (preferred)
res["run_id"]         # dict-style access
res.get("status")     # .get() with optional default
"thread_id" in res    # membership test (declared fields + extra fields)
res.to_dict()         # model_dump(mode="json", by_alias=True, exclude_none=True)

Models are configured with extra="allow", so unknown fields returned by a newer backend are preserved (forward-compatible) and reachable through the same shim. to_dict() serializes with aliases applied and None values dropped. The model base type ModulexModel and the pagination wrapper AsyncPage are importable from modulex.types; SSEEvent is importable from the modulex package root.

Header construction

Headers are built once per request. The base set, in merge order, is:

headers

{
    "User-Agent": "modulex-python/1.0.0",   # overridable via default_headers
    # ...your default_headers merged here...
    "Authorization": "Bearer <api_key>",    # NOT overridable
    "Content-Type": "application/json",      # NOT overridable
}
# + "X-Organization-ID": "<org_id>"   when an organization is resolved
# + "Idempotency-Key": "<key>"        when idempotency_key= is passed on a mutating call

default_headers are merged before the auth and content-type keys, so they can override User-Agent but never Authorization or Content-Type.
X-Organization-ID is added only when an organization resolves. Precedence: per-request organization_id= argument → client default → omitted.
Content-Type is dropped on GET-style SSE streams (no body) and on multipart uploads (so httpx sets the multipart boundary).
Idempotency-Key is attached only when you pass idempotency_key= to a mutating method (currently executions.run).

Idempotency-Key is not a run-deduplication mechanism. The backend run route assigns its own run identifier, so a caller-supplied key does not de-duplicate runs. It is also not used by the automatic retry path, which only retries GET/HEAD. See Errors & retries.

Resource groups

The client exposes 17 resource groups as lazy properties (instantiated on first access). Each maps to a backend router; methods are async coroutines unless noted as SSE/paginator factories. The full route-to-method mapping is in the parity matrix.

`client.<attr>`	Purpose	Canonical reference
`auth`	Current user, organizations, invitations	Organizations & roles
`workflows`	Workflow CRUD, builder details, change SSE	Run via API
`executions`	Run, listen, resume, cancel, run history	SSE run streaming
`deployments`	Deploy and version workflows	Deploy & versions
`chats`	Chat list, messages, stream	Chat overview
`credentials`	Integration credentials, OAuth2, MCP	Managing credentials
`integrations`	Browse the catalog and providers	Integrations overview
`knowledge`	Knowledge bases, documents, search	Knowledge & RAG
`schedules`	Cron and interval schedules	Schedules
`composer`	AI Composer chats, HITL, save/revert	AI Composer
`assistant`	Assistant chats, HITL, streaming	Assistant overview
`dashboard`	Logs and analytics	Data model reference
`subscriptions`	Plans, billing, checkout, customer portal	Subscriptions & Stripe
`notifications`	List and create notifications	—
`api_keys`	Create, list, revoke API keys	API authentication
`system`	Health, timezones	System status
`organizations`	Org settings, members, invites	Roles & permissions

The subscriptions resource is Python-only

client.subscriptions exists only in the Python SDK. The JavaScript SDK has no subscriptions resource, so these four methods have no JavaScript counterpart — to read plans or open a Stripe checkout from JavaScript you call the REST routes directly. See the parity matrix and Subscriptions & Stripe.

Method	Signature	Returns	Route
`organization_plans`	`(*, organization_id=None)`	`OrganizationPlansResponse`	`GET /subscriptions/organization-plans`
`organization_billing`	`(*, organization_id=None)`	`BillingResponse`	`GET /subscriptions/organization-billing`
`checkout_link`	`(plan_slug, interval, *, plan_id=None, organization_id=None)`	`CheckoutResponse`	`POST /subscriptions/checkout-link`
`customer_portal`	`(*, organization_id=None)`	`CheckoutResponse`	`POST /subscriptions/customer-portal`

str

required

The target plan slug, for example "pro" or "max". Preferred over the legacy plan_id. See Plans & pricing.

str

required

The billing interval, for example "month" or "year".

str | None

default:"None"

Legacy plan identifier, deprecated in favor of plan_slug.

str | None

default:"None"

Per-request organization override; defaults to the client/environment organization.

checkout_link and customer_portal send their parameters as query parameters, not a JSON body. Both return a CheckoutResponse whose url field is the link to open in a browser. The catalog PlanPrice model exposes the field amount; the billing BillingPlanPrice model exposes the field price — they are two different shapes for two different routes.

# JavaScript has no subscriptions resource — call the REST route directly.
curl https://api.modulex.dev/subscriptions/organization-plans \
  -H "Authorization: Bearer mx_live_your_api_key" \
  -H "X-Organization-ID: org_7f3a2b10"

curl -X POST "https://api.modulex.dev/subscriptions/checkout-link?plan_slug=pro&interval=month" \
  -H "Authorization: Bearer mx_live_your_api_key" \
  -H "X-Organization-ID: org_7f3a2b10"

async with Modulex(api_key="mx_live_your_api_key", organization_id="org_7f3a2b10") as client:
    plans = await client.subscriptions.organization_plans()
    for plan in plans.plans:
        print(plan.plan_slug, [(price.interval, price.amount) for price in plan.prices])

    billing = await client.subscriptions.organization_billing()
    print(billing.has_subscription)

    checkout = await client.subscriptions.checkout_link("pro", "month")
    print(checkout.url)  # open this URL in a browser

    portal = await client.subscriptions.customer_portal()
    print(portal.url)

// No subscriptions resource exists in modulex-js. Call the REST routes with fetch.
const res = await fetch("https://api.modulex.dev/subscriptions/organization-plans", {
  headers: {
    Authorization: "Bearer mx_live_your_api_key",
    "X-Organization-ID": "org_7f3a2b10",
  },
});
const plans = await res.json();

Run a workflow

executions.run triggers a run and returns a RunResponse carrying the run_id and thread_id. Provide exactly one of workflow_id (a saved workflow), workflow (an ad-hoc definition), or system_workflow (a named system workflow). To consume the live event stream, pass run_id to executions.listen — covered in Streaming & HITL and SSE run streaming.

str | None

default:"None"

Run a saved workflow by id. Provide exactly one of workflow_id, workflow, or system_workflow.

dict | None

default:"None"

Run an ad-hoc workflow definition without saving it.

str | None

default:"None"

Run a named system workflow.

dict | None

default:"None"

Run inputs, resolved by the engine’s {{node_id.field}} reference model. See Variables & references.

dict | None

default:"None"

Per-run configuration overrides.

bool

default:"true"

Always sent. When true, the run streams events you consume with executions.listen.

bool

default:"false"

Always sent. When true, the run is not persisted to run history.

bool

default:"false"

Always sent. Scopes the run’s chat to you rather than the organization.

str | None

default:"None"

Links an ad-hoc run to a saved workflow’s Runs panel.

str | None

default:"None"

Sent as the Idempotency-Key header. Note the no-op caveat in Header construction.

str | None

default:"None"

Per-request organization override.

object

Show fields

str

The per-execution identifier used for SSE listen, status, and history. Distinct from the id field (returned by list/get) used by executions.get_run.

str

The conversation thread id; pass it to executions.resume and executions.get_state.

str

bool

str

float

object

str

Running a workflow goes through the live billing gate, so this operation can return the 402/403/429 DenialEnvelope described in Errors. Calling the run route requires the owner or admin role; the member role has been retired.

curl -X POST https://api.modulex.dev/workflows/run \
  -H "Authorization: Bearer mx_live_your_api_key" \
  -H "X-Organization-ID: org_7f3a2b10" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "wf_7f3a2b10", "input": {"q": "summarize Q3"}, "stream": true}'

import asyncio
from modulex import Modulex

async def main():
    async with Modulex(api_key="mx_live_your_api_key", organization_id="org_7f3a2b10") as client:
        run = await client.executions.run(
            workflow_id="wf_7f3a2b10",
            input={"q": "summarize Q3"},
            stream=True,
        )
        print(run.run_id, run.thread_id, run.status)

        # Stream live events (see Streaming & HITL).
        async with client.executions.listen(run.run_id) as stream:
            async for event in stream:
                print(event.event, event.data)
                if event.is_terminal:
                    break

asyncio.run(main())

import { Modulex } from "modulex-js";

const client = new Modulex({
  apiKey: "mx_live_your_api_key",
  organizationId: "org_7f3a2b10",
});

const run = await client.executions.run({
  workflowId: "wf_7f3a2b10",
  input: { q: "summarize Q3" },
  stream: true,
});
console.log(run.run_id, run.thread_id);

executions.get_run(run_pk) takes the id field on a list_runs item — not the run_id field that executions.run returns. Both fields appear on the same list item, so it is easy to confuse them. The run_id is for streaming, status, and resume; the id is for history lookups. See Workflows & runs.

Pagination

List methods come in two forms: single-page methods that return a typed *ListResponse model, and two auto-paginating helpers that return an AsyncPage[Model] you iterate with async for. The two auto-paginators are workflows.list_all (page style) and executions.iter_runs (offset style). AsyncPage validates each item into its Pydantic model lazily as you iterate. For cursor-paginated lists (composer.list, assistant.list), loop on next_cursor yourself. See Pagination.

curl "https://api.modulex.dev/workflows?page=1&page_size=20" \
  -H "Authorization: Bearer mx_live_your_api_key" \
  -H "X-Organization-ID: org_7f3a2b10"

# Single page
res = await client.workflows.list(status="active", page=1, page_size=20)
print(res.total, res.total_pages)
for wf in res.workflows:
    print(wf.id, wf.name)

# Auto-paginated (page style) — iterate every page transparently
async for wf in client.workflows.list_all(status="active", search="email"):
    print(wf.id, wf.name)

# Auto-paginated run history (offset style)
async for run in client.executions.iter_runs(status="succeeded"):
    print(run.run_id, run.status)

// Single page
const res = await client.workflows.list({ status: "active", page: 1, pageSize: 20 });
for (const wf of res.workflows) console.log(wf.id, wf.name);

// Auto-paginated
for await (const wf of client.workflows.listAll({ status: "active" })) {
  console.log(wf.id, wf.name);
}

Retries, timeouts and backoff

The SDK retries automatically, but only conservatively. Mutating requests are never retried, so they cannot double-execute.

Aspect	Behavior
Retried methods	`GET` and `HEAD` only — never `POST`/`PUT`/`PATCH`/`DELETE`
Retried statuses	`429`, `500`, `502`, `503`
Max attempts	`max_retries` retries after the first try (default `3`)
Backoff	exponential with jitter: `min(0.5 * 2*attempt + random0.5, 30.0)` seconds
`Retry-After`	honored on `429` (overrides computed backoff)
Timeouts	`GET`/`HEAD` timeouts are retried within budget, then raised as `TimeoutError`
`204 No Content`	returns `None`

See Errors & retries for the idempotency caveats and Rate limiting for the 429 headers.

Errors and billing denials

Any response with status >= 400 is mapped to a typed exception. All SDK exceptions inherit from ModulexError, which carries message, status_code, response, and body.

Status	Exception	Notes
`400`	`BadRequestError`
`401`	`AuthenticationError`	bad or missing API key
`402`	`PaymentRequiredError`	a `BillingError` subclass
`403`	`PermissionError`	also the quota-denial layer
`404`	`NotFoundError`	not found or not owned by your org (no existence leak)
`409`	`ConflictError`	e.g. a pending HITL question
`422`	`ValidationError`	FastAPI validation; messages are joined
`429`	`RateLimitError`	carries `retry_after`, `limit`, `remaining`, `reset`
`500`	`InternalError`
`502`	`ExternalServiceError`
`503`	`ServiceUnavailableError`
other `>= 400`	`ModulexError`	base fallback (e.g. `410`)
—	`StreamError`, `TimeoutError`	non-HTTP failures

On 402/403/429, if the response body carries the flat denial envelope {code, layer, key, current, limit, reason} (top-level, under detail, or a bare {reason}), the SDK raises a BillingError subclass keyed by layer:

layer="credit" → CreditExhaustedError (402)
layer="wallet" → WalletError (402)
layer="quota" → QuotaExceededError (403)
otherwise (including layer="rate") → base BillingError

This is the same DenialEnvelope the usage gate returns on the run, composer, assistant, and managed-knowledge surfaces. A header-based 429 (the active rate-limit path) raises RateLimitError instead, so handle both 429 shapes. The unified envelope reference is on the Errors page.

PermissionError and TimeoutError shadow the Python builtins of the same name. After from modulex import TimeoutError, an except TimeoutError clause catches the ModuleX exception, not asyncio.TimeoutError. Import them explicitly and be deliberate about which one a handler should catch.

error-handling

from modulex import (
    Modulex,
    ModulexError,
    NotFoundError,
    RateLimitError,
    BillingError,
    CreditExhaustedError,
    ValidationError,
)

async with Modulex(api_key="mx_live_your_api_key", organization_id="org_7f3a2b10") as client:
    try:
        await client.executions.run(workflow_id="wf_7f3a2b10", input={"q": "hi"})
    except CreditExhaustedError as e:          # 402, layer="credit"
        print(f"Out of credits: {e.current}/{e.limit} (code={e.code})")
    except BillingError as e:                  # any quota/credit/wallet/base denial
        print(f"Denied [{e.layer}/{e.code}]: {e.reason}")
    except RateLimitError as e:                # header-based 429
        print(f"Backoff {e.retry_after}s (remaining={e.remaining}, reset={e.reset})")
    except NotFoundError:
        print("Workflow or run not found (or not owned by your org)")
    except ValidationError as e:
        print(f"422: {e.message}")
    except ModulexError as e:                  # catch-all, incl. unmapped statuses
        print(f"API error ({e.status_code}): {e.message}")

Streaming and human-in-the-loop

SSE methods (executions.listen, workflows.listen_changes, composer.listen, assistant.listen, chats.stream, credentials.bulk_modulex_keys_stream) return an EventSourceStream you use as an async iterator and async context manager. Each yielded SSEEvent exposes event, data, id, retry, and is_terminal. Terminal event types (done, error, cancelled, interrupted) stop iteration; heartbeats are filtered unless you opt in. An HTTP error on connect (for example a 404, billing denial, or rate limit) raises the same typed exception as a REST call rather than an opaque stream error. For the full event taxonomy, resume contract, and worked HITL examples, see Streaming & HITL, SSE run streaming, and HITL resume.

async with client.executions.listen(run.run_id) as stream:
    async for event in stream:
        if event.event == "interrupt":
            # Pause for a human answer, then resume the run.
            await client.executions.resume(run.thread_id, run.run_id, {"answer": "yes"})
        if event.is_terminal:
            break

async with client.assistant.listen(chat_id, run_id) as stream:
    async for event in stream:
        print(event.event, event.data)
        if event.is_terminal:
            break

Next steps

SDKs overview

How both SDKs map onto the REST surface, installed once and used across every operation.

SDK parity matrix

Route-to-method coverage and every cross-SDK naming difference, including the Python-only subscriptions resource.

Streaming & HITL

Consume SSE run streams and answer human-in-the-loop prompts.

Errors & retries

The exception tree, retry policy, and idempotency behavior in depth.

Overview

SDKs

Endpoints

Realtime

MCP server

Python SDK (modulex-python)

Requirements

Install

Authenticate

Construct the client

Environment-variable fallbacks

Async client lifecycle

Wire conventions and typed responses

snake_case both ways

Pydantic v2 models with a dict-compatibility shim

Header construction

Resource groups

The subscriptions resource is Python-only

Run a workflow

Retries, timeouts and backoff

Errors and billing denials

Streaming and human-in-the-loop

Next steps

SDKs overview

SDK parity matrix

Streaming & HITL

Errors & retries

​Requirements

​Install

​Authenticate

​Construct the client

​Environment-variable fallbacks

​Async client lifecycle

​Wire conventions and typed responses

​snake_case both ways

​Pydantic v2 models with a dict-compatibility shim

​Header construction

​Resource groups

​The subscriptions resource is Python-only

​Run a workflow

​Pagination

​Retries, timeouts and backoff

​Errors and billing denials

​Streaming and human-in-the-loop

​Next steps

SDKs overview

SDK parity matrix

Streaming & HITL

Errors & retries

Requirements

Install

Authenticate

Construct the client

Environment-variable fallbacks

Async client lifecycle

Wire conventions and typed responses

snake_case both ways

Pydantic v2 models with a dict-compatibility shim

Header construction

Resource groups

The subscriptions resource is Python-only

Run a workflow

Pagination

Retries, timeouts and backoff

Errors and billing denials

Streaming and human-in-the-loop

Next steps