Workflow Engine

Overview

The Workflow Engine provides durable, multi-step workflow execution with step tracking, human approval gates, callbacks/webhooks, retry/backoff, state snapshots, and an event audit log. Unlike Workflow Templates (which define reusable automation patterns), the Workflow Engine manages the actual execution lifecycle of workflow runs.

Step Tracking

Track individual step status with retry and timeout support.

Human Approval

Insert approval gates that pause execution until approved.

State Snapshots

Checkpoint workflow state for recovery and rollback.

API Endpoints

POST /api/v1/workflows Auth

Start a new workflow run from a published template. Inputs are supplied through the template's declared variables.

Request Body:

{
  "template_id": "<uuid>",
  "input": {
    "source": "...",
    "destination": "..."
  }
}

Response Body:

{
  "id": "<run-uuid>",
  "status": "pending",
  "template": {
    "id": "...",
    "name": "...",
    "version": 1
  },
  "trigger_type": "api",
  ...
}

GET /api/v1/workflows Auth

List runs owned by the authenticated user. Query params: status, limit, offset.

GET /api/v1/workflows/:id Auth

Get a run with its steps and events (owner-scoped).

POST /api/v1/workflows/:id/pause Auth

Pause a running workflow. The Runner hibernates; the heartbeat stops. Resume with /resume.

POST /api/v1/workflows/:id/resume Auth

Resume a paused run; respawns the Runner process from DB state if it had stopped.

POST /api/v1/workflows/:id/cancel Auth

Cancel a workflow run. Body: {"reason": "..."} (optional).

POST /api/v1/workflows/:id/retry Auth

Retry a failed or cancelled run from the last failed step.


          POST /api/v1/workflows/:id/approvals/:approval_id/approve

Auth

Approve a pending human-approval step; the run resumes. Body: {"comment": "..."} (optional).


          POST /api/v1/workflows/:id/approvals/:approval_id/reject

Auth

Reject a pending approval step; the run fails with reason approval_rejected.

Workflow Run States

State Description

pending Run created, waiting to start

running Currently executing steps

waiting_approval Paused at an approval gate

completed All steps finished successfully

failed Execution failed (retries exhausted)

cancelled Run cancelled by user or system