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.A
manifest type
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.org role
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.node type
One of the nine node types. An autonomous step that can call tools and
loop until it decides it is done. See Agent node.
product surface
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.auth credential
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.agent capability
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.
product surface
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.
manifest type
The discriminated union (on
auth_type) of the six auth variants an
integration manifest may expose. See
Manifest & schema contract.enum
The auth-variant discriminator in a manifest: one of
oauth2, bearer_token, api_key,
modulex_key, custom, internal (six schema variants).B
exception
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.usage mode
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
engine
Checkpoint-thread state persistence. A thread is identified by its
thread_id;
see thread_id. See Workflow engine & nodes.knowledge type
A text segment of a document with the embedding vector.
Chunks are the unit that retrieval searches over. See
Managed knowledge (modulexdb).
auth credential
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.data model
The shared conversation store backing both AI Composer and the
Assistant. Its
id is the conversation
thread_id. The kind field (composer or assistant) decides which
surface a chat belongs to. See Data model reference.node type
One of the nine node types. Branches on an expression, an LLM decision, or
loops over data. See Conditional node.
data model
A stored, encrypted auth record linking an organization to an
integration; identified by
credential_id. See
Credentials & OAuth2 and Managing credentials.billing unit
required
The unit of managed usage billing.
100 credits = 0.01. 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.
entitlement
An organization’s monthly credit grant from its plan.
The credits/rate-limit values come from the plan configuration, which is canonical:
Free = 300 (one-time, trial), Pro = 5,000 monthly, Max = 20,000 monthly,
Enterprise = unlimited.
D
error shape
required
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.knowledge type
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
engine
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.data model
A monotonically increasing integer on a workflow, bumped on each successful Composer edit.
See Versioning & history.
billing
A per-plan limit or flag in the plan configuration.
null means unlimited
(the check is skipped), 0 blocks, and an absent key means the feature is not metered. See
Usage gating & limits.manifest type
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
knowledge
The parse → chunk → embed → store pipeline for an uploaded document.
Managed ingest reserves
FILE_INGEST_BASE = 1 credit. See
Build a RAG knowledge base.engine
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.node type
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
billing
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.node type
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
SSE event
A
{"type": "heartbeat"} keepalive injected every 15 seconds on the
SSE run stream. See SSE run streaming.agent flow
required
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 an
interrupt 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
product
A connector to an external service. One integration exposes many tools (callable
actions). ModuleX ships 175 integrations.See Integrations overview and Integration catalog.
manifest type
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.node type
One of the nine node types. Pauses a workflow run with an
interrupt to await a resume value; it is not retry-wrapped. Distinct from the
Composer/Assistant HITL interrupt, which uses the same
primitive on a different surface. See Interrupt node (HITL).
K
product
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.
data model
required
A knowledge base 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.node type
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
error field
The discriminator on a
DenialEnvelope that maps to an HTTP status:
rate → 429, quota → 403, credit → 402, wallet → 402. See
Errors & status codes.node type
One of the nine node types. Calls a language model with prompts, variables, and
optional structured output. See LLM node.
engine
A
for, foreach, or while construct, expressed via an edge condition of type loop or a
conditional node. See Conditional node.M
brand
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.
product surface
The feature that publishes your organization’s live workflows, Files, and Knowledge as tools
on a private Model Context Protocol server that external AI
clients (Claude Code, Cursor, Codex) connect to over Streamable HTTP. Here ModuleX is the
server and the client is the consumer — the reverse of a
custom MCP server, where ModuleX is the client of an
external server. Clients authenticate with a server-scoped
mx_mcp_ key. See
ModuleX MCP.usage mode
required
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.billing
The monthly billing-bucket integer,
year*12 + (month-1), that partitions paid credit usage
per period. Free orgs return 0. See Credits & metering.N
engine
One step in a workflow graph. Every node writes its result into
run state under its own
id. See
Workflow engine & nodes.enum
required
One of the nine node kinds in the
NodeType enum. Each is documented on its own page:See the Node types overview.O
agent flow
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.tenancy
required
The tenant and billing unit. Every managed-usage record, plan,
wallet, and knowledge base is org-scoped, and every
org-scoped request must send the
X-Organization-ID header. See
Organizations, roles & membership.billing
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.org role
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
manifest type
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.billing
required
A subscription level: Free, Pro, Max, or Enterprise (slugs
free, pro,
max, enterprise). Each plan sets the credit allowance, rate limits,
and entitlements.agent
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
engine
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.engine
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.knowledge
A search or retrieve call against a knowledge base. Managed retrieval
reserves
RETRIEVAL_BASE = 1 credit before embedding. See
Knowledge & RAG.auth
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.execution
required
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.
SSE event
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
convention
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.transport
required
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.engine
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.agent
A Composer-only sub-agent (
integration-resolver, credential-resolver). The Assistant has
no subagents. See How the Assistant works.SDK
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
execution
The conversation 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.product
A single callable action exposed by an integration. ModuleX advertises
600+ tools across its 175 integrations. See Tool node and
@tool function contract.
node type
One of the nine node types. Calls one integration tool. See
Tool node.
node type
One of the nine node types. Reshapes, maps, and combines data between steps. See
Transformer node.
agent
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
HITL payload
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
billing
The prepaid balance an organization spends after its plan
credit allowance is gone. The balance may go negative,
and it supports manual top-ups and auto-top-up. See Wallet & top-ups.
data model
required
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.product surface
The visual canvas for building workflows, with realtime
collaboration. See Workflow builder overview.
Socket.io event
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 pub/sub
channel. See Socket.io collaboration events and
Realtime co-editing & external sync.X
header
required
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.