🎬 MEDIA PLACEHOLDER · MX-MEDIA-1310 · [IMAGE]
[IMAGE_DESCRIPTION]: A one-screen “naming map” that groups the canonical ModuleX terms into their subsystems (engine, agents, knowledge, integrations, auth, billing, errors, realtime) so a reader can place a term at a glance.
[IMAGE_DETAILS]: Eight labeled clusters — “Workflow engine” (workflow, node, edge, state, reference), “Agents” (AI Composer, Assistant, turn, HITL), “Knowledge / RAG” (knowledge base, document, chunk, retrieval), “Integrations” (integration, tool, credential, manifest), “Auth & orgs” (API key, organization, X-Organization-ID, role), “Billing” (credit, wallet, overage, entitlement), “Errors” (DenialEnvelope, BillingDenied, layer), “Realtime” (run_id, thread_id, SSE, Socket.io). Use the ModuleX brand palette. Light theme, 16:9, no UI chrome, readable at one glance. Mark the deprecated terms (member role, X-Authorization, workflow:updated channel) in a small struck-through “do not use” footnote band.
Terms you should not use
These names are deprecated, wrong, or refer to a path that does not work. They appear in older code and stale snapshots; do not use them in your own integrations, requests, or documentation.| Avoid | Why | Use instead |
|---|---|---|
member role | The member organization role is retired (deprecated 2026-06-20). It is not a current first-class role; it still leaks in a no-filter member list and in the invitation CHECK constraint, but it grants nothing on the gated surfaces. Composer, Assistant, schedules, and managed knowledge all require owner or admin. | The owner and admin roles — see Roles & permissions and Organizations, roles & membership. |
X-Authorization header | This header does not exist and is read nowhere in the backend. Sending it authenticates nothing. Both SDKs send Authorization: Bearer. | Authorization: Bearer mx_live_… (or the alternative X-API-KEY) plus X-Organization-ID — see Authentication. |
X-Organization-Id (lowercase d) | The org-context header name is case-significant in code; the canonical spelling capitalizes ID. | X-Organization-ID — see Org context & X-Organization-ID. |
workflow:updated / workflow:deleted Redis channel | The realtime server subscribes to these literal Redis channels, but the backend publishes workflow:{id}:changes, so this bridge never fires. Do not treat it as the external-sync mechanism. | The Socket.io workflow:external-sync event — see Socket.io collaboration events and Realtime co-editing & external sync. |
nodes:delete (plural) Socket.io event | The UI emits nodes:delete, but only the singular node:delete handler is registered server-side, so the plural event has no effect. | node:delete (singular) — see Socket.io collaboration events and Known limitations. |
pip install modulex-integrations[all] / [github,slack] extras | These install extras are empty (all=[], no per-tool extras), so they emit pip warnings and install only the core package. | Install the core package and let integrations load at runtime — see Installing & using integrations. |
[ghost] integrations canvas, cogmento, help_scout, medium | These names exist only in a stale vendored manifest and have no source behind them. | Browse the live catalog of 175 integrations — see Integration catalog. |
| ”136 integrations” | A stale count from an out-of-date vendored manifest. | 175 integrations — see Integrations overview. |
Legacy LLM-only POST /workflows/run (“agentic mode”) | The legacy LLM-only request mode on the run endpoint now returns HTTP 410 Gone. | Use the Assistant (assistant.chat) instead — see How the Assistant works. |
A
One callable action declared in an integration’s
manifest.py. The action’s
output shape is not declared here — it is derived from the @tool function’s
return annotation. Action names match ^[a-z][a-z0-9_]*$. See
Manifest & schema contract.A live organization role with elevated permissions. Together with
owner, it is one of the two current roles, and it is required to use Composer, the
Assistant, schedules, and managed knowledge. See
Roles & permissions.One of the nine node types. An autonomous step that can call tools and
loop until it decides it is done. See Agent node.
The canonical name for the text-to-workflow agent: it turns a plain-English description
into a complete, editable workflow graph. The backend router
and surface are
/composer.See AI Composer and AI Composer in the builder.A user API key with the prefix
mx_live_. Send it as Authorization: Bearer mx_live_…
or, alternatively, as X-API-KEY: mx_live_…. Any bearer token that does not start
with mx_live_ is treated as a Clerk JWT. See
Authentication and Auth model: JWT vs API key.The point at which an agent stops before a sensitive action and waits for a person to
approve it. Approval is enforced by the tool-execution gating policy and is a
human-in-the-loop interaction. See
Human-in-the-loop.
The workflow-independent agentic chat: it searches your connected tools, decides next
steps, drafts outputs, calls tools, and pauses for approval. It has no workflow-editing
tools (that is the AI Composer). The backend router and profile are
See Assistant overview and Assistant.
assistant.The home page tile calls this “Deep Agentic Assistant”. The documentation standardizes on
Assistant.
The discriminated union (on
auth_type) of the six auth variants an
integration manifest may expose. See
Manifest & schema contract.The auth-variant discriminator in a manifest: one of
oauth2, bearer_token, api_key,
modulex_key, custom, internal (six schema variants).B
The exception the credit gate raises when a managed call is
denied. It carries a
DenialEnvelope, an HTTP status, and headers, and
is serialized to the flat envelope shape (no detail wrapper). See
Errors & status codes and Usage gating & limits.Connecting your own model, tool, or vector-store provider accounts so that usage is billed
directly by that provider, with no ModuleX markup. BYOK usage is not metered in
credits — it is tracked for analytics only. There is no
feature.byok
entitlement; BYOK is ungated.This is the alternative to ModuleX-managed usage.
See LLM providers, External knowledge providers,
and Credits & metering.C
LangGraph state persistence. The checkpointer is always Postgres (
AsyncPostgresSaver,
forced regardless of input). A thread is identified by config.configurable.thread_id;
see thread_id. See Workflow engine & nodes.A text segment of a document with a vector embedding
(
Vector(1536)). Chunks are the unit that retrieval searches over. See
Managed knowledge (modulexdb).The user-auth bearer token used by the app (anything that does not start with
mx_live_), verified against Clerk’s JWKS. The programmatic alternative is an
API key. See Auth model: JWT vs API key.The shared chat row backing both AI Composer and the
Assistant (table
composer_chats). Its id equals the LangGraph
thread_id. The kind field (composer or assistant) decides which
surface a chat belongs to. See Data model reference.One of the nine node types. Branches on an expression, an LLM decision, or
loops over data. See Conditional node.
A stored, encrypted auth record linking an organization to an
integration; identified by
credential_id. See
Credentials & OAuth2 and Managing credentials.The unit of managed usage billing.
1000 credits = 0.001. Each organization
receives a monthly credit allowance from its plan; when
that is exhausted, a paid org with overage enabled spends down its
wallet. BYOK usage is not charged in credits.
See Credits & metering.
An organization’s monthly credit grant from its plan.
The credits/rate-limit values come from
subscription_plans.json, which is canonical:
Free = 1,500 (one-time, trial), Pro = 25,000 monthly, Max = 100,000 monthly,
Enterprise = unlimited.D
The flat billing, credit, rate, and quota denial body. It is not wrapped in This is “shape D” of the four ModuleX error envelopes, and it is live on the run,
Composer, Assistant, and managed-knowledge surfaces. On plain CRUD and org-settings routes,
a 402/403/429 carries only the
detail:{"detail": …} shape — it is not a DenialEnvelope. See
Errors & status codes and Usage gating & limits.An uploaded file in a knowledge base;
status is one of pending,
processing, completed, or failed. The upload size cap is a plan
entitlement, not a fixed 50 MB limit. See Managing documents.E
A connection between two nodes in a workflow graph.
The virtual
__start__ (→ START) and __end__ (→ END) endpoints must not appear in
the nodes[] array. See Variables & references.A monotonically increasing integer on a workflow, bumped on each successful Composer edit.
See Versioning & history.
A per-plan limit or flag in
subscription_plans.json. null means unlimited
(the check is skipped), 0 blocks, and an absent key means the feature is not metered. See
Usage gating & limits.An operator-supplied secret or setting under a manifest auth schema. Unlike a
ParameterDef, an EnvVar’s required field defaults to True. See
Manifest & schema contract.F
The parse → chunk → embed → store pipeline for an uploaded document.
Managed ingest reserves
FILE_INGEST_BASE = 1 credit. See
Build a RAG knowledge base.A registry function callable from a function node. There are exactly four
built-ins:
http_request, send_webhook, validate_schema, and validate_workflow_schema.
See Function node.One of the nine node types. Runs a built-in function such
as an HTTP request, a webhook, or schema validation. See Function node.
G
The synchronous admission gate run before any database write on managed-usage surfaces.
It reserves credit and raises
BillingDenied on denial. It is
live on the run, Composer, Assistant, and managed-knowledge surfaces, and is part of the
reserve → charge → settle credit lifecycle. See Usage gating & limits.One of the nine node types. Validates content with JSON-schema, regex, PII, and
placeholder hallucination checks, with
on_failure in {block, warn, transform, route}. See
Guardrails node.H
A
{"type": "heartbeat"} keepalive injected every 15 seconds on the
SSE run stream. See SSE run streaming.The pattern where an agent or workflow pauses to ask a person a structured question, then
resumes once the person answers. In Composer and the Assistant the pause is a LangGraph
interrupt(envelope) answered through /resume; in a workflow it is an
interrupt node. The question is a UserInputRequest
(single_choice, multi_choice, yes_no, free_text, or credential_request) and the
answer is a UserInputResponse. See Human-in-the-loop (HITL) resume and
Human-in-the-loop.I
A connector to an external service. One integration exposes many tools (callable
actions). ModuleX ships 175 integrations.See Integrations overview and Integration catalog.
The single Pydantic contract every integration’s
manifest.py must satisfy. It forbids
unknown fields (extra="forbid"), so a typo fails at import time. Its integration_type is
always "tool". See Manifest & schema contract.One of the nine node types. Pauses a workflow run via LangGraph
interrupt(value) to await a resume value; it is not retry-wrapped. Distinct from the
Composer/Assistant HITL interrupt, which uses the same LangGraph
primitive on a different surface. See Interrupt node (HITL).K
Company knowledge connected to chats and workflows. ModuleX retrieves relevant context
automatically using retrieval-augmented generation.See Knowledge & RAG and Knowledge overview.
The home page chip reads “Knowledges” (plural). The documentation standardizes on the
singular Knowledge.
A
knowledge_bases row with its own embedding and chunking configuration — the unit that
retrieval searches over. The API router prefix is /knowledge-bases.A native (managed) KB has embedding_config.integration_name == "modulexai" and is
served by the modulexdb provider; its retrieval and ingest are billed in
credits. A BYOK KB uses your own vector store and
is uncosted.See Managed knowledge (modulexdb) and Knowledge providers.One of the nine node types. Retrieves from a knowledge base
inside a workflow; its
output_format is chunks, context, or both. See
Knowledge node.L
The discriminator on a
DenialEnvelope that maps to an HTTP status:
rate → 429, quota → 403, credit → 402, wallet → 402. See
Errors & status codes.One of the nine node types. Calls a language model with prompts, variables, and
optional structured output. See LLM node.
A
for, foreach, or while construct, expressed via an edge condition of type loop or a
conditional node. See Conditional node.M
The product and brand. The legal entity is ModulexAI, LLC, a Delaware LLC; “the Service”
is the legal umbrella for the ModuleX websites, applications, APIs, and related services. See
Why ModuleX.
The default alternative to BYOK: your calls run through
ModuleX-provisioned providers and are billed in credits. On the wire the
managed provider is
modulexai (LLM and tools) or modulexdb (knowledge). See
ModuleX-managed models and Credits & metering.The monthly billing-bucket integer,
year*12 + (month-1), that partitions paid credit usage
per period. Free orgs return 0. See Credits & metering.N
One step in a workflow graph. Every node writes its result into
run state under its own
id. See
Workflow engine & nodes.One of the nine node kinds in the
NodeType enum. Each is documented on its own page:See the Node types overview.O
When a HITL credential request opens an OAuth flow, the callback
re-runs the credential guard and resumes the chat without a manual
/resume call. See
Using tools.The tenant and billing unit. Every managed-usage row, plan,
wallet, and knowledge base is org-scoped, and every
org-scoped request must send the
X-Organization-ID header. See
Organizations, roles & membership.Spending beyond the plan credit allowance, funded by the
wallet. It is paid-plan only and toggled by
extra_usage_enabled. See
Wallet & top-ups.A live organization role with full permissions. With
admin, it is one
of the two current roles required on the gated surfaces. See
Roles & permissions.P
A single parameter of an
ActionDefinition: type in
{string, integer, number, boolean, array, object}, a description, an optional default, and a
required field that defaults to False (the opposite of EnvVar). See
Manifest & schema contract.A subscription level: Free, Pro, Max, or Enterprise (slugs
free, pro,
max, enterprise). Each plan sets the credit allowance, rate limits,
and entitlements.The agent profile derived from a chat’s
kind — composer or assistant —
which selects the tools, middleware, and subagents for that turn. See
How the Assistant works.R
How a state field merges updates:
none replaces, add does a smart
array or operator-add merge, and update does a dict-merge. See
Variables & references.The template syntax that pulls a prior node’s value into a later node, for example
{{extract_topic.result}}. The array-spread variant is {{...nodeId.path}}. See
Variables & references.A search or retrieve call against a knowledge base. Managed retrieval
reserves
RETRIEVAL_BASE = 1 credit before embedding. See
Knowledge & RAG.The caller’s organization role. The live roles are
owner and
admin only; the member role is retired. Composer, the
Assistant, schedules, and managed knowledge require owner or admin. See
Roles & permissions.A single workflow or agent execution. The identifier called “run id” actually refers to
three distinct identities, and you must not assume one for another.See Workflows & runs and Realtime overview.
The events that signal a paused run has continued under a new
run_id:
run_resumed (agent) and resumed (workflow). See Human-in-the-loop (HITL) resume.S
API responses are snake_case JSON (Pydantic v2 default; no global camelCase alias). The
JavaScript SDK accepts camelCase params and converts them to snake_case on the way out, but
its responses stay snake_case (
run_id, created_at); the Python SDK is snake_case both
ways. See SDKs overview.The streaming transport for runs. Each run event is
data: <json>\n\n with no event:
line — the discriminator is the type key inside the JSON (metadata, node_update,
interrupt, done, error, and so on).See SSE run streaming and Realtime overview.The dynamic run-state dictionary. One field is auto-added per node
id (type Any) for
streaming, alongside any user-defined and loop fields. See
Variables & references.A Composer-only sub-agent (
integration-resolver, credential-resolver). The Assistant has
no subagents. See How the Assistant works.The SDK resource for subscription lifecycle. It exists in the Python SDK only; the
JavaScript SDK has no
subscriptions methods. See SDK ⇄ API parity matrix
and Subscriptions & Stripe.T
The LangGraph checkpoint thread identifier, equal to the
ComposerChat id.
Unlike a per-execution run_id, thread_id is stable across an entire
conversation. See Workflows & runs.A single callable action exposed by an integration. ModuleX advertises
600+ tools across its 175 integrations. See Tool node and
@tool function contract.
One of the nine node types. Calls one integration tool. See
Tool node.
One of the nine node types. Reshapes, maps, and combines data between steps. See
Transformer node.
One user message resulting in one agent run. Billing charges exactly one run
credit per turn; a resume re-enters through
/resume rather than /chat and
mints a new run_id. See How the Assistant works.U
The HITL question and answer payloads. A
UserInputRequest is
discriminated on kind (single_choice, multi_choice, yes_no, free_text,
credential_request); a UserInputResponse is discriminated on kind
(single_choice, multi_choice, yes_no, free_text, credential_added,
credential_failed, skipped). Each pair is bound by a request_id. See
Human-in-the-loop (HITL) resume.W
The prepaid balance an organization spends after its plan
credit allowance is gone (
org_wallets). The balance may go negative,
and it supports manual top-ups and auto-top-up. See Wallet & top-ups.The editable graph of nodes and edges that connects tools, data, and agents;
the backend type is
WorkflowDefinition. A WorkflowDefinition carries metadata, config,
state_schema, nodes[], edges[], and an entry_point (default "__start__"). The visual
edit surface is the Workflow Builder. See
Workflows & runs and Workflow engine & nodes.The visual canvas for building workflows, with realtime
collaboration. See Workflow builder overview.
The live Socket.io event that propagates external (REST) workflow changes to collaborators.
It is the canonical external-sync mechanism — not the dead
workflow:updated Redis
channel. See Socket.io collaboration events and
Realtime co-editing & external sync.X
The required header that selects the organization context for every
org-scoped endpoint. Note the capital
ID. A missing header returns 400. Both SDKs send
it automatically once an org is configured.See Org context & X-Organization-ID.Putting the canonical names together
The example below uses the canonical terms in the way the rest of the documentation does: authenticate with an API key asAuthorization: Bearer mx_live_…, pass the
X-Organization-ID header, and start a run of a saved
workflow. The operation is shown once, three ways — see
Run a workflow (REST + SDK) for the full walkthrough.
DenialEnvelope (402/403/429) if the
billing gate denies it, because POST /workflows/run is a managed
run surface. See Errors & status codes for how to branch on each
layer.
Looking for the plain-English version of these terms? Start with
Core concepts at a glance and How ModuleX works.