Data model reference

This page is the reference for the objects you meet through the ModuleX API and SDKs: what each one is, the fields it returns, how the objects relate, and the identifier conventions you need to join them correctly. It describes the data model as it is exposed on the API — internal storage, indexing, and database tuning are out of scope.

Wire responses are snake_case JSON. The official SDKs convert between camelCase and snake_case at their own boundary, so a field shown here as edit_version surfaces as editVersion in the JavaScript SDK and stays edit_version in the Python SDK and raw REST. See /sdks/parity.

Entity map

Two objects sit at the centre of the model — the organization and the user. An organization is the tenant and billing unit; a user is a person. Every workflow, run, credential, knowledge base, chat, and wallet belongs to exactly one organization. Tenant isolation is enforced per request: you select the active organization with the X-Organization-ID header, and every response is scoped to it. See /security/org-context.

Core objects and how they relate

Conventions you must know first

Timestamps are UTC

Treat every ModuleX timestamp as UTC and normalize on your side. A timezone-aware value emits an offset on the wire; a naive one does not — so normalize rather than comparing the raw strings.

Metadata fields use prefixed names

Free-form metadata surfaces under prefixed field names rather than a bare metadata key: doc_metadata on documents, chunk_metadata on chunks, and extra_metadata on wallet ledger entries and catalog entries.

Reference credentials by credential_id

A credential is referenced everywhere — in the API, the SDKs, and from a native knowledge base — by its credential_id, a unique UUID. Always join on credential_id.

Organizations, users, and access

object

The tenant and billing unit. Every managed-usage record, plan, wallet, workflow, and knowledge base is scoped to one organization. Selected per request by the X-Organization-ID header. See /concepts/organizations-roles.

Show key fields

string (uuid)

required

The organization id.

string

required

Unique URL-safe identifier.

string

required

Display name.

string | null

The linked Stripe customer, set once the org has a billing relationship.

object

Free-form organization settings.

boolean

Trial-eligibility flag; never cleared once set.

object

The join between a user and an organization, carrying the user’s role.

Show key fields

string (uuid)

required

The member.

string (uuid)

required

The organization.

string

required

The live roles are owner and admin only.

The member role is retired (deprecated 2026-06-20). It is no longer a current first-class role: Composer, Assistant, Knowledge, and schedule operations require owner or admin. Treat only owner and admin as valid roles. See /security/roles-permissions.

object

An API key with the prefix mx_live_. The plaintext key is shown once at creation; afterwards only a hint is kept for display, and the key itself is never returned again.

Show key fields

string (uuid)

required

The key id.

string (uuid) | null

The org the key is scoped to. Null means the key works across all of the creating user’s organizations — in which case you must still pass X-Organization-ID to choose the active org per request.

string

required

A label for the key.

string

The first few characters of the key, for display.

integer

Per-key request limit. Default 60.

boolean

Whether the key is usable.

string (timestamp) | null

Optional expiry.

string (timestamp) | null

Last successful use.

Send the key as Authorization: Bearer mx_live_… together with X-Organization-ID. The backend also accepts X-API-KEY: mx_live_…. See /api-reference/authentication.

Workflows

A workflow is the editable graph — nodes, edges, and run state. A run is one execution of a workflow. The two are distinct objects; see /concepts/workflows-and-runs for the conceptual model and /concepts/workflow-engine for how the graph executes.

object

The durable, editable workflow record.

Show key fields

string (uuid)

required

The workflow id.

string (uuid)

required

Owning org.

string (uuid) | null

User who created it; nulled if that user is deleted.

string

required

Display name.

string | null

Description.

string

Semantic version string. Default "1.0.0". This is a label, distinct from edit_version below.

array

Tag list.

string

One of draft, active, archived. Default draft.

string

One of private, organization, public, system. Default organization.

object

required

The complete workflow definition — see below.

object

Default run input.

object

Run configuration.

integer

required

A monotonically increasing edit counter. Default 0. Distinct from version. See the version planes note below.

string (uuid) | null

Most recent editor.

string (timestamp) | null

Most recent edit time.

string (uuid) | null

The currently live deployment snapshot, if any.

The `workflow_schema` object

workflow_schema holds the complete workflow definition. The name, description, version, and tags fields above mirror values inside workflow_schema.metadata; the schema is the source of truth.

object

Show fields

object

Name, description, version, tags, and other workflow-level metadata.

object

Workflow-level run configuration.

object

