Base URLs, environments & versioning

The ModuleX REST API is served from a single production base URL. There is no /v1 (or /api/v1) path segment — routers mount directly at their resource path, so a request URL is just the base URL joined to the route (for example https://api.modulex.dev/workflows). This page covers the base URL, how to point each surface at a different environment, the trailing-slash rule, and how the API and the SDKs are versioned. For how to authenticate those requests, see Authentication. For the request lifecycle and content types, see the API overview.

Base URL

Environment	Base URL	Notes
Production (default)	`https://api.modulex.dev`	The base URL every SDK uses unless you override it.
Local development	`http://localhost:8000`	The backend’s documented local serving port.

Both the JavaScript SDK and the Python SDK default to https://api.modulex.dev, so you do not set the base URL for normal use. You only override it to target a local backend or a self-hosted deployment.

The production OAuth redirect target — where a browser is sent back after connecting a credential — is the ModuleX app at https://app.modulex.dev, not the API host. The API host https://api.modulex.dev only serves REST endpoints and the realtime streams. See Credentials & OAuth2.

How a request URL is built

The SDKs build every request URL as baseUrl + path, with no version segment inserted. A trailing slash on the base URL is stripped before the path is joined, so https://api.modulex.dev/ and https://api.modulex.dev behave identically.

Request URL composition

base URL          https://api.modulex.dev
+ route path      /workflows/run
= request URL     https://api.modulex.dev/workflows/run

No `/v1` path segment

ModuleX does not put a version number in the URL path. Every resource router mounts directly at its prefix:

Resource	Full URL
Workflows	`https://api.modulex.dev/workflows`
Run a workflow	`POST https://api.modulex.dev/workflows/run` (workflow id in the JSON body as `workflow_id`)
Knowledge bases	`https://api.modulex.dev/knowledge-bases`
Credentials	`https://api.modulex.dev/credentials`
Integrations	`https://api.modulex.dev/integrations`
Organizations	`https://api.modulex.dev/organizations`
API keys	`https://api.modulex.dev/api-keys`

Do not prefix routes with /v1 or /api/v1. There is no such segment — a request to https://api.modulex.dev/v1/workflows does not resolve to the workflows router. Use https://api.modulex.dev/workflows.

Trailing slashes

The API has automatic trailing-slash redirects turned off. A route is matched exactly as declared, so request the path without a trailing slash:

Request	Result
`GET /workflows`	Matches the list-workflows route.
`GET /workflows/`	Does not redirect to `/workflows`; it is treated as a different, unmatched path.

Always call the canonical path with no trailing slash. The SDKs already do this for you.

Switching environments

You change the environment by changing the base URL. Authentication is unchanged across environments — every request still sends Authorization: Bearer mx_live_… and, for organization-scoped endpoints, X-Organization-ID. Use a key that belongs to the environment you are calling.

# Production (default)
curl https://api.modulex.dev/workflows \
  -H "Authorization: Bearer mx_live_8sJ2kQ4mZ1pX7vR9tB3nW6yL0aD5cF" \
  -H "X-Organization-ID: 9d1f0c2e-4b7a-4c1e-8f3a-2b6d5e0a1c34"

# Local backend — same call, base URL swapped
curl http://localhost:8000/workflows \
  -H "Authorization: Bearer mx_live_8sJ2kQ4mZ1pX7vR9tB3nW6yL0aD5cF" \
  -H "X-Organization-ID: 9d1f0c2e-4b7a-4c1e-8f3a-2b6d5e0a1c34"

from modulex import Modulex

# Production (default) — no base_url needed
client = Modulex(
    api_key="mx_live_8sJ2kQ4mZ1pX7vR9tB3nW6yL0aD5cF",
    organization_id="9d1f0c2e-4b7a-4c1e-8f3a-2b6d5e0a1c34",
)

# Local backend — override base_url
local = Modulex(
    api_key="mx_live_8sJ2kQ4mZ1pX7vR9tB3nW6yL0aD5cF",
    organization_id="9d1f0c2e-4b7a-4c1e-8f3a-2b6d5e0a1c34",
    base_url="http://localhost:8000",
)

import { Modulex } from "modulex";

// Production (default) — no baseUrl needed
const client = new Modulex({
  apiKey: "mx_live_8sJ2kQ4mZ1pX7vR9tB3nW6yL0aD5cF",
  organizationId: "9d1f0c2e-4b7a-4c1e-8f3a-2b6d5e0a1c34",
});

// Local backend — override baseUrl
const local = new Modulex({
  apiKey: "mx_live_8sJ2kQ4mZ1pX7vR9tB3nW6yL0aD5cF",
  organizationId: "9d1f0c2e-4b7a-4c1e-8f3a-2b6d5e0a1c34",
  baseUrl: "http://localhost:8000",
});

Configuring the base URL per SDK

The two SDKs differ in whether the base URL can come from an environment variable. This matters when you deploy the same code to different environments.

string

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

Python SDK. Set it explicitly on the constructor, or set the MODULEX_BASE_URL environment variable, or let it fall back to the default. The resolution order is constructor argument → MODULEX_BASE_URL → default. The same fallback exists for MODULEX_API_KEY and MODULEX_ORGANIZATION_ID.

string

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

JavaScript SDK. Set it on the constructor (baseUrl) or omit it for the default. The JavaScript SDK has no environment-variable fallback — there is no MODULEX_BASE_URL lookup, and likewise no env fallback for the API key or organization ID. Read any environment variables in your own code and pass the value to the constructor.

JavaScript — env-driven base URL (you read the env var)

import { Modulex } from "modulex";

// The JS SDK does not read process.env itself — pass it through explicitly.
const client = new Modulex({
  apiKey: process.env.MODULEX_API_KEY ?? "",
  organizationId: process.env.MODULEX_ORGANIZATION_ID ?? "",
  baseUrl: process.env.MODULEX_BASE_URL ?? "https://api.modulex.dev",
});

Versioning

ModuleX versions the API and the SDKs separately. Neither uses a version segment in the URL path.

API versioning

The API is unversioned in the URL — there is no /v1 path segment and no API-version request header to send. The backend application advertises an internal version string of 0.1.2 (visible at the service root GET / and the health endpoint GET /system/health), but you do not pass a version on a request, and you cannot pin to a specific API version from the client side. Because there is no version negotiation, ModuleX evolves the API in a backward-compatible way wherever possible. Track changes that affect you through the changelog, and use the SDK ⇄ API parity matrix to confirm which routes a given SDK release covers.

SDK versioning (semantic versioning)

The official SDKs follow semantic versioning and ship at version 1.0.0:

SDK	Package	Version	Page
JavaScript / TypeScript	`modulex`	`1.0.0`	JavaScript SDK
Python	`modulex`	`1.0.0`	Python SDK

Pin the SDK version in your dependency manifest so a major release does not change behavior under you. Breaking changes land in a new major version; consult the changelog before upgrading across a major boundary. Notable changes already shipped in the 1.0 line include the retirement of the organization member role (invites accept only admin; see Roles & permissions), realtime SSE frames discriminating on type rather than event, and the removal of client-side billing helpers from the JavaScript SDK.

The Python SDK sends a User-Agent of modulex-python/<version> on every request; the JavaScript SDK does not set a User-Agent. Neither identifies an API version, because the API is unversioned.

Interactive API documentation

The running backend also serves machine- and human-readable API references at the base URL:

Path	Surface
`https://api.modulex.dev/docs`	Swagger UI (interactive).
`https://api.modulex.dev/redoc`	ReDoc reference.
`https://api.modulex.dev/system/health`	Public liveness check returning `{ "status": "healthy", "service": "ModuleX", "version": "0.1.2" }`.

For the curated, language-tabbed reference and a live “Try it” playground inside these docs, use the API overview and the endpoint reference. To check live availability, see System status & health.

What does not change per environment

Switching environments changes only the base URL. The following are the same across production and a local or self-hosted backend:

Authentication scheme

Every request sends Authorization: Bearer mx_live_…, and organization-scoped requests also send X-Organization-ID. See Authentication.

Route paths

The same paths with no /v1 segment, called without a trailing slash.

Error envelopes

The same three error shapes, including the billing DenialEnvelope returned as 402 / 403 / 429 on metered surfaces. See Errors & status codes.

Rate limiting

The same per-key, per-user, and per-organization limits and 429 responses. See Rate limiting.

Next steps

Make your first API call

Authenticate and run a workflow with cURL, Python, and JavaScript.

Authentication

The Authorization: Bearer header and X-Organization-ID org context.

API overview

The request lifecycle, content types, and how each operation is shown three ways.

SDK ⇄ API parity matrix

Which REST routes each SDK release maps to, with gaps called out.

Welcome

Quickstart

Foundations

Concepts

Base URLs, environments & versioning

Base URL

How a request URL is built

No `/v1` path segment

Trailing slashes

Switching environments

Configuring the base URL per SDK

Versioning

API versioning

SDK versioning (semantic versioning)

Interactive API documentation

What does not change per environment

Next steps

Make your first API call

Authentication

API overview

SDK ⇄ API parity matrix

​Base URL

​How a request URL is built

​No /v1 path segment

​Trailing slashes

​Switching environments

​Configuring the base URL per SDK

​Versioning

​API versioning

​SDK versioning (semantic versioning)

​Interactive API documentation

​What does not change per environment

​Next steps

Make your first API call

Authentication

API overview

SDK ⇄ API parity matrix

Base URL

How a request URL is built

No `/v1` path segment

Trailing slashes

Switching environments

Configuring the base URL per SDK

Versioning

API versioning

SDK versioning (semantic versioning)

Interactive API documentation

What does not change per environment

Next steps