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

All routes

Method and pathPolicyRefusals
POST /api/workflow/startoperate400, 404, 409, 502
GET /api/workflow/instancesview
GET /api/workflow/instances/{id}view404
GET /api/workflow/tasksview
GET /api/workflow/tasks/{id}view404
POST /api/workflow/tasks/{id}/completeoperate400, 403, 404, 409, 502
POST /api/workflow/tasks/{id}/assignoperate403, 404, 409
POST /api/workflow/tasks/{id}/releaseoperate403, 404, 409
POST /api/workflow/signals/raiseoperate400, 404, 409
GET /api/workflow/definitionsview
GET /api/workflow/definitions/{id}view404
GET /api/workflow/definitions/{id}/render-graphview404
GET /api/workflow/definitions/{name}/versionsview
POST /api/workflow/definitions/importadmin400, 403, 409
POST /api/workflow/definitions/import-multiadmin400, 403, 409
POST /api/workflow/definitions/exportview404
POST /api/workflow/definitions/export-multiview404
POST /api/workflow/definitions/{name}/activateadmin400, 403, 404, 409
GET /api/workflow/supported-formatsview
GET /api/workflow/diagrams/{name}view404
GET /api/workflow/canonical/schemaview
POST /api/workflow/canonical/validateview
GET /api/workflow/functionsview
GET /api/workflow/metadataview
POST /api/workflow/retention/runadmin
GET /api/workflow/signals/dead-lettersview
POST /api/workflow/signals/dead-letters/replayadmin
GET /api/workflow/signals/pump/statsview
GET /api/workflow/designated-workflowsview

Instances

POST /api/workflow/start

Starts an instance of a registered workflow. Policy: operate. Refusals: 400, 404, 409, 502.

Body fieldRequiredMeaning
workflowNameyesThe registered workflow
workflowVersionnoA registered version; the latest registered version when absent
payloadnoThe start request, bound to the workflow’s start request type
businessReferencenokey and parts; overrides the business key of the start request
deduplicationno"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 parameterMatches
workflowName, workflowVersionThe workflow
workflowInstanceIdOne instance
businessReferenceKeyThe business key
statusOpen, Completed or Stale
includeDetailstrue 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 parameterMatches
workflowName, workflowVersionThe workflow
workflowInstanceIdOne instance
businessReferenceKeyThe business key
assigneeThe assigned user
statusOpen, 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 fieldRequiredMeaning
payloadnoThe 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 fieldRequiredMeaning
targetUserIdnoThe user to assign the task to; empty assigns it to the caller
targetRolesnoRole 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 fieldRequiredMeaning
workflowInstanceIdyesThe waiting instance
signalNamenoThe name the instance waits for in WaitForSignal; without it, the signal goes to the instance’s first wait for an external signal
waitingTokennoThe token of a specific wait
payloadnoThe 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 parameterMeaning
signalId, workflowInstanceId, signalTypeFilters
maxMessagesThe most messages to return; 50 by default
includeRawPayloadtrue 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 parameterMatches
workflowName, workflowVersionThe 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 parameterMeaning
includeRenderingtrue 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 parameterMeaning
versionA stored version; the active one when absent
includeSvgtrue 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 fieldRequiredMeaning
canonicalDefinitionJsonyesThe canonical definition, as a JSON string
renderingSvgBase64, renderingJsonBase64, renderingPngBase64noRendering assets to store with the version
originnoOPERATOR_IMPORTED (the default) or MANAGED_EMBEDDED for a managed definition
managedCode, sourceBuildSha256, compatibilitySha256for a managed definitionThe 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 fieldRequiredMeaning
formatIdyesA format that GET /api/workflow/supported-formats lists with supportsImport
contentBase64yesThe 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 fieldRequiredMeaning
workflowNameyesThe workflow
versionnoA stored version; the active one when absent
includeRenderingnotrue 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 fieldRequiredMeaning
workflowNameyesThe workflow
versionnoA stored version; the active one when absent
formatIdyesA 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 fieldRequiredMeaning
versionyesThe stored version to activate
expectedActiveVersion, expectedActiveSha256when a version is activeThe 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
reasonCodenoThe reason recorded in the audit; OPERATOR_ACTIVATION by default
allowRollback, rollbackOfAuditIdfor a rollbackActivate 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 parameterMeaning
workflowVersionA registered version
workflowInstanceIdHighlights the progress of this instance
layoutProvider, layoutEffort, layoutOrderingIterations, layoutPlacementIterationsLayout 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 fieldRequiredMeaning
referenceUtcnoThe time the run counts from; now when absent
runningOlderThanDaysnoMarks open instances created more than this many days before as stale and purges them
completedOlderThanDaysnoPurges 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.