Workflow HTTP API reference
MapWorkflowEndpoints() of StellaOps.Workflow.AspNetCore maps the engine’s HTTP API into your ASP.NET Core host under /api/workflow. This page lists all 29 routes as the method maps them, with the policy each route requires, the refusals it declares, its parameters, its response and an example. Human tasks and the HTTP API explains the common calls in context.
Conventions
Base path. Every route is under
/api/workflow. The method returns the route group (RouteGroupBuilder), so your host can add its own filters, metadata or rate limits to all routes at once.Authorization. Every route requires a token and one of three policies (Hosting):
Policy Name Scopes that satisfy it view workflow.viewworkflow:view,workflow:operateorworkflow:adminoperate workflow.operateworkflow:operateorworkflow:adminadmin workflow.adminworkflow:adminA request without a valid token answers 401; a token without a matching scope answers 403.
The caller. Task actions, imports and activations act as the authenticated caller: the actor ID and roles come from the token’s claims, never from the body (Hosting). A token without an actor ID claim gets 403 with
error: WorkflowActorUnresolvedon those routes.JSON. Request and response bodies are JSON with camel-case property names. Their .NET types are on the
StellaOps.Workflow.ContractsandStellaOps.Workflow.AspNetCorepages of the .NET API reference.Refusals. An expected refusal answers with its status and a body
{ "error": "<code>", "message": "<reason>" }; the codes are listed in Human tasks and the HTTP API. The “Refusals” line of each route lists the statuses the route declares in its API description.Examples. The examples call a host on
http://localhost:5090with a token in$TOKEN, as in Getting started.
All routes
| Method and path | Policy | Refusals |
|---|---|---|
POST /api/workflow/start | operate | 400, 404, 409, 502 |
GET /api/workflow/instances | view | |
GET /api/workflow/instances/{id} | view | 404 |
GET /api/workflow/tasks | view | |
GET /api/workflow/tasks/{id} | view | 404 |
POST /api/workflow/tasks/{id}/complete | operate | 400, 403, 404, 409, 502 |
POST /api/workflow/tasks/{id}/assign | operate | 403, 404, 409 |
POST /api/workflow/tasks/{id}/release | operate | 403, 404, 409 |
POST /api/workflow/signals/raise | operate | 400, 404, 409 |
GET /api/workflow/definitions | view | |
GET /api/workflow/definitions/{id} | view | 404 |
GET /api/workflow/definitions/{id}/render-graph | view | 404 |
GET /api/workflow/definitions/{name}/versions | view | |
POST /api/workflow/definitions/import | admin | 400, 403, 409 |
POST /api/workflow/definitions/import-multi | admin | 400, 403, 409 |
POST /api/workflow/definitions/export | view | 404 |
POST /api/workflow/definitions/export-multi | view | 404 |
POST /api/workflow/definitions/{name}/activate | admin | 400, 403, 404, 409 |
GET /api/workflow/supported-formats | view | |
GET /api/workflow/diagrams/{name} | view | 404 |
GET /api/workflow/canonical/schema | view | |
POST /api/workflow/canonical/validate | view | |
GET /api/workflow/functions | view | |
GET /api/workflow/metadata | view | |
POST /api/workflow/retention/run | admin | |
GET /api/workflow/signals/dead-letters | view | |
POST /api/workflow/signals/dead-letters/replay | admin | |
GET /api/workflow/signals/pump/stats | view | |
GET /api/workflow/designated-workflows | view |
Instances
POST /api/workflow/start
Starts an instance of a registered workflow. Policy: operate. Refusals: 400, 404, 409, 502.
| Body field | Required | Meaning |
|---|---|---|
workflowName | yes | The registered workflow |
workflowVersion | no | A registered version; the latest registered version when absent |
payload | no | The start request, bound to the workflow’s start request type |
businessReference | no | key and parts; overrides the business key of the start request |
deduplication | no | "OpenBusinessKey" returns the open instance with the same workflow and business key instead of starting another; "None" (the default) always starts one |
curl -s -X POST http://localhost:5090/api/workflow/start \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"workflowName":"OrderApproval","payload":{"orderId":"ORD-1003","customer":"Fabrikam","amount":120.0}}'
The response has workflowInstanceId, workflowName, workflowVersion, businessReference, the tasks the start opened (nextTasks, each a task summary as described under GET /api/workflow/tasks), the workflowState, and deduplicated: true when an open instance was returned. A service call that fails during the start, without a failure branch, answers 502 WorkflowTransportFailed.
GET /api/workflow/instances
Lists instances. Policy: view.
| Query parameter | Matches |
|---|---|
workflowName, workflowVersion | The workflow |
workflowInstanceId | One instance |
businessReferenceKey | The business key |
status | Open, Completed or Stale |
includeDetails | true adds the active task and the state of each instance |
curl -s "http://localhost:5090/api/workflow/instances?workflowName=OrderApproval&status=Open" \
-H "Authorization: Bearer $TOKEN"
The response has instances and totalCount. An instance summary carries workflowInstanceId, workflowName, workflowVersion, businessReference, status, runtimeProvider, runtimeInstanceId, runtimeStatus, completedOnUtc and, with includeDetails, activeTask and workflowState.
GET /api/workflow/instances/{id}
One instance with its tasks, task events and runtime state. Policy: view. Refusals: 404.
curl -s http://localhost:5090/api/workflow/instances/$INSTANCE_ID -H "Authorization: Bearer $TOKEN"
The response has instance (a summary as above), workflowState, tasks, taskEvents (each with workflowTaskId, taskName, eventType, actorId and payload) and runtimeState (runtimeProvider, runtimeInstanceId, runtimeStatus, the provider’s state, completedOnUtc, staleAfterUtc, purgeAfterUtc). The allowedActions of each task are the caller’s; an actorId query parameter is ignored.
Tasks
GET /api/workflow/tasks
Lists tasks. Policy: view.
| Query parameter | Matches |
|---|---|
workflowName, workflowVersion | The workflow |
workflowInstanceId | One instance |
businessReferenceKey | The business key |
assignee | The assigned user |
status | Open, Assigned, Completed, Expired, Cancelled or Stale |
curl -s "http://localhost:5090/api/workflow/tasks?status=Open&workflowName=OrderApproval" \
-H "Authorization: Bearer $TOKEN"
The response has tasks and totalCount. A task summary carries workflowTaskId, workflowInstanceId, workflowName, workflowVersion, taskName, taskType, route, businessReference, assignee, status, the roles (workflowRoles, taskRoles, runtimeRoles, effectiveRoles), allowedActions for the caller, payload, createdOnUtc, completedOnUtc, staleAfterUtc, purgeAfterUtc and, for a task with a deadline, deadlineUtc. The filters decide which tasks are listed; the view scope reads every task.
GET /api/workflow/tasks/{id}
One task, as task (a summary as above). Policy: view. Refusals: 404.
curl -s http://localhost:5090/api/workflow/tasks/$TASK_ID -H "Authorization: Bearer $TOKEN"
POST /api/workflow/tasks/{id}/complete
Completes a task as the caller. Policy: operate. Refusals: 400, 403, 404, 409, 502.
| Body field | Required | Meaning |
|---|---|---|
payload | no | The task’s answer; the task’s completion steps read it as payload.* |
curl -s -X POST http://localhost:5090/api/workflow/tasks/$TASK_ID/complete \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"payload":{"decision":"approve"}}'
The response has workflowTaskId, completed, workflowInstanceId, the tasks the completion opened (nextTasks) and workflowState. A caller outside the task’s effective roles gets 403 WorkflowTaskActionDenied; a completed, expired or cancelled task answers 409.
POST /api/workflow/tasks/{id}/assign
Assigns a task. Policy: operate. Refusals: 403, 404, 409.
| Body field | Required | Meaning |
|---|---|---|
targetUserId | no | The user to assign the task to; empty assigns it to the caller |
targetRoles | no | Role groups to assign the task to instead of a user |
curl -s -X POST http://localhost:5090/api/workflow/tasks/$TASK_ID/assign \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
The response has workflowTaskId, assignee, status, runtimeRoles and effectiveRoles. Assigning to another user or to roles needs an administrator role (Who may act on a task).
POST /api/workflow/tasks/{id}/release
Releases an assigned task. No body. Policy: operate. Refusals: 403, 404, 409.
curl -s -X POST http://localhost:5090/api/workflow/tasks/$TASK_ID/release -H "Authorization: Bearer $TOKEN"
The response has workflowTaskId and released. Only the current assignee or an administrator may release a task.
Signals
POST /api/workflow/signals/raise
Raises an external signal for a waiting instance. Policy: operate. Refusals: 400, 404, 409.
| Body field | Required | Meaning |
|---|---|---|
workflowInstanceId | yes | The waiting instance |
signalName | no | The name the instance waits for in WaitForSignal; without it, the signal goes to the instance’s first wait for an external signal |
waitingToken | no | The token of a specific wait |
payload | no | The signal’s payload; the step reads it under its result key |
curl -s -X POST http://localhost:5090/api/workflow/signals/raise \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"workflowInstanceId":"<instance id>","signalName":"documents-uploaded","payload":{"count":3}}'
The response has workflowInstanceId, signalId and queued; the signal pump delivers the signal. An instance on a provider without durable signals, such as Stella.InProcess, answers 409 WorkflowOperationNotSupported.
GET /api/workflow/signals/dead-letters
Lists dead-lettered signals. Policy: view.
| Query parameter | Meaning |
|---|---|
signalId, workflowInstanceId, signalType | Filters |
maxMessages | The most messages to return; 50 by default |
includeRawPayload | true adds rawPayloadBase64 to each message |
curl -s "http://localhost:5090/api/workflow/signals/dead-letters?maxMessages=20" -H "Authorization: Bearer $TOKEN"
The response has messages and totalCount. A message carries signalId, correlation, workflowInstanceId, runtimeProvider, signalType, expectedVersion, waitingToken, occurredAtUtc, dueAtUtc, enqueuedOnUtc, deliveryCount, isEnvelopeReadable, readError, payload and, on request, rawPayloadBase64.
POST /api/workflow/signals/dead-letters/replay
Puts one dead-lettered signal back on the signal queue. Policy: admin.
curl -s -X POST http://localhost:5090/api/workflow/signals/dead-letters/replay \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"signalId":"<signal id>"}'
The response has signalId, replayed, workflowInstanceId, signalType and wasEnvelopeReadable. Fix the cause before you replay: a signal that fails again is dead-lettered again (Operations).
GET /api/workflow/signals/pump/stats
The counters of the signal pump in this process, as stats. Policy: view.
curl -s http://localhost:5090/api/workflow/signals/pump/stats -H "Authorization: Bearer $TOKEN"
stats carries startedOnUtc, lastActivityOnUtc, lastSuccessOnUtc, lastFailureOnUtc, lastDeadLetterOnUtc, the counts emptyPollCount, processedCount, failureCount, deadLetterCount and concurrencySkipCount, the counts per signal type (signalsByType), and the last success, failure and dead letter. The counters are those of the node that answers.
Definitions
GET /api/workflow/definitions
The workflows registered in code, as definitions with totalCount. Policy: view.
| Query parameter | Matches |
|---|---|
workflowName, workflowVersion | The workflow, case-insensitively |
curl -s "http://localhost:5090/api/workflow/definitions?workflowName=OrderApproval" -H "Authorization: Bearer $TOKEN"
Each definition has workflowName, workflowVersion, displayName, workflowRoles and its tasks.
GET /api/workflow/definitions/{id}
One definition by workflow name: the workflow registered in code under that name, otherwise the active stored version. Policy: view. Refusals: 404.
| Query parameter | Meaning |
|---|---|
includeRendering | true adds the stored rendering assets |
The response has workflowName, version, displayName, canonicalDefinitionJson, contentHash, isActive, the rendering assets (renderingSvgBase64, renderingJsonBase64, renderingPngBase64) and source: catalog for a workflow registered in code, store for a stored definition.
GET /api/workflow/definitions/{id}/render-graph
The render graph of a definition, found as above. Policy: view. Refusals: 404.
| Query parameter | Meaning |
|---|---|
version | A stored version; the active one when absent |
includeSvg | true adds a server-rendered SVG |
The response has workflowName, version, graph, source and, with includeSvg, svg and svgLayoutProvider (Rendering).
GET /api/workflow/definitions/{name}/versions
The stored versions of a workflow, as versions. Policy: view.
curl -s http://localhost:5090/api/workflow/definitions/InventoryRestock/versions -H "Authorization: Bearer $TOKEN"
Each version has workflowName, version, baseVersion, buildIteration, contentHash, isActive, displayName, origin, managedCode, isManaged, sourceBuildSha256, compatibilitySha256, createdOnUtc, activatedOnUtc and importedBy.
POST /api/workflow/definitions/import
Stores a canonical definition as a new, inactive version. Policy: admin. Refusals: 400, 403, 409.
| Body field | Required | Meaning |
|---|---|---|
canonicalDefinitionJson | yes | The canonical definition, as a JSON string |
renderingSvgBase64, renderingJsonBase64, renderingPngBase64 | no | Rendering assets to store with the version |
origin | no | OPERATOR_IMPORTED (the default) or MANAGED_EMBEDDED for a managed definition |
managedCode, sourceBuildSha256, compatibilitySha256 | for a managed definition | The managed code and its two hashes (Governed activation and publishing) |
curl -s -X POST http://localhost:5090/api/workflow/definitions/import \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d "{\"canonicalDefinitionJson\": $(jq -Rs . < InventoryRestock.definition.json)}"
The response has workflowName, version, contentHash, wasImported (false when the same content is already stored), wasNewVersion, isActive and validationIssues. The importer recorded in the audit is the caller; an importedBy in the body is not used. A new version stays inactive until it is activated with POST /api/workflow/definitions/{name}/activate. Importing other content under an existing version answers 409 WORKFLOW_DEFINITION_VERSION_HASH_CONFLICT.
POST /api/workflow/definitions/import-multi
Converts a definition from another format and stores it like an import. Policy: admin. Refusals: 400, 403, 409.
| Body field | Required | Meaning |
|---|---|---|
formatId | yes | A format that GET /api/workflow/supported-formats lists with supportsImport |
contentBase64 | yes | The file, base64-encoded |
The response has workflowName, version, contentHash, wasImported, wasNewVersion, isActive, the converted canonicalDefinitionJson, conversionDiagnostics and validationIssues. A conversion that fails before it names a workflow answers 400 with this response body and its diagnostics.
POST /api/workflow/definitions/export
Exports a stored version. Policy: view. Refusals: 404.
| Body field | Required | Meaning |
|---|---|---|
workflowName | yes | The workflow |
version | no | A stored version; the active one when absent |
includeRendering | no | true adds the rendering assets |
curl -s -X POST http://localhost:5090/api/workflow/definitions/export \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"workflowName":"InventoryRestock"}'
The response has workflowName, version, contentHash, isActive, canonicalDefinitionJson and, on request, the rendering assets.
POST /api/workflow/definitions/export-multi
Exports a stored version in another format. Policy: view. Refusals: 404.
| Body field | Required | Meaning |
|---|---|---|
workflowName | yes | The workflow |
version | no | A stored version; the active one when absent |
formatId | yes | A format that supports export |
The response has workflowName, version, formatId, contentBase64, contentType and suggestedFileName.
POST /api/workflow/definitions/{name}/activate
Makes a stored version the active version, fenced against concurrent activations and recorded in the audit. Policy: admin. Refusals: 400, 403, 404, 409.
| Body field | Required | Meaning |
|---|---|---|
version | yes | The stored version to activate |
expectedActiveVersion, expectedActiveSha256 | when a version is active | The fence: the version and hash you expect to be active now; leave both out for the first activation of a workflow. A fence that no longer holds answers 409 WORKFLOW_DEFINITION_ACTIVATION_FENCE_LOST |
reasonCode | no | The reason recorded in the audit; OPERATOR_ACTIVATION by default |
allowRollback, rollbackOfAuditId | for a rollback | Activate an older version, naming the audit entry it rolls back |
curl -s -X POST http://localhost:5090/api/workflow/definitions/InventoryRestock/activate \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"version":"1.1.0","expectedActiveVersion":"1.0.0","expectedActiveSha256":"<content hash of 1.0.0>"}'
The response has workflowName, version and activated. The route names the workflow, and the actor recorded in the audit is the caller. Activation, rollback and the audit are described in Governed activation and publishing.
GET /api/workflow/supported-formats
The formats of the multi-format import and export, as formats. Policy: view.
Each format has formatId, displayName, contentType, fileExtension, supportsImport, supportsExport and isBinary.
Diagrams
GET /api/workflow/diagrams/{name}
The positioned diagram of a registered workflow. Policy: view. Refusals: 404.
| Query parameter | Meaning |
|---|---|
workflowVersion | A registered version |
workflowInstanceId | Highlights the progress of this instance |
layoutProvider, layoutEffort, layoutOrderingIterations, layoutPlacementIterations | Layout settings (Rendering) |
curl -s "http://localhost:5090/api/workflow/diagrams/OrderApproval?workflowInstanceId=$INSTANCE_ID" \
-H "Authorization: Bearer $TOKEN"
The response has workflowName, workflowVersion, displayName, the layout settings used, the instance’s workflowInstanceId, instanceStatus, runtimeProvider and runtimeStatus when one was given, and the positioned nodes and edges.
Canonical definitions
GET /api/workflow/canonical/schema
The JSON Schema of canonical definitions: schemaVersion and schemaJson. Policy: view.
POST /api/workflow/canonical/validate
Validates a canonical definition without storing it. Policy: view.
curl -s -X POST http://localhost:5090/api/workflow/canonical/validate \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d "{\"canonicalDefinitionJson\": $(jq -Rs . < InventoryRestock.definition.json)}"
The response has isValid, workflowName, workflowVersion, the issues by kind (schemaIssues, semanticIssues, moduleIssues, each with code, path and message) and the installedModules of this host. A module issue names a transport or function module the host lacks.
GET /api/workflow/functions
The expression functions installed in this host, as functions, and the installedModules. Policy: view. Each function has functionName, moduleName, moduleVersion, summary, deterministic, aliases, arguments, return, examples and introducedInSchemaVersion.
Operations
GET /api/workflow/metadata
Facts about this host, as metadata. Policy: view. metadata has serviceName (the host’s IHostEnvironment.ApplicationName), diagramProvider and the flags supportsDefinitionInspection, supportsInstanceInspection, supportsCanonicalSchemaInspection and supportsCanonicalImportValidation.
POST /api/workflow/retention/run
Runs the retention once (Operations). Policy: admin. Send a JSON body, {} for the configured retention.
| Body field | Required | Meaning |
|---|---|---|
referenceUtc | no | The time the run counts from; now when absent |
runningOlderThanDays | no | Marks open instances created more than this many days before as stale and purges them |
completedOlderThanDays | no | Purges completed instances finished more than this many days before |
curl -s -X POST http://localhost:5090/api/workflow/retention/run \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
The response has executedOnUtc, staleInstancesMarked, staleTasksMarked, purgedInstances, purgedTasks, purgedTaskEvents and purgedRuntimeStates. The two overrides delete data that the configured retention would keep: use them deliberately.
GET /api/workflow/designated-workflows
The Designated Workflow ledger and its count (Licensing). Policy: view. Read-only: it records nothing and sends nothing anywhere.
curl -s http://localhost:5090/api/workflow/designated-workflows -H "Authorization: Bearer $TOKEN"
The response has designatedWorkflows (the count), ledger (durable with a workflow store, process-memory without one), workflows (each with workflowName, firstSeenSource and firstSeenOnUtc), and the licence status and notice of the latest licence evaluation, null before the first one.
