Skip to main content
This page collects behaviors and edge cases worth knowing so you can build with confidence. Each entry states what to expect and the recommended approach to take. If you hit something that is not on this list, check Errors & status codes and the Errors & troubleshooting help page first, then get in touch.
This is the developer-facing reference. For a plain-language version aimed at app users, see the help version.

Summary

Delete nodes one at a time

In the builder, remove selected nodes individually and confirm each is gone.

Refresh OAuth by reconnecting

To restore a lapsed OAuth2 credential, disconnect and reconnect it.

Composer, Assistant & schedules need owner/admin

These surfaces require the owner or admin role.

Confirm the annual total at checkout

The Stripe checkout total is authoritative — confirm it before subscribing annually.

Install tool dependencies directly

Install the base package, then add each tool’s required SDK.

External sync uses Socket.io

Listen for the Socket.io workflow:external-sync event for external edits.

Idempotency-Key and runs

Each run request starts a new run — guard against duplicates in your own code.

Builder & canvas

Delete nodes one at a time

When you select several nodes on the workflow canvas and delete them in a single action, remove them one at a time instead. After each deletion, confirm the node is gone before removing the next one.
Delete nodes one at a time, confirming each removal, rather than relying on a multi-select delete to remove every selected node in one step.
For the collaboration event reference and how external sync works, see Socket.io collaboration events and Realtime co-editing & external sync.

Credentials & OAuth

Refresh an OAuth connection by reconnecting

To restore a lapsed OAuth2 credential — for example when its access token has expired and cannot be renewed automatically — disconnect the credential and reconnect it. Reconnecting runs the full OAuth2 flow again and issues fresh tokens.
To restore an expired OAuth connection, disconnect the credential and reconnect it. This is the supported way to issue fresh tokens.
For how credentials are connected, scoped, and rotated, see Authentication & credentials and Managing credentials. When the Assistant needs a credential mid-task, it asks you to reconnect — see Using tools.

Roles & permissions

Composer, Assistant, and schedules need owner or admin

The live organization roles are owner and admin. The Composer, the Assistant, and schedule management require owner or admin; a request from another role receives a 403.
If a teammate cannot start the Composer, use the Assistant, or create a schedule, check that they are an owner or admin — promote them, or perform the action with an owner/admin account.
For the full permission model, see Roles & permissions, Organizations, roles & membership, and the Assistant’s Permissions & limits.

Billing & pricing

Confirm the annual total at checkout

When you subscribe annually, the total shown on the Stripe checkout page is authoritative. Confirm it before you complete the purchase rather than assuming the figure on a pricing table.
Always confirm the total shown at Stripe checkout before subscribing annually.
For the plan and pricing details, see Plans & pricing. For what consumes credits and how usage is metered, see Credits & metering.
Credit allowances and rate limits are unaffected. The credit allowances (Pro 5,000 / Max 20,000 per month) come from the authoritative plan configuration.

SDKs & integrations

Installing tool dependencies

ModuleX does not publish per-tool pip extras. Install the base package, then add the SDK each tool requires, based on that tool’s documented requirements.
Install the base package and add each tool’s required dependencies directly, rather than relying on a per-tool extra to pull them in.
Install
For how integrations are discovered and loaded, see Installing & using integrations. For the full inventory, see the Integration catalog, generated from the 175 live integrations.

Idempotency-Key and run de-duplication

Both SDKs can send an Idempotency-Key header, but it is not used to de-duplicate workflow runs — each run request starts a new run with its own run_id, so sending the same Idempotency-Key twice produces two distinct runs.
Do not use Idempotency-Key to make a run request safe to retry. Guard against duplicate runs in your own code — for example, only retry after confirming the first request did not start a run.
The per-execution run_id is also re-minted on every resume, so it is not stable across a paused-and-resumed conversation. For retry policy and error classes in the SDKs, see Errors & retries. For run-id identity in general, see Workflows & runs.

Realtime

External sync uses Socket.io

External edits — changes made through the REST API while collaborators have the canvas open — are delivered over the Socket.io workflow:external-sync event. That is the live external-sync mechanism.
If you are building or debugging realtime sync, listen for the Socket.io workflow:external-sync event.
For the complete event reference, see Socket.io collaboration events and Realtime co-editing & external sync. For the realtime model overview, see Realtime & collaboration model.

Edit history is managed in the builder

Workflow edits are versioned, and you read or revert them through the in-builder versioning and history controls rather than a separate programmatic API. See Versioning & history.
For the shared entities behind these behaviors — workflows, runs, credentials, and more — see the Data model reference.

Quick reference