The dynamic run-state shape. One field is auto-added per node id (type Any) for streaming, alongside any user-defined state fields and loop fields. Each field carries a reducer: none (replace), add (append/merge arrays), or update (dict-merge).

array

required

The graph steps. Each node has an id, a type (one of the nine node types), and type-specific config. Every node writes its result into run state under its own id.

array

required

Connections between nodes. The virtual nodes __start__ and __end__ must not appear in nodes[] — they exist only as edge endpoints.

string

The first node. Default "__start__".

array

Optional declared run inputs.

object

The {x, y} canvas position of the __start__ node.

The nine node types are llm, tool, agent, function, conditional, interrupt, transformer, guardrails, and knowledge. Nodes reference earlier results with the template syntax {{nodeId.path}}. See /workflow-builder/nodes/overview and /workflow-builder/variables-and-references.

workflow_schema round-trips a fixed set of fields. When the realtime co-editing server saves, it keeps a fixed set of top-level fields — metadata, config, state_schema, nodes, edges, entry_point, input_parameters, end_points, start_position — and does not persist top-level keys outside that set. Do not assume an arbitrary key you add at the top level of workflow_schema will survive a reload. See /workflow-builder/realtime-coediting.

Edit history and the two version planes

Every edit is recorded, and there are two different counters both called “version”.

object

One append-only record per accepted flush of edits.

Show key fields

string (uuid)

required

The history record id.

string (uuid)

required

The workflow.

integer

required

The edit_version this flush produced — unique per workflow; a duplicate flush is a no-op.

string (uuid)

required

The editor.

array

required

The original client RFC-6902 JSON Patch operations for this flush.

string (timestamp)

required

When the flush was recorded.

Two planes, both called “version”. During live editing the realtime room keeps an in-memory counter that increments once per accepted client operation. The persisted edit_version increments once per flush, and a single flush carries many operations. So after N operations and one flush, the in-memory counter has advanced by N while the persisted edit_version has advanced by 1. Clients see the in-memory plane through live acknowledgements and the persisted plane through the saved record — do not copy one over the other. See /workflow-builder/versioning-history and /realtime/presence-locks.

object

An immutable snapshot of a workflow taken at deploy time. A run can be tied to the deployment it was launched from.

Show key fields

string (uuid)

required

The deployment id.

string (uuid)

required

The source workflow.

object

required

The frozen workflow definition at deploy time.

string

The version label captured at deploy.

string | null

Optional note.

string (uuid) | null

Deploying user.

string (timestamp)

required

Deploy time.

Runs

object

The durable system-of-record for every real run. This is the object you query for run history and status.

Show key fields

string (uuid)

required

The run record’s id (UUID).

string

required

The durable, unique run identifier — the stable id to reference a run by. See the identity section below.

string (uuid)

required

Owning org.

string (uuid) | null

Source workflow; nulled if the workflow is deleted.

string

How the run was started: manual, api_key, scheduled, or composer. Default manual.

string (uuid) | null

Triggering user, where applicable.

string (uuid) | null

The deployment snapshot this run used, if launched from a deployment.

string | null

The conversation/checkpoint thread for this run.

string

required

One of pending, running, succeeded, failed, cancelled, interrupted, skipped. Default pending.

string | null

Failure detail, if any.

string (timestamp) | null

Run start.

string (timestamp) | null

Run completion.

number | null

Wall-clock duration.

object | null

The input the run was launched with.

object | null

A summary of the run output.

Schedules add two more objects. A schedule defines a recurring trigger (schedule_type is interval or cron), and each fire produces a schedule-run record carrying its own id, run_id, status, and timing. See /workflow-builder/execution/schedule and /guides/schedule-a-workflow.

Identifiers and the three run-id identities

The single most important identity hazard in ModuleX: the word “run id” refers to different things at different layers. A reader must not assume one identity.

The three identities
The SDK-return hazard

string

The identifier used for SSE streaming and run status of one execution. For agentic surfaces (Composer and Assistant), a new run_id is minted on every resume — the chat keeps the same thread_id, but each turn or resume has its own run_id. So this run_id is not stable across a conversation.

string

The conversation/checkpoint thread. For chat-backed agents, thread_id equals the chat’s id and is stable across the whole conversation.

string

The durable run identifier — the unique run_id on the run record. A resume reuses the same run_id (the record is updated in place). This is the stable, unique identifier the docs reference when they say “a run”.

Because the SDKs expose runs through several resources, three different SDK return values can all be called “the run id”. Keep them straight:

