Workflow APIs

API endpoints for managing workflow templates, step registry, and workflow runs.

Status: Planned (not yet implemented) Source: Architecture Advisory Section 6.3.4 Related Modules: Workflow Engine Module, Workflow Templates

Overview

The Workflow API provides endpoints for managing workflow templates (DAG definitions), discovering available step types, and executing workflow runs. Workflows are directed acyclic graphs (DAGs) of steps that orchestrate promotions, deployments, and other automation tasks.

Workflow Template Endpoints

Create Workflow Template

Endpoint: POST /api/v1/workflow-templates

Request:

{
  "name": "standard-promotion",
  "displayName": "Standard Promotion Workflow",
  "description": "Default workflow for promoting releases",
  "nodes": [
    {
      "id": "security-check",
      "type": "security-gate",
      "name": "Security Check",
      "config": {
        "maxCritical": 0,
        "maxHigh": 5
      },
      "position": { "x": 100, "y": 100 }
    },
    {
      "id": "approval",
      "type": "approval",
      "name": "Manager Approval",
      "config": {
        "approvers": ["manager-group"],
        "minApprovals": 1
      },
      "position": { "x": 300, "y": 100 }
    },
    {
      "id": "deploy",
      "type": "deploy",
      "name": "Deploy to Target",
      "config": {
        "strategy": "rolling",
        "batchSize": "25%"
      },
      "position": { "x": 500, "y": 100 }
    }
  ],
  "edges": [
    { "from": "security-check", "to": "approval" },
    { "from": "approval", "to": "deploy" }
  ],
  "inputs": [
    { "name": "releaseId", "type": "uuid", "required": true },
    { "name": "environmentId", "type": "uuid", "required": true }
  ],
  "outputs": [
    { "name": "deploymentId", "type": "uuid" }
  ]
}

Response: 201 Created

{
  "id": "uuid",
  "name": "standard-promotion",
  "displayName": "Standard Promotion Workflow",
  "version": 1,
  "nodeCount": 3,
  "isActive": true,
  "createdAt": "2026-01-10T14:23:45Z"
}

List Workflow Templates

Endpoint: GET /api/v1/workflow-templates

Query Parameters:

• includeBuiltin (boolean): Include system-provided templates
• tags (string): Filter by tags

Response: 200 OK - Array of workflow templates

Get Workflow Template

Endpoint: GET /api/v1/workflow-templates/{id}

Response: 200 OK - Full template with nodes and edges

Update Workflow Template

Endpoint: PUT /api/v1/workflow-templates/{id}

Creates a new version of the template.

Request: Partial or full template definition

Response: 200 OK - New version of template

Delete Workflow Template

Endpoint: DELETE /api/v1/workflow-templates/{id}

Response: 200 OK

{ "deleted": true }

Validate Workflow Template

Endpoint: POST /api/v1/workflow-templates/{id}/validate

Validates a template with sample inputs.

Request:

{
  "inputs": {
    "releaseId": "sample-uuid",
    "environmentId": "sample-uuid"
  }
}

Response: 200 OK

{
  "valid": true,
  "errors": []
}

Or on validation failure:

{
  "valid": false,
  "errors": [
    { "nodeId": "deploy", "field": "config.strategy", "message": "Invalid strategy: unknown" },
    { "type": "dag", "message": "Cycle detected: node-a -> node-b -> node-a" }
  ]
}

Step Registry Endpoints

List Step Types

Endpoint: GET /api/v1/step-types

Lists all available step types from core and plugins.

Query Parameters:

• category (string): Filter by category (deployment, gate, notification, utility)
• provider (string): Filter by provider (builtin, plugin-id)

Response: 200 OK

[
  {
    "type": "script",
    "displayName": "Script",
    "description": "Execute shell script on target",
    "category": "utility",
    "provider": "builtin",
    "configSchema": { ... }
  },
  {
    "type": "security-gate",
    "displayName": "Security Gate",
    "description": "Check vulnerability thresholds",
    "category": "gate",
    "provider": "builtin",
    "configSchema": { ... }
  }
]

Get Step Type

Endpoint: GET /api/v1/step-types/{type}

Response: 200 OK - Full step type with configuration schema

Workflow Run Endpoints

Start Workflow Run

Endpoint: POST /api/v1/workflow-runs

Request:

{
  "templateId": "uuid",
  "context": {
    "releaseId": "uuid",
    "environmentId": "uuid",
    "variables": {
      "deploymentTimeout": 600
    }
  }
}

Response: 201 Created

{
  "id": "uuid",
  "templateId": "uuid",
  "templateVersion": 1,
  "status": "running",
  "startedAt": "2026-01-10T14:23:45Z"
}

List Workflow Runs

Endpoint: GET /api/v1/workflow-runs

Query Parameters:

• status (string): Filter by status (pending, running, succeeded, failed, cancelled)
• templateId (UUID): Filter by template
• page (number): Page number

Response: 200 OK

{
  "data": [
    {
      "id": "uuid",
      "templateName": "standard-promotion",
      "status": "running",
      "progress": 66,
      "startedAt": "2026-01-10T14:23:45Z"
    }
  ],
  "meta": { "page": 1, "totalCount": 50 }
}

Get Workflow Run

Endpoint: GET /api/v1/workflow-runs/{id}

Response: 200 OK - Full run with step statuses

Pause Workflow Run

Endpoint: POST /api/v1/workflow-runs/{id}/pause

Pauses a running workflow at the next step boundary.

Response: 200 OK - Updated workflow run

Resume Workflow Run

Endpoint: POST /api/v1/workflow-runs/{id}/resume

Resumes a paused workflow.

Response: 200 OK - Updated workflow run

Cancel Workflow Run

Endpoint: POST /api/v1/workflow-runs/{id}/cancel

Cancels a running or paused workflow.

Response: 200 OK - Updated workflow run

List Step Runs

Endpoint: GET /api/v1/workflow-runs/{id}/steps

Response: 200 OK

[
  {
    "nodeId": "security-check",
    "stepType": "security-gate",
    "status": "succeeded",
    "startedAt": "2026-01-10T14:23:45Z",
    "completedAt": "2026-01-10T14:23:50Z"
  },
  {
    "nodeId": "approval",
    "stepType": "approval",
    "status": "running",
    "startedAt": "2026-01-10T14:23:50Z"
  }
]

Get Step Run

Endpoint: GET /api/v1/workflow-runs/{id}/steps/{nodeId}

Response: 200 OK - Step run with logs

Get Step Logs

Endpoint: GET /api/v1/workflow-runs/{id}/steps/{nodeId}/logs

Query Parameters:

• follow (boolean): Stream logs in real-time via SSE

Response: 200 OK - Log content or SSE stream

List Step Artifacts

Endpoint: GET /api/v1/workflow-runs/{id}/steps/{nodeId}/artifacts

Response: 200 OK - Array of artifacts

Download Artifact

Endpoint: GET /api/v1/workflow-runs/{id}/steps/{nodeId}/artifacts/{artifactId}

Response: Binary download

Error Responses

See Also

• WebSocket APIs - Real-time workflow updates
• Workflow Engine Module
• Workflow Templates
• Workflow Execution