Skip to main content
Everything you can do in the ModuleX app, you can also do from code. The REST API, the JavaScript SDK, and the Python SDK all talk to the same backend, so a workflow you build in the app runs the same way when you call it from a script. This page answers the questions people ask most when they start using ModuleX from code. For the full developer reference, see the API overview and the SDKs overview.

Quick answers

Two official SDKs

JavaScript and Python, both with streaming. A few features differ between them.

One way to authenticate

Send your mx_live_ API key as a Bearer token plus your organization ID.

One base URL

Every request goes to https://api.modulex.dev by default.

Live run streaming

Follow a run event by event with listen() or the listen endpoint.

Common questions

Yes — ModuleX publishes an official JavaScript SDK (modulex-js) and an official Python SDK (modulex-python), and both support live streaming. They cover the same operations with a handful of differences. The biggest one to know: managing subscriptions (plans, billing, checkout, the customer portal) is available in the Python SDK only — the JavaScript SDK has no subscriptions methods. For the full side-by-side comparison, see the SDK parity matrix; to get started, see the SDKs overview.
Send two things on every request: your API key as Authorization: Bearer mx_live_…, and your organization in the X-Organization-ID header. In the SDKs you pass your API key and organization ID when you create the client, and it adds both headers for you. Create and copy your key from Settings, API Keys (it is shown only once). Full details are on the authentication page.
https://api.modulex.dev, with no version segment in the path — do not add /v1 or /api. The SDKs use this base URL by default, so you normally do not set it yourself. See base URLs & versioning for the details.
Instead of waiting for a run to finish, you can follow it event by event. In the SDKs, call listen() and read the events as they arrive; over plain HTTP, open the run’s listen endpoint, which streams server-sent events. This is how the app shows live progress. See SSE run streaming and streaming & HITL.
Yes — a per-minute limit applies to your API key (and a higher combined limit across all your keys). If you go over it, ModuleX returns a 429 response with a Retry-After header telling you how many seconds to wait before retrying. The SDKs read that header and back off automatically. See rate limiting.
In the Python SDK, yes: if you do not pass them in code, it reads MODULEX_API_KEY, MODULEX_ORGANIZATION_ID, and MODULEX_BASE_URL from the environment. The JavaScript SDK does not read environment variables on its own — you must pass your API key (and organization ID) to the client explicitly. See the JavaScript SDK and Python SDK pages.
Yes. ModuleX MCP publishes your workflows, Files, and Knowledge as tools on a private Model Context Protocol endpoint that an MCP client connects to. An owner or admin creates a server and a key in Settings → ModuleX MCP, then you paste the endpoint URL and key into the client. This is separate from your mx_live_ API key — MCP clients use a server-scoped mx_mcp_ key. See ModuleX MCP and Connect an MCP client.

Authenticate and make a call

Every operation looks the same in all three: send your mx_live_ key as a Bearer token plus your X-Organization-ID. Here is listing your workflows.
The Python SDK is async — call its methods with await inside an async function. The JavaScript SDK uses promises, so await its methods too.

Stream a run live

To watch a run as it happens, call listen() with the run’s id and read events until the run finishes.

Handle rate limits

When you exceed the per-minute limit, ModuleX returns 429 with a Retry-After header (seconds to wait). The SDKs honor it and retry for you; if you call the API directly, wait that long before retrying.
1

Check the status code

A 429 means too many requests in the current window — not an error in your request itself.
2

Read Retry-After

The Retry-After response header tells you how many seconds to wait before trying again.
3

Wait, then retry

Pause for that many seconds and send the request again. The SDKs do this automatically.
For what other status codes mean (401, 402, 403, and more), see errors & troubleshooting and the full errors reference.

Where to go next

Authentication

The full authentication reference: Bearer keys, organization context, and headers.

SDKs overview

Install and configure the JavaScript and Python SDKs.

Run a workflow

An end-to-end walkthrough in cURL, Python, and JavaScript.

SDK parity matrix

Exactly which operations each SDK supports, including the Python-only subscriptions.