Authentication
Stateway uses API keys for authentication. Every API request must include a valid API key in the X-API-Key header.
Processes
Stateway supports three formats for process definitions: BPMN 2.0 XML, JSON, and YAML. All three are parsed into the same internal model and run on the same engine. BPMN 2.0 XML is the canonical format — JSON and YAML express a subset of what it can model. They are convenience formats for the same concepts, never a superset with different semantics. See JSON/YAML vs BPMN — Known Limitations for what BPMN can express that JSON/YAML cannot.
Supported Elements & Fields
{/* GENERATED by scripts/export-element-support.ts — do not edit by hand.
Credentials
Stateway provides an encrypted credential store so you can reference secrets — API tokens, access keys, passwords — in process definitions without embedding them in plaintext.
Service Tasks
Service tasks (serviceTask) make HTTP calls to external services, enabling integration with any REST API. They support configurable headers, input/output mapping, and two execution modes: synchronous and asynchronous.
Human Tasks
Human tasks (userTask) pause process execution until a user manually completes them. They are the primary mechanism for involving people in automated workflows.
Instances
A process instance is a running execution of a process definition. This guide covers how to start, monitor, suspend, resume, and terminate instances via the API.
Instance Recovery
When an automated task fails, a process token ends up in the wrong element, or you need to reprocess a case from scratch, Stateway provides targeted recovery operations that let you intervene without recreating the entire instance.
Events and Signals
Stateway supports two ways to inject external events into running process instances: instance events (targeted at a single instance) and broadcast signals (fan-out to all waiting instances across the tenant).
Decision Models
Stateway includes a built-in decision engine that evaluates Decision Model (DMM) tables. Decisions can be evaluated standalone via the API or embedded in processes via businessRuleTask elements.
Timers
Timer events pause process execution until a specified time condition is met. Stateway supports three ISO 8601 timer patterns: duration, date, and cycle.
Webhooks
Stateway sends outbound HTTP notifications (webhooks) to your endpoints when process events occur. Webhooks enable real-time integration with external systems without polling.
Multitenancy
Stateway implements multitenancy by API key. Every resource is isolated per tenant, and the API key automatically handles tenant resolution.
MCP
Stateway exposes a Model Context Protocol (MCP) server that lets LLMs and AI agents interact with the BPMN engine through native tool calling. Instead of crafting raw HTTP requests, agents discover and invoke typed tools — the MCP server translates each call into the appropriate Stateway API operation.
File Variables
Process instances hold data in variables. POST /v1/instances//variables — the endpoint you'll typically use to read and write them by hand — enforces a payload cap of 5 MB serialized (MAXVARIABLESPAYLOAD_BYTES) on the instance's full variables blob (existing variables merged with the patch you send), not just the patch itself. Embedding a binary file as base64 in a variable counts fully against that budget and inflates every payload that touches the instance through this endpoint — the variables blob, audit snapshots, webhook deliveries.