OpenAPI for HTTP workflow triggers

Expose an OpenAPI document for Elsa HTTP workflow triggers and understand the generated document's runtime and security boundaries in Elsa 3.8.0.

The Elsa.Http.OpenApi extension generates a small OpenAPI 3.0 document from the HTTP trigger records known to Elsa. It is useful for giving API consumers and process owners a discoverable list of workflow routes, but it is not a complete request/response contract.

Use this extension when you want a live route catalogue or a ReDoc page for workflow endpoints. Add your own schemas, security requirements, server URL, and response details when consumers need a precise API contract.

This guide describes the release/3.8.0 implementation. The extension is provided by elsa-extensions; Elsa Studio does not enable or consume it automatically.

Install and enable it

Add the package version that matches the rest of your Elsa deployment:

dotnet add package Elsa.Http.OpenApi --version 3.8.0

Enable the feature while configuring Elsa's HTTP module, then map its two application endpoints:

using Elsa.Extensions;

builder.Services.AddElsa(elsa =>
{
    elsa.UseHttp(http => http.UseOpenApi());
});

var app = builder.Build();

app.UseWorkflows();
app.MapWorkflowOpenApi();

app.Run();

UseOpenApi registers the endpoint extractor and OpenAPI generator. It does not map routes by itself. MapWorkflowOpenApi is also required; it adds:

Route	Behavior
GET /openapi.json	Extracts the current HTTP trigger records and returns generated JSON.
GET /documentation	Serves a small ReDoc page that loads /openapi.json from the same host.

These routes are mapped at the application root. They are not automatically prefixed with the HTTP workflow base path, which defaults to /workflows. If your host uses a path base or reverse proxy prefix, include that deployment prefix when you give the URL to consumers.

The package's feature and route-builder contracts are visible in the 3.8.0 UseOpenApi source and the 3.8.0 MapWorkflowOpenApi source.

What the extension discovers

When /openapi.json is requested, the extension:

1. Looks up trigger records whose name is the generated type name for Core's HttpEndpoint activity.

2. Keeps records with a non-null HTTP trigger payload.

3. Reads each payload's path and method.

4. Looks up the associated workflow definition to add its definition ID and name.

5. Generates the OpenAPI JSON for that request.

In normal Elsa operation, HTTP trigger records are produced from workflow definitions as they are published. The extractor itself reads the trigger store and does not independently re-check publication state, query Studio, or inspect the workflow designer. The exact behavior is implemented in the 3.8.0 endpoint extractor.

Because extraction happens inside the /openapi.json request handler, the document is regenerated on each request. Each request scans the matching trigger records and looks up each distinct workflow definition; put a cache in front of the route if the document is requested frequently. If a newly published workflow is not visible, check the server's trigger store and publication state before troubleshooting the ReDoc page.

Understand the generated document

For a workflow with an HttpEndpoint configured as POST /orders, the generated document is shaped like this:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Elsa Workflow HTTP Endpoints",
    "version": "3.8.0",
    "description": "HTTP endpoints exposed by Elsa workflows"
  },
  "paths": {
    "/orders": {
      "post": {
        "summary": "POST /orders",
        "description": "Workflow endpoint from 'Order intake' (ID: order-workflow)",
        "responses": {
          "default": {
            "description": "Response from workflow execution"
          }
        },
        "tags": ["Order intake"]
      }
    }
  }
}

The generator emits:

• OpenAPI version 3.0.0.

• A fixed document title and description.

• An info.version read from a loaded Elsa assembly, with an autogenerated +... build suffix removed when present.

• One path and method operation for each extracted endpoint.

• A summary made from the uppercase method and path.

• A description containing the workflow name and definition ID.

• The workflow name as an operation tag.

• A default response description.

The implementation does not emit servers, securitySchemes, operation parameters, request bodies, response content schemas, status-specific responses, or a workflow version field. HttpEndpoint can accept route parameters and request content, but the generated document does not describe their types. Treat the document as discovery metadata unless you enrich it outside this extension. See the 3.8.0 OpenAPI generator for the exact output shape.

