Workflows

Operations of the Workflow Engine API. Paths are relative to your deployment's API host.

GET /api/workflow-engine-api/workflows

List workflow definitions

Returns system-seeded workflows plus custom workflows owned by the caller's org. Filter with ?isSystem=true|false and ?isReusable=true|false. A workflow contributed by a biome installed in a Project is listed only with that Project's ?projectId=.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/workflow-engine-api/workflows

Create a stable workflow identity with its mutable draft

The initial YAML must be valid so the server can establish the workflow slug. The server owns generated revision numbers; ordinary workflow authors never provide a version.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json CreateWorkflowDraftDto

DELETE /api/workflow-engine-api/workflows/id/{id}

Archive workflow definition by id

History-preserving delete for custom workflows. Marks archivedAt and removes active schedule/trigger projections. Immutable system/biome workflows are rejected with 409.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/workflow-engine-api/workflows/{slug}

Get workflow definition by slug

Resolves a slug (e.g. product-development) to its definition row. System workflows are checked first; custom workflows match only when they belong to the caller's org.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/workflow-engine-api/workflows/{slug}/dispatch-schema

Get workflow dispatch inputs as a JSON Schema

Reads on.workflow_dispatch.inputs from the workflow's current version and projects it to a JSON Schema Draft 2020-12 object. Single source of truth consumed by the MCP gateway (workflow-tool inputSchema), the frontend dispatch dialog, and any other consumer that renders or validates dispatch inputs.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/workflow-engine-api/workflows/{slug}/draft

Get the mutable workflow draft

Authentication: bearer token (Authorization: Bearer <token>)

PATCH /api/workflow-engine-api/workflows/{slug}/draft

Update the mutable workflow draft with optimistic concurrency

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json UpdateWorkflowDraftDto

GET /api/workflow-engine-api/workflows/{slug}/drafts

List the autosaved draft ring, newest first

Drafts are append-plus-evict and bounded. This is the recovery surface: the previous bytes of an edit or a restore are here until they fall out of the ring. The first entry is always the one WorkflowDefinition.draftId points at.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/workflow-engine-api/workflows/{slug}/editor-state

Get mutable presentation state outside executable revisions

Authentication: bearer token (Authorization: Bearer <token>)

PATCH /api/workflow-engine-api/workflows/{slug}/editor-state

Update mutable workflow presentation state with CAS

Canvas layout and annotations never affect executable content hashes. Shared system/biome workflows receive organization-scoped editor state.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json UpdateWorkflowEditorStateDto

GET /api/workflow-engine-api/workflows/{slug}/history

List immutable workflow revision history

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/workflow-engine-api/workflows/{slug}/history/{revisionNumber}/restore

Load an immutable revision back into the editor as a new draft

Appends a NEW draft-ring entry carrying the revision's YAML and moves the draft pointer to it; the entry you were editing stays in the ring and is still listable. This is an AUTHORING convenience — to serve an earlier immutable release again use POST /workflows/:slug/rollback, which requests replay of its prior ReleaseSet and creates no revision.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json RestoreWorkflowRevisionDto

GET /api/workflow-engine-api/workflows/{slug}/live

Get the immutable revision currently served for new runs

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/workflow-engine-api/workflows/{slug}/publish

Publish the current draft as the next generated revision

Validates the current draft, allocates a monotonic immutable revision under a database lock, and durably requests promotion through the generic release plane. Schedules and triggers reconcile from the resulting ReleaseSet.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json PublishWorkflowDraftDto

POST /api/workflow-engine-api/workflows/{slug}/revisions/pins/move

Re-point every movable pin from one revision to another

Moves ONLY mutable holders, in one transaction, and returns the full partition — what moved, what needs its holder republished, and what records history and was never touched. A caller can therefore never believe everything moved.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json MoveRevisionPinsDto

GET /api/workflow-engine-api/workflows/{slug}/revisions/{revisionNumber}

Get a specific generated workflow revision

Returns the immutable parsed document, raw YAML, and content hash for a generated workflow revision. The hash is recorded in CompiledRun.workflowDefinitionContentHash for audit.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/workflow-engine-api/workflows/{slug}/revisions/{revisionNumber}/pins

List every consumer naming this exact revision

Workflow dispatch definitions that pin it (mutable), outbound uses: references inside other published revisions (immutable — republish the holder), and the runs that executed it (provenance — never moved). Provenance is capped per source and the counts say how much was left out.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/workflow-engine-api/workflows/{slug}/rollback

Request replay of an earlier immutable ReleaseSet

Enqueues a governed rollback intent for a prior ReleaseSet. The generic release plane owns history and compare-and-swap activation; the workflow draft and immutable revision history are untouched.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json RollbackWorkflowRevisionDto