SDK return	What it is
Execution `run_id` (execution methods)	The per-execution streaming/status id.
Run record `id` (run-record lookup)	The run record’s UUID id.
Scheduled-run `id` (schedule-run methods)	The schedule-run record’s id.

When you persist a reference to a run, persist the durable run_id, not a per-execution id, and not a record id from another resource. See /sdks/parity.

Idempotency-Key does not de-duplicate runs. The SDKs send the header, but ModuleX assigns its own run_id per execution and does not use the header for run dedup. Sending the same Idempotency-Key twice will start two runs. See /sdks/errors-retries.

Credentials

A credential is a stored, encrypted authentication record linking an organization to an integration. See /concepts/credentials-oauth, /integrations/authentication, and /integrations/managing-credentials.

object

Show key fields

string (uuid)

required

The credential’s unique id. Use it in the API, the SDKs, and all references.

string (uuid)

required

Owning org.

string

required

The integration this credential is for.

string

required

One of tool, llm_provider, knowledge_provider.

string

required

A human label.

string

required

The auth variant. See the note below on the allowed set.

object | null

Discovered tool schemas and similar metadata.

string (uuid) | null

Creating user. A user cannot be deleted while they still own credentials.

boolean

Whether the credential currently authenticates.

boolean

Whether this is the default credential for its integration in the org.

string (timestamp) | null

Expiry, where the auth type has one.

The credential’s secret material is not returned by the API — it is stored encrypted at rest and only decrypted server-side at execution. See /security/data-encryption for how that protection works.

The auth_type value you receive is one of six variants — oauth2, bearer_token, api_key, modulex_key, custom, internal. Author new credentials against this set. See /integrations/building/manifest-schema.

Managed-key credentials are indirected

A modulex_key credential does not expose a provider API key. You reference the credential, and ModuleX resolves the underlying managed key on your behalf, runs it, and meters the usage. This is how ModuleX-managed (non-BYOK) usage is billed in credits. See /billing/credits.

Knowledge

A knowledge base is the unit retrieval-augmented generation searches over. It holds documents, which are split into chunks, which carry vector embeddings. See /concepts/knowledge-rag, /platform/knowledge/overview, and /platform/knowledge/managed.

object

Show key fields

string (uuid)

required

The knowledge base id.

string (uuid)

required

Owning org.

string (uuid) | null

For a native (managed) KB, the credential backing it. A native KB is one whose embedding provider is the managed provider; its ingest and retrieval are billed in credits. BYOK knowledge bases are not credited.

string

required

Display name.

object

required

Per-KB embedding settings (provider, model, dimension).

object

required

Per-KB chunking settings: strategy (recursive, token, or simple), chunk_size, chunk_overlap, separators.

string

One of active, processing, error, archived. Default active.

object

An uploaded file in a knowledge base.

Show key fields

string (uuid)

required

The document id.

string (uuid)

required

Parent KB.

string

required

Original file name.

string

required

One of pdf, docx, doc, txt, md, html, csv, json, xlsx, pptx.

integer | null

File size.

string | null

A content fingerprint used for de-duplication.

string

One of pending, processing, completed, failed. Default pending.

integer

Number of chunks produced. Default 0.

integer

Total tokens. Default 0.

object

Free-form document metadata.

string (uuid)

required

Uploader. A user cannot be deleted while they still have uploaded documents.

object

A text segment of a document with its vector embedding.

Show key fields

string (uuid)

required

The chunk id.

string (uuid)

required

Parent KB.

string (uuid)

required

Parent document.

string

required

The chunk text.

vector | null

The vector embedding for the chunk.

integer

required

Position within the document.

object

Free-form chunk metadata.

The advertised “50MB” knowledge upload limit is not the enforced cap. The real upload cap is a plan entitlement that varies by plan. See /platform/knowledge/documents and /billing/usage-gating.

Billing, credits, and the wallet

Managed usage is priced in credits (100 credits =

1.00; 1 credit =

0.01). Each organization gets a monthly credit allowance from its plan; when the allowance is exhausted, a paid org with overage enabled spends down a prepaid wallet. See /billing/overview, /billing/credits, and /billing/wallet.

object

The prepaid balance an org spends after its plan allowance is gone. There is exactly one wallet per organization.

Show key fields

string (uuid)

required

The organization this wallet belongs to. One wallet per organization.

number

required

The current balance. May go negative.

boolean

Whether the org may spend beyond its plan allowance (overage). Paid plans only.

number | null

Balance at which auto top-up fires.

number | null