The base-path mismatch to plan for

The OpenAPI path comes directly from the HttpEndpoint trigger payload. Core then combines that activity path with HttpActivityOptions.BasePath when it routes requests. The extractor does not inspect bookmarks or apply custom route providers, tenant prefixes, or other host-level routing changes. With the default base path, the effective URL is therefore:

Configuration	Generated OpenAPI path	Runtime URL
Path = "orders" and default BasePath = "/workflows"	/orders	/workflows/orders
Path = "orders" and BasePath = "/api/workflows"	/orders	/api/workflows/orders

If an API gateway or client generator consumes this document, either configure the gateway to add the runtime prefix or publish an adjusted document. The extension does not emit a servers entry or combine the workflow base path with the extracted path. Core's route provider shows the base-path join in the 3.8.0 HTTP route implementation, and the default is defined in 3.8.0 HttpActivityOptions.

Duplicate routes

The generator groups operations by path, then stores each method under that path. If two workflow trigger records produce the same path and method, one operation replaces the other in the generated dictionary; which one wins depends on trigger-store enumeration order. Do not publish competing workflows on the same effective route and method unless you have verified which trigger Elsa will select at runtime.

Design and integration guidance

For process designers

• Give each HTTP trigger an intentional, stable path and method.

• Treat the OpenAPI page as a route catalogue, not as a description of the request payload or workflow output.

• Publish the workflow before expecting its trigger to appear in the generated document.

• Coordinate the BasePath with the API gateway and the URL shared with external callers.

For the activity's request, authorization, upload, and parsed-content inputs, see HTTP workflows and HTTP endpoint security.

For API consumers

Use /openapi.json to discover route paths, methods, workflow names, and workflow definition IDs. Confirm the effective URL with the service owner because the document may omit the runtime base path. Obtain request/response schemas and authentication requirements from the application contract; they are not present in the generated output.

For operators and platform teams

The two OpenAPI routes are regular ASP.NET Core minimal API routes. In release/3.8.0, MapWorkflowOpenApi does not attach authorization metadata, rate limiting, or a custom route policy. If the route catalogue is sensitive, protect it at the reverse proxy or with a deliberate host-level authorization policy. A global fallback policy can also affect unrelated endpoints, so test that choice against public workflow routes. The extractor also does not add tenant filtering; in a multi-tenant deployment, verify that the configured trigger and definition stores enforce the tenant boundary before exposing the document.

The /documentation page loads ReDoc from https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js. If your deployment disallows third-party browser assets, use /openapi.json with an internally hosted documentation tool or replace the page at the edge. The extension does not provide a self-hosted ReDoc bundle.

Troubleshooting

/openapi.json returns 404

Confirm that both the Elsa.Http.OpenApi package and elsa.UseHttp(http => http.UseOpenApi()) are present, and that the built application calls app.MapWorkflowOpenApi().

The document loads but contains no paths

Check that the server has published HTTP workflows and that the trigger store contains HttpEndpoint trigger records with payloads. The extension does not read drafts directly from Studio, and Studio does not populate the document.

The route appears, but the client calls the wrong URL

Compare the generated path with HttpActivityOptions.BasePath. The document contains the activity path, while the runtime route includes the configured workflow base path. Also check any reverse-proxy path base.

Authentication is missing from the document

This is expected in 3.8.0. Add the security scheme and requirements in a consumer-facing contract, or expose the document only through a protected network boundary. HttpEndpoint.Authorize controls workflow ingress; it is not copied into the generated OpenAPI operation.

ReDoc is blank or does not load

Open /openapi.json directly and validate the JSON first. Then check browser network policy, Content Security Policy, and access to the ReDoc CDN. The built-in page references /openapi.json at the same host and loads the ReDoc JavaScript bundle from the CDN.

Related guides

• HTTP workflows

• HTTP endpoint security

• API & Client

• External application interaction