elsa-core/doc/wiki/workflow-api.md

Workflow API

The workflow API exposes management, runtime, descriptors, execution logs, tasks, installed features, runtime admin, and real-time workflow updates. It uses FastEndpoints with Elsa-specific serializer configuration.

Start in src/modules/Elsa.Workflows.Api and shared API infrastructure in src/common/Elsa.Api.Common.

Feature Wiring

WorkflowsApiFeature:

• depends on workflow instances, workflow management, workflow runtime, and SAS tokens
• registers its endpoint assembly with the module
• calls AddFastEndpointsFromModule()
• configures API serialization
• registers IWorkflowDefinitionLinker
• registers read-only-mode authorization requirement handling
• registers workflow instance export naming

The module extension is UseWorkflowsApi.

Route Prefix

The default route prefix is elsa/api, defined in ApiEndpointOptions. Endpoint-routed ASP.NET hosts apply it with MapWorkflowsApi:

var routePrefix = app.Services.GetRequiredService<IOptions<ApiEndpointOptions>>().Value.RoutePrefix;
app.MapWorkflowsApi(routePrefix);

With the default prefix, endpoint paths look like /elsa/api/workflow-definitions.

FastEndpoints Registration

FastEndpoints assemblies are collected through module properties:

• AddFastEndpointsAssembly
• AddFastEndpointsFromModule

This allows multiple features to contribute endpoints before FastEndpoints is registered.

Endpoint Categories

Category	Folder	Examples
Workflow definitions	Endpoints/WorkflowDefinitions	list, get, post, publish, retract, delete, import, export, dispatch, execute, graph, refresh, reload.
Workflow instances	Endpoints/WorkflowInstances	list, get, delete, cancel, bulk cancel/delete, import/export, execution state, variables, journal.
Activity executions	Endpoints/ActivityExecutions and ActivityExecutionSummaries	list, get, count, report, call stack, summaries.
Descriptors	ActivityDescriptors, VariableTypes, StorageDrivers, IncidentStrategies, CommitStrategies, Scripting	designer metadata and option providers.
Runtime admin	Endpoints/RuntimeAdmin	status, pause, resume, force drain.
Events and tasks	Endpoints/Events, Endpoints/Tasks	trigger event, complete task.
Package and features	Endpoints/Package, Endpoints/Features	package version and installed feature metadata.

Common Endpoint Shape

Endpoint classes typically derive from Elsa API base classes in Elsa.Api.Common. They configure route, verb, permissions, and response shape in Configure(), then implement either ExecuteAsync or HandleAsync depending on the FastEndpoints pattern used by that area of the module.

When adding endpoints:

• keep one endpoint per folder/action
• keep request and response models near the endpoint
• follow the ExecuteAsync or HandleAsync pattern used by nearby endpoints in the same area
• use ConfigurePermissions for protected operations
• use the configured API serializer rather than custom JSON settings
• add route examples to relevant docs when behavior is externally visible

Real-Time Workflow Updates

Real-time updates live under RealTime:

• WorkflowInstanceHub
• BroadcastWorkflowProgress
• client contract IWorkflowInstanceClient
• messages for activity and workflow execution updates

Hosts map these hubs with app.UseWorkflowsSignalRHubs() when SignalR is enabled.

Authorization And Read-Only Mode

Workflow API registers NotReadOnlyRequirementHandler and the policy name in AuthorizationPolicies. Mutable workflow definition endpoints use this policy to honor management read-only mode.

Identity and API key setup are supplied by Elsa.Identity; see Identity, Tenancy, And Security.

API Client

The generated or hand-maintained client project is src/clients/Elsa.Api.Client. When endpoint contracts or enums change, check whether the client has mirrored models that need updating. The graceful shutdown plan explicitly called out mirroring WorkflowSubStatus.Interrupted in the API client.

JSON Serialization Errors

Hosts can use UseJsonSerializationErrorHandler, which installs middleware that returns JSON error responses for serialization failures. The reference server maps it after workflow API endpoints.

Endpoint Discovery Command

To quickly list routes:

rg "Get\\(|Post\\(|Delete\\(|Put\\(|Patch\\(|Routes\\(|Verbs\\(" src/modules/Elsa.Workflows.Api/Endpoints src/modules/Elsa.Diagnostics.StructuredLogs/Endpoints -g "Endpoint.cs"