Auto top-up amount.

boolean

Set true after repeated auto top-up failures.

object

An append-only entry recording one wallet movement.

Show key fields

string (uuid)

required

The ledger entry id.

string (uuid)

required

The wallet’s org.

number

required

The signed movement (positive for credit, negative for debit).

string

required

One of topup, auto_topup, debit, refund, adjustment.

number | null

The balance after applying this entry.

string | null

For Stripe-funded movements. De-duplicated so a retried payment cannot double-credit.

object | null

Free-form metadata.

object

An append-only record of one managed-usage charge in credits.

Show key fields

string (uuid)

required

The usage record id.

string (uuid)

required

Charged org.

number

required

The credits charged.

string | null

One of run, llm, tool, file_ingest, embedding, retrieval.

integer | null

The billing-bucket integer that partitions paid usage per period.

string | null

The de-duplication key that prevents a double-charge on retry.

object | null

Per-record pricing audit detail.

string | null

The Composer chat this charge is attributed to, where applicable.

The plan catalog, the active subscription (with its subscription_status and an operations_suspended flag), and Stripe billing records round out the billing model. The subscriptions resource is Python-SDK-only — there is no JavaScript equivalent. See /billing/subscription-lifecycle and /sdks/parity.

What happens when you delete an object

Deletion behavior is the part that surprises people, so it is worth stating explicitly.

Deleting an organization

Removes all of its data — members, credentials, workflows, runs, chats, knowledge bases, and the wallet with its ledger.

Deleting a user

History is preserved. A run, workflow, or chat the user created keeps existing, with the creator link cleared.

Blocked deletes

A user who still owns credentials or uploaded documents cannot be deleted until those are removed first.

Append-only and system-managed objects

Some records are append-only history and never change in place — wallet ledger entries, credit-usage records, workflow edit history, and run records. Treat them as immutable history. Others are system-managed and should not be treated as durable user data: the integration catalog and the node-type builder metadata are regenerated on each deploy. By contrast, runs, the wallet ledger, and credit-usage records are durable systems-of-record and are never reset.

Things to get right

Reference credentials by credential_id

A credential is referenced everywhere — including from a native knowledge base — by its credential_id.

Persist the durable run_id

Of the three run identities, only the durable run_id is stable and unique across a run’s lifecycle. Per-execution run ids change on every resume.

Treat owner and admin as the only roles

The member role is retired. Anything that requires a writer requires owner or admin.

Expect snake_case on the wire and prefixed metadata fields

Raw API responses are snake_case; free-form metadata surfaces under names like doc_metadata, chunk_metadata, and extra_metadata.

Do not rely on Idempotency-Key to de-dup runs

The header is accepted but ignored for run dedup; ModuleX assigns its own run_id.

Workflows & runs

The conceptual model behind the workflow and run objects, including the run lifecycle.

Workflow engine & nodes

How the workflow_schema, nodes, edges, and run state execute.

Credentials & OAuth2

How credentials are stored, resolved, and encrypted.

Errors & status codes

The error-envelope shapes you get back when an operation is denied or fails.

Billing & credits

Data & limits

Guides

Power using

Entity map

Conventions you must know first

Organizations, users, and access

Workflows

The `workflow_schema` object

Edit history and the two version planes

Runs

Identifiers and the three run-id identities

Credentials

Managed-key credentials are indirected

Knowledge

Billing, credits, and the wallet

What happens when you delete an object

Deleting an organization

Deleting a user

Blocked deletes

Append-only and system-managed objects

Things to get right

Workflows & runs

Workflow engine & nodes

Credentials & OAuth2

Errors & status codes

​Entity map

​Conventions you must know first

​Organizations, users, and access

​Workflows

​The workflow_schema object

​Edit history and the two version planes

​Runs

​Identifiers and the three run-id identities

​Credentials

​Managed-key credentials are indirected

​Knowledge

​Billing, credits, and the wallet

​What happens when you delete an object

Deleting an organization

Deleting a user

Blocked deletes

​Append-only and system-managed objects

​Things to get right

​Related pages

Workflows & runs

Workflow engine & nodes

Credentials & OAuth2

Errors & status codes

Entity map

Conventions you must know first

Organizations, users, and access

Workflows

The `workflow_schema` object

Edit history and the two version planes

Runs

Identifiers and the three run-id identities

Credentials

Managed-key credentials are indirected

Knowledge

Billing, credits, and the wallet

What happens when you delete an object

Append-only and system-managed objects

Things to get right

Related pages