Skip to content

Processes REST API

/workflow/api/processes is the engine’s REST API for processes: start one, read it, list them, and send it the operator commands — the same operations the admin console and the MCP tools offer. It is built on the same application services, so a start over HTTP is the console’s “new process” (same idempotency, same disabled-definition rule, same flow authorization), a listing is the console’s listing, and a command is the same request the console and MCP send to the node that owns the process.

The machine-readable description is published with these docs: /openapi/eventconductor-api.yaml (OpenAPI 3.1, every /workflow/api/** endpoint). A build-time test regenerates it from the controllers and fails when the committed copy drifts, so it is the API the release actually serves.

Method and pathDoesAnswers
POST /workflow/api/processesStart {definitionId, businessKey?, variables?}201 + Location; 200 when the business key already names a process of that definition (and its businessKeyPolicy keeps it), or a startPolicy singleton skipped the start; 202 StartHeldBack when a startPolicy debounced or queued it; 429 + Retry-After when its throttle dropped it
GET /workflow/api/processesOne page of the listing (filters below)200 ProcessPage
GET /workflow/api/processes/by-key?businessKey=…The process with that business key (exact)200 Process
GET /workflow/api/processes/{id}The process, with its variables200 Process
GET /workflow/api/processes/{id}/stepsIts step executions, in creation order200 StepExecution[]
GET /workflow/api/processes/{id}/variablesIts variables, by name (a sensitive one reads ••••)200 {name: value}
POST /workflow/api/processes/{id}/variables/{name}/revealOne sensitive variable’s value {reason} — needs a workflow.security.sensitive.reveal-roles role; audited200 RevealedVariable; 403 without the role
GET /workflow/api/processes/{id}/logsIts log, oldest first200 LogEntry[]
POST /workflow/api/processes/{id}/cancelCancel (not a COMPLETED process)202
POST /workflow/api/processes/{id}/pausePause a PENDING or RUNNING process202
POST /workflow/api/processes/{id}/resumeResume a PAUSED process202
POST /workflow/api/processes/{id}/retryPick an ERROR or CANCELLED process up where it stopped202
POST /workflow/api/processes/{id}/restartRun an ERROR or CANCELLED process again from the beginning202
POST /workflow/api/processes/{id}/steps/{stepExecutionId}/retryRun one ERROR/TIMEOUT step execution again202
POST /workflow/api/processes/{id}/variablesChange a live process’s variables {set?, remove?, reason}202
POST /workflow/api/processes/{id}/steps/{stepExecutionId}/completeComplete a step execution by hand {variables?, reason}202
POST /workflow/api/processes/{id}/retry-from/{stepId}Run a live process again from one of its steps {reason}202
POST /workflow/api/processes/{id}/migrateMove a live process onto another version of its definition {targetVersion?, stepMapping?, variableMapping?, reason}202
POST /workflow/api/processes/{id}/migrate/dry-runThe plan of that migration, changing nothing {targetVersion?, stepMapping?, variableMapping?}200 MigrationPlan
POST /workflow/api/processes/{id}/updates/{name}Apply a declared update; body = its payload; Idempotency-Key, Prefer: wait=N200 ProcessUpdateResponse with result; 202 + Location past the deadline
POST /workflow/api/processes/by-key/updates/{name}?businessKey=…The same, finding the process by business keyas above
POST /workflow/api/definitions/{definitionId}/update-with-startUpdate the process with businessKey, starting it when there is none {businessKey, variables?, update, payload?}as above, with started
GET /workflow/api/updates/{updateId}One update, answered as its POST was (Prefer: wait=N long-polls)200 / 202 / its problem
GET /workflow/api/processes/{id}/updatesA process’s updates, oldest first200 ProcessUpdateResponse[]
GET /workflow/api/incidents?definitionId=…Failed steps of failed processes, grouped by definition, step and error family200 IncidentList
GET /workflow/api/incidents/{key}/processes?limit=…The failed steps (and processes) of one incident200 IncidentMember[]
POST /workflow/api/incidents/{key}/retryRetry every failed step of one incident {reason}202 IncidentRetryAccepted

A step that ran more than once has a row per run in /steps: a forEach iteration carries parentExecutionId (its container’s id) and itemIndex; a loop pass carries iteration (0 for the first run) and superseded: true once a later pass replaced it. Retrying an iteration retries its forEach, which re-runs only the failed and cancelled items.

What retry, restart, pause and resume do is described in Starting a process; the statuses in Process & Step Statuses.

Terminal window
curl -X POST https://engine.example.com/workflow/api/processes \
-H 'X-Api-Key: …' -H 'Content-Type: application/json' \
-d '{"definitionId": "order-fulfilment", "businessKey": "ORDER-1001",
"variables": {"orderId": "1001", "lines": [{"sku": "A", "qty": 2}]}}'
HTTP/1.1 201 Created
Location: /workflow/api/processes/5f0c…
{"id": "5f0c…", "definitionId": "order-fulfilment", "definitionVersion": 3, "name": "Order fulfilment",
"businessKey": "ORDER-1001", "status": "PENDING", "completionPercentage": 0,
"created": "2026-10-18T09:30:00.123", "started": null, "finished": null, "pausedAt": null,
"parentStepExecutionId": null, "variables": {"orderId": "1001", "lines": "[{\"sku\":\"A\",\"qty\":2}]"}}
  • Idempotent on the business key. The same businessKey and definitionId again answers 200 with the process that already has it — a retried request never starts a second process. The same key for another definition is 409. Without a business key every request starts a new process. A definition’s businessKeyPolicy can let a new run take the key once the previous one ended (or cancel a running one): then the same request starts a new run (201).
  • Flow control. A definition’s startPolicy decides first: the EventConductor-Flow-Control header says what it did (started, replaced, skipped); a held-back start answers 202 with {flowControl, businessKey, dueAt, detail} and no process yet; a dropped one 429 with Retry-After.
  • Chains. A process view carries continuedFrom, continuedAs and outcome (continued for a run a CONTINUE_AS_NEW handed over); by-key answers the run that holds the key now.
  • Variables are strings, as the engine keeps them: a string stays itself, any other JSON value is stored as its JSON text.
  • A traceparent (and optionally tracestate, baggage) header makes the process join the caller’s trace (workflow.tracing.join-caller-trace).
  • A paused definition still accepts the start: the process is created PAUSED. A disabled or archived one does not: 409.
  • To start a process and wait for its answer, use synchronous invocation instead.

GET /workflow/api/processes answers one page of processes, newest first, narrowed by every filter given (they combine with AND):

ParameterNarrows to
definitionIdprocesses of this definition
tagprocesses of the definitions carrying this tag (case-insensitive); a tag no definition carries lists nothing
statusany of these statuses — repeat it (status=ERROR&status=CANCELLED) or separate with commas; an unknown status is 400
from, tocreated at or after / at or before — an ISO date-time (2026-10-18T09:30:00) or a date (from = its first moment, to = its last), in the engine’s time zone
businessKeybusiness key contains this, case-insensitively
qname or business key contains this, case-insensitively
attr.<name>the search attribute equals this — exactly for a keyword or bool, as a case-insensitive substring for a text, numerically for a number, as a moment for a date; repeatable
attr.<name>.gt, .gte, .lt, .ltea number or date attribute is above / at least / below / at most this (a bare date as an upper bound is its last moment); a value that is neither a number nor a date is 400
querythe same conditions as text, joined by AND: customerId = "C-9" AND amount > 100; malformed is 400
page, sizezero-based page (default 0) and page size (default 20, 1–500)
{"content": [{"id": "5f0c…", "definitionId": "order-fulfilment", "name": "Order fulfilment",
"businessKey": "ORDER-1001", "status": "RUNNING", "completionPercentage": 40,
"created": "2026-10-18T09:30:00.123", "started": "2026-10-18T09:30:00.140", "finished": null}],
"page": 0, "size": 20, "totalElements": 1, "totalPages": 1}

page and size in the answer are the ones served: a page past the end is answered with the last real page. The listing carries no variables.

Every attribute condition is bound as a parameter; at most 10 per request. GET /workflow/api/processes/{id} carries the process’s searchAttributes by name.

Where it comes from — the same rule as the console’s Processes page. With the process index on (workflow.projection.enabled=true) a listing filtered only by q and search attributes is answered from the read model, which has seen every shard; any other filter is answered by the engine’s own store, because the index cannot apply it and a page that silently ignored a filter would be a wrong answer.

A command answers 202 Accepted with {processId, command, stepExecutionId} and a Location to the process. It is carried out asynchronously by the node that owns the process (its Kafka partition, its shard), under the process lock, by the same use case the console and MCP reach — read the process to see the outcome.

Before accepting, the API checks what a synchronous caller needs to know: the process exists (404) and its status allows the command (409, with processStatus in the body) — by the use case’s own rule, so a 202 is a command the engine will carry out. A step retry also checks the step belongs to the process (404), failed (ERROR/TIMEOUT) and that the process is not finished (409). In a sharded fleet with the process index on, a process another shard owns is found through the index and the command routed to its shard.

Set variables, complete a step and retry from a step change a live (RUNNING, PAUSED or ERROR) process by hand. Each needs a reason (400 without one), answers 202 with {processId, command, stepExecutionId, stepId}, and is carried out — and recorded, with the caller and the reason, in the process log — by the node that owns the process. Before accepting, the API checks with the engine’s own rules: 404 for an unknown process, step execution or step; 409 with the reason when the process or the step is not in a status the operation is done from, when a saga rollback is under way, for a retry from a step that has not run yet, or when another failure is not downstream of it. Semantics, locks and compensations: Operating running processes.

A sensitive variable reads •••• in every view; reading one is POST …/variables/{name}/reveal with a reason, for a caller holding one of workflow.security.sensitive.reveal-roles — 400 without a reason or for a variable that is not sensitive, 403 without the role (an API key alone never reveals), and every reveal and refusal is recorded in the process log.

POST /{id}/migrate moves a live process onto another version of its definition (targetVersion; absent for the definition as it is now), each step onto the target’s step of the same id or the one stepMapping names, setting variableMapping’s variables; reason mandatory. It is planned before it is accepted: 409 lists the problems that refuse it, 400 for a version that does not exist (or any version but the current one in memory mode), 404 for an unknown process. POST /{id}/migrate/dry-run answers the plan — fromVersion, toVersion, executable, the effective mapping, every step’s state and action (REMAP, KEEP_TASK, REDISPATCH, REARM, HISTORY, DROP, CARRY, ADD, ADD_PASSED) and the problems (ERROR refuses, WARNING is reported) — without changing anything; a process owned by another node is planned there (409 here). Semantics and rules: Migrating running processes.

The incidents endpoints group the failures waiting for an operator; a group retry is a RETRY batch operation over the incident — 202 with its batchOperationId, Location naming the batch — see Incidents.

An update is a validated write that answers with a result, declared in the definition’s updates — not an admin operation: it needs no reason and no operations role, only what reading or commanding the process needs (the definition’s requirements, with flow authorization on). The body is the payload, any JSON. The answer is 200 with {updateId, processId, name, status: COMPLETED, result, payload, requestedBy, requestedAt, completedAt, location} (payload with the update’s sensitive fields masked), or 202 + Location when Prefer: wait=N ran out first — the update still completes. Refusals: 400 (INVALID_PAYLOAD: not JSON or not what accepts allows), 404, 409 (NOT_ACCEPTING, the detail says why), 422 (REFUSED by a guard, or IDEMPOTENCY_KEY_REUSED), 500 (FAILED: an expression of the update failed) — in every case nothing changed, and a refusal the owner recorded is replayed to a retry with the same Idempotency-Key. Semantics: Updating running processes.

/workflow/api/batch-operations applies one command to every process a filter matches, in the background (guide).

Method and pathDoesAnswers
POST /workflow/api/batch-operationsCreate {type, filter, variables?, remove?, stepId?, reason?, targetVersion?, fromVersion?, stepMapping?} — type CANCEL, RETRY, RESTART, PAUSE, RESUME, SET_VARIABLES (variables to set, remove names; reason mandatory), RETRY_FROM_STEP (stepId; reason mandatory) or MIGRATE (targetVersion, fromVersion, stepMapping, variables to set; reason mandatory; the filter must name the definition); filter {definitionId?, tag?, status?[], from?, to?, businessKey?, q?, onlyErrors?, query?, attributes?: {name: value}}, at least one202 + Location, the batch CREATED with matched
GET /workflow/api/batch-operationsThe most recent batches, newest first200 BatchOperation[]
GET /workflow/api/batch-operations/{id}One batch: status, matched, processed, succeeded, failed, skipped, skippedByReason (notApplicable, notAuthorized, gone), percent, errors (a sample), createdBy, dates, failure200; 404
POST /workflow/api/batch-operations/{id}/cancelStop it: no further process is touched200; 404; 409 when it already finished

Each process is commanded as the single-process endpoint would be, judged against the caller who created the batch: with flow authorization on, a process of a definition the caller may not operate is skipped (notAuthorized). An empty filter, an unknown type or status, or a malformed date or query is 400.

Exactly the rule of the rest of /workflow/api/** — see HTTP security: the X-Api-Key header when workflow.message-api.api-key is set; otherwise the application’s own Spring Security; otherwise 401 unless workflow.message-api.allow-anonymous=true. Bodies over workflow.rest.max-body-bytes are cut off unread (413), and identifiers and variables over the engine’s input limits are refused with 400 naming the field.

With workflow.security.flow-authorization.enabled=true, a definition’s requiredScopes / requiredRoles are checked against the caller (resolved by the same CallerResolver as the console and MCP):

  • starting a process of it — as everywhere the engine starts one;
  • reading one of its processes (/{id}, /by-key, /steps, /variables, /logs) and commanding it (cancel, pause, resume, retry, restart, step retry): a caller who may not start a workflow may not read its variables or stop its runs either.

The manual operations and the incident retry are admin operations: besides the definition’s requirements (when flow authorization is on), the caller must hold every role in workflow.security.operations.required-roles — enforced whenever it is set, flow authorization on or off; empty by default.

A caller who lacks something gets 403 naming what is missing. The listing is not filtered by it — it shows what identifies a process and its status, never its variables.

Errors are application/problem+json (RFC 9457):

StatusWhen
400no definitionId; a value over the input limits; a malformed body, status, date, page or size
401missing or wrong X-Api-Key, or an anonymous request the engine refuses
403flow authorization, or workflow.security.operations.required-roles, refused the caller
404no such process, step execution of it, or definition (on start)
409the business key belongs to another definition’s process; the definition accepts no new processes; the process’s status does not allow the command, or is not accepting an update
422an update refused by its guard, or an Idempotency-Key reused for another update
429too many callers waiting for an update on this node
500an update whose set or reply failed to evaluate (nothing changed)
413body over workflow.rest.max-body-bytes
{"type": "about:blank", "title": "Conflict", "status": 409,
"detail": "Cannot retry process '5f0c…' while it is RUNNING.", "processStatus": "RUNNING"}

The committed description is at /openapi/eventconductor-api.yaml. A running engine can serve it too: add springdoc (an optional dependency of the engine) and switch it on.

<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>3.1.1</version>
</dependency>
workflow.api.openapi.enabled=true

The engine then contributes the eventconductor group — /v3/api-docs/eventconductor (JSON) and /v3/api-docs.yaml/eventconductor — covering /workflow/api/** only, with the X-Api-Key security scheme. It does not switch springdoc on or off for the application’s own endpoints; without the property it contributes nothing.

  • Editing a batch operation once created (cancel it and create another).
  • Pausing or resuming a whole definition — the console and the pauseWorkflow / resumeWorkflow MCP tools.
  • Analytics — the console and the getWorkflowAnalytics / findBottleneck MCP tools.
  • In a sharded fleet, reading a process (/{id}, its steps, variables and log) answers from the shard that serves the request; a process owned by another shard is 404 there. Commands are routed (above).

POST /workflow/api/test-runs accepts {runId, definition, variables?}: runId is a canonical UUID, definition is the workflow JSON object (YAML is parsed by the IDE), and variables is a JSON object. Requires workflow.test-runs.enabled=true; off by default, a call returns 404 with an explanation. Normal API authentication applies, and the caller must hold every role in workflow.test-runs.required-roles (falling back to workflow.security.operations.required-roles) even when flow authorization is off; with no role configured, or no identified caller, the call returns 403. Roles or scopes declared by the submitted document never grant this permission; with flow authorization on they are required in addition.

A first accepted call returns 201 and a process Location; the same ID and payload returns the retained instance with 200. A conflicting document/input or concurrent submission returns 409. After an uncertain response, query the same ID or retry that exact submission. Once retention purges the instance, its identifier no longer provides idempotency.

The definition is validated and frozen in the process; it is never saved to the definition catalogue. It always runs under a private definition ID: vscode-<id>-<runId>, or vscode-<runId> when the document has none. A catalogue definition already holding that ID returns 409. A test run therefore never counts as an instance of a published definition, and it is refused by migration and its dry run with 409. Test runs and their children are left out of process analytics. The persisted test marker is inherited by nested subprocesses and continuations. Children still resolve their deployed definitions normally. same continuations use the executed snapshot; latest is rejected with 400, since the run has no published definition to continue on. This is a manual start: no cron/event registration or startPolicy admission is performed. Workers and services have their usual, real effects.

GET /workflow/api/processes/{id}/graph returns {process, testRun, parentProcessId, definition, overlay, steps}. definition is the effective graph topology from the process’s snapshot plus injected steps, not today’s catalogue definition. A process without a snapshot returns 409. Request blocks, credentials, agent inputs and prompts are omitted; an agent’s catalogue reference is retained. process carries the effective version, masked current variables and continuation links. overlay provides node states, errors, waits, retries and iteration summaries; steps includes historical executions and their exact IDs. Logs remain at the existing /processes/{id}/logs route.

GET /workflow/api/processes/{id}/children?page=0&size=20&stepId=sub returns a page of direct child processes, ordered by creation then ID. stepId is optional, size is 1–100. Every row contains parentStepExecutionId, source stepId, zero-based itemIndex (or null), zero-based iteration, effective definition version and continuation links. The relation keeps earlier attempts and loop passes. It is not a recursive download. A forbidden child causes 403 for that page. A purged process returns 404; continuation links may still point to purged history. Graph and children reads use normal process authorization even when starting tests is disabled.