Workflows API

Overview

The Workflows API allows you to programmatically create, manage, and execute automated workflows. Workflows consist of interconnected nodes that process data, make decisions, and integrate with external services. The API also supports versioning, debug sessions, and workflow templates.

---

Endpoint Summary

Workflow CRUD

Execution

Workflow Executions (Global)

Debug

Templates

Node Types

---

List Workflows

GET /api/v1/workflows

Query Parameters

Response

jsonCopy
{
  "data": [
    {
      "id": "wf_abc123",
      "name": "Lead Processing",
      "slug": "lead-processing",
      "description": "Processes new leads from forms",
      "status": "published",
      "trigger_type": "form_submission",
      "node_count": 8,
      "execution_count": 1520,
      "last_executed_at": "2025-12-07T15:30:00Z",
      "version": 3,
      "created_at": "2025-11-01T10:00:00Z",
      "updated_at": "2025-12-07T15:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 12,
    "total_pages": 1
  }
}

Example

bashCopy
curl "/api/v1/workflows?status=published&per_page=10" \
  -H "Authorization: Bearer your_api_key"

---

Create Workflow

POST /api/v1/workflows

Request Body

jsonCopy
{
  "name": "Lead Processing",
  "description": "Automatically process and score new leads",
  "trigger": {
    "type": "form_submission",
    "config": {
      "form_id": "form_abc123"
    }
  },
  "nodes": [
    {
      "id": "node_1",
      "type": "trigger_form",
      "position": { "x": 100, "y": 100 },
      "data": {
        "label": "Form Submitted"
      }
    },
    {
      "id": "node_2",
      "type": "action_ai",
      "position": { "x": 100, "y": 250 },
      "data": {
        "label": "Score Lead",
        "agent_id": "agent_xyz789",
        "prompt": "Analyze this lead and provide a score from 1-100: {{input}}"
      }
    },
    {
      "id": "node_3",
      "type": "condition",
      "position": { "x": 100, "y": 400 },
      "data": {
        "label": "Check Score",
        "condition": "{{node_2.score}} >= 70"
      }
    },
    {
      "id": "node_4",
      "type": "action_http",
      "position": { "x": -50, "y": 550 },
      "data": {
        "label": "Send to CRM",
        "url": "https://api.salesforce.com/leads",
        "method": "POST",
        "body": "{{input}}"
      }
    },
    {
      "id": "node_5",
      "type": "action_email",
      "position": { "x": 250, "y": 550 },
      "data": {
        "label": "Add to Nurture",
        "to": "[email protected]",
        "subject": "New lead for nurturing"
      }
    }
  ],
  "edges": [
    { "source": "node_1", "target": "node_2" },
    { "source": "node_2", "target": "node_3" },
    { "source": "node_3", "target": "node_4", "label": "true" },
    { "source": "node_3", "target": "node_5", "label": "false" }
  ]
}

Workflow Fields

Trigger Types

Node Types

Response

jsonCopy
{
  "data": {
    "id": "wf_abc123",
    "name": "Lead Processing",
    "slug": "lead-processing",
    "description": "Automatically process and score new leads",
    "status": "draft",
    "trigger": { "type": "form_submission", "config": { "form_id": "form_abc123" } },
    "nodes": [...],
    "edges": [...],
    "node_count": 5,
    "version": 1,
    "created_at": "2025-12-07T10:00:00Z",
    "updated_at": "2025-12-07T10:00:00Z"
  }
}

---

Get Workflow

GET /api/v1/workflows/:id

Returns the full workflow definition including nodes, edges, settings, and execution stats.

Response

jsonCopy
{
  "data": {
    "id": "wf_abc123",
    "name": "Lead Processing",
    "slug": "lead-processing",
    "description": "Automatically process and score new leads",
    "status": "published",
    "trigger": {
      "type": "form_submission",
      "config": { "form_id": "form_abc123" }
    },
    "nodes": [...],
    "edges": [...],
    "variables": {
      "crm_api_key": "{{secrets.CRM_API_KEY}}"
    },
    "settings": {
      "timeout_seconds": 300,
      "retry_on_failure": true,
      "max_retries": 3
    },
    "stats": {
      "total_executions": 1520,
      "successful_executions": 1498,
      "failed_executions": 22,
      "avg_duration_ms": 4500
    },
    "version": 3,
    "created_at": "2025-11-01T10:00:00Z",
    "updated_at": "2025-12-07T15:30:00Z",
    "published_at": "2025-11-02T09:00:00Z"
  }
}

---

Get Workflow by Slug

GET /api/v1/workflows/slug/:slug

Same response format as Get Workflow. Useful when you have the human-readable slug instead of the UUID.

---

Update Workflow

PUT /api/v1/workflows/:id

Only include fields you want to update. Returns the updated workflow object.

jsonCopy
{
  "name": "Updated Lead Processing",
  "nodes": [...],
  "edges": [...],
  "settings": {
    "timeout_seconds": 600
  }
}

---

Delete Workflow

DELETE /api/v1/workflows/:id

Returns 204 No Content. Deleting a workflow also cancels any running executions.

---

Lifecycle Endpoints

Publish

POST /api/v1/workflows/:id/publish

Changes status from draft to published, enabling automatic triggers.

Archive

POST /api/v1/workflows/:id/archive

Archives the workflow. Disables triggers and prevents new executions while retaining history.

Pause

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

Temporarily pauses a published workflow. Triggers are disabled but the workflow remains published.

Resume

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

Resumes a paused workflow, re-enabling its triggers.

Response (all lifecycle endpoints)

jsonCopy
{
  "data": {
    "id": "wf_abc123",
    "status": "published",
    "updated_at": "2025-12-07T10:00:00Z"
  }
}

---

Validate Workflow

POST /api/v1/workflows/:id/validate

Validates the workflow definition without executing it. Checks for missing connections, invalid node configurations, and circular dependencies.

Response

jsonCopy
{
  "data": {
    "valid": true,
    "warnings": [
      {
        "node_id": "node_5",
        "message": "Email node has no error handler configured"
      }
    ],
    "errors": []
  }
}

---

Versions

List Versions

GET /api/v1/workflows/:id/versions

jsonCopy
{
  "data": [
    {
      "version": 3,
      "created_at": "2025-12-07T15:30:00Z",
      "published": true,
      "node_count": 8,
      "change_summary": "Added notification node"
    },
    {
      "version": 2,
      "created_at": "2025-12-01T10:00:00Z",
      "published": false,
      "node_count": 7,
      "change_summary": "Added condition branch"
    }
  ]
}

Get Specific Version

GET /api/v1/workflows/:id/versions/:version

Returns the full workflow definition as it existed at that version.

---

Trigger Workflow

POST /api/v1/workflows/:id/trigger

Request Body

jsonCopy
{
  "input": {
    "name": "John Doe",
    "email": "[email protected]",
    "company": "Acme Inc"
  },
  "async": true,
  "callback_url": "https://your-server.com/callback"
}

Parameters

Response (Async)

jsonCopy
{
  "data": {
    "execution_id": "exec_xyz789",
    "workflow_id": "wf_abc123",
    "status": "running",
    "started_at": "2025-12-07T10:30:00Z"
  }
}

Response (Sync)

jsonCopy
{
  "data": {
    "execution_id": "exec_xyz789",
    "workflow_id": "wf_abc123",
    "status": "completed",
    "output": {
      "lead_score": 85,
      "action_taken": "sent_to_crm",
      "crm_id": "lead_123456"
    },
    "started_at": "2025-12-07T10:30:00Z",
    "completed_at": "2025-12-07T10:30:05Z",
    "duration_ms": 5000
  }
}

Example

bashCopy
curl -X POST "/api/v1/workflows/wf_abc123/trigger" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "name": "Jane Smith",
      "email": "[email protected]"
    }
  }'

---

Test Run

POST /api/v1/workflows/:id/test-run

Executes the workflow in test mode with sample data. Test runs are not counted in production stats and are flagged in execution history.

Request Body

jsonCopy
{
  "input": {
    "name": "Test User",
    "email": "[email protected]"
  },
  "stop_at_node": "node_3"
}

---

List Executions (per Workflow)

GET /api/v1/workflows/:id/executions

Query Parameters

Response

jsonCopy
{
  "data": [
    {
      "id": "exec_xyz789",
      "workflow_id": "wf_abc123",
      "status": "completed",
      "trigger_type": "form_submission",
      "started_at": "2025-12-07T10:30:00Z",
      "completed_at": "2025-12-07T10:30:05Z",
      "duration_ms": 5000
    },
    {
      "id": "exec_abc456",
      "workflow_id": "wf_abc123",
      "status": "failed",
      "trigger_type": "manual",
      "error": {
        "node_id": "node_4",
        "message": "HTTP request failed: 503 Service Unavailable"
      },
      "started_at": "2025-12-07T10:25:00Z",
      "failed_at": "2025-12-07T10:25:03Z",
      "duration_ms": 3000
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}

---

Execution Summary

GET /api/v1/workflows/:id/execution-summary

Returns aggregated execution statistics for a workflow.

jsonCopy
{
  "data": {
    "total": 1520,
    "completed": 1498,
    "failed": 12,
    "cancelled": 10,
    "avg_duration_ms": 4500,
    "p95_duration_ms": 12000,
    "success_rate": 98.6,
    "last_24h": { "total": 45, "completed": 44, "failed": 1 },
    "last_7d": { "total": 312, "completed": 308, "failed": 4 }
  }
}

---

Running Executions

GET /api/v1/workflows/:id/running

Returns all currently running executions for the workflow.

---

Global Executions

List All Executions

GET /api/v1/workflow-executions

Lists executions across all workflows. Supports the same query parameters as per-workflow listing, plus workflow_id filter.

Get Execution

GET /api/v1/workflow-executions/:id

Get Detailed Execution

GET /api/v1/workflow-executions/:id/detail

Returns the execution with full node-level results, input/output data, and timing for each node.

jsonCopy
{
  "data": {
    "id": "exec_xyz789",
    "workflow_id": "wf_abc123",
    "workflow_name": "Lead Processing",
    "status": "completed",
    "input": { "name": "John Doe", "email": "[email protected]" },
    "output": { "lead_score": 85, "action_taken": "sent_to_crm" },
    "node_executions": [
      {
        "node_id": "node_1",
        "node_type": "trigger_form",
        "status": "completed",
        "started_at": "2025-12-07T10:30:00.000Z",
        "completed_at": "2025-12-07T10:30:00.050Z",
        "duration_ms": 50
      },
      {
        "node_id": "node_2",
        "node_type": "action_ai",
        "status": "completed",
        "input": { "prompt": "Analyze this lead..." },
        "output": { "score": 85, "reasoning": "High-quality enterprise lead..." },
        "started_at": "2025-12-07T10:30:00.050Z",
        "completed_at": "2025-12-07T10:30:02.500Z",
        "duration_ms": 2450,
        "tokens_used": 350
      },
      {
        "node_id": "node_3",
        "node_type": "condition",
        "status": "completed",
        "output": { "branch": "true" },
        "duration_ms": 10
      }
    ],
    "started_at": "2025-12-07T10:30:00Z",
    "completed_at": "2025-12-07T10:30:05Z",
    "duration_ms": 5000
  }
}

Get Node Results

GET /api/v1/workflow-executions/:id/nodes

Returns an array of all node execution results for the given execution.

Get Single Node Result

GET /api/v1/workflow-executions/:id/nodes/:nodeId

Returns the detailed result for a specific node within an execution.

Cancel Execution

POST /api/v1/workflow-executions/:id/cancel

jsonCopy
{
  "data": {
    "id": "exec_xyz789",
    "status": "cancelled",
    "cancelled_at": "2025-12-07T10:31:00Z"
  }
}

Retry Failed Execution

POST /api/v1/workflow-executions/:id/retry

Retries a failed execution from the point of failure. Creates a new execution record linked to the original.

jsonCopy
{
  "data": {
    "execution_id": "exec_retry_001",
    "original_execution_id": "exec_xyz789",
    "status": "running",
    "retry_from_node": "node_4",
    "started_at": "2025-12-07T11:00:00Z"
  }
}

---

Debug Sessions

Debug sessions allow you to step through a workflow execution node by node, inspect data, set breakpoints, and modify inputs in real time.

Start Debug Session

POST /api/v1/workflows/:id/debug/start

jsonCopy
{
  "input": { "name": "Debug User", "email": "[email protected]" },
  "breakpoints": ["node_3", "node_5"]
}

Response:

jsonCopy
{
  "data": {
    "execution_id": "exec_dbg_001",
    "status": "paused",
    "current_node": "node_1",
    "breakpoints": ["node_3", "node_5"]
  }
}

Get Debug State

GET /api/v1/executions/:id/debug/state

Returns the current state of the debug session including the current node, variables, and node outputs so far.

Set Breakpoints

PUT /api/v1/executions/:id/debug/breakpoints

jsonCopy
{
  "breakpoints": ["node_2", "node_4", "node_6"]
}

Continue / Step Over / Resume / Skip

Modify Node Input

POST /api/v1/executions/:id/debug/modify-input

jsonCopy
{
  "node_id": "node_2",
  "input": {
    "prompt": "Modified prompt for testing: {{input}}"
  }
}

Abort Debug Session

POST /api/v1/executions/:id/debug/abort

Terminates the debug session and marks the execution as cancelled.

---

Templates

Create from Template

POST /api/v1/workflows/from-template/:templateId

jsonCopy
{
  "name": "My Lead Processing",
  "variables": {
    "crm_url": "https://api.salesforce.com",
    "notification_email": "[email protected]"
  }
}

List Templates

GET /api/v1/workflow-templates

jsonCopy
{
  "data": [
    {
      "id": "tmpl_001",
      "name": "Lead Scoring & Routing",
      "description": "Score inbound leads with AI and route to the right team",
      "category": "sales",
      "node_count": 6,
      "tags": ["ai", "crm", "lead-gen"]
    }
  ]
}

List Template Categories

GET /api/v1/workflow-templates/categories

Get Template

GET /api/v1/workflow-templates/:id

Returns the full template definition including nodes, edges, and configurable variables.

---

Node Types

List All Node Types

GET /api/v1/workflow-node-types

jsonCopy
{
  "data": [
    {
      "type": "action_ai",
      "label": "AI Processing",
      "category": "actions",
      "description": "Process data using an AI agent or LLM",
      "icon": "brain",
      "config_schema": {
        "type": "object",
        "properties": {
          "agent_id": { "type": "string" },
          "prompt": { "type": "string" },
          "temperature": { "type": "number", "default": 0.7 },
          "max_tokens": { "type": "integer", "default": 1000 }
        },
        "required": ["prompt"]
      }
    }
  ]
}

List Node Categories

GET /api/v1/workflow-node-types/categories

Node Types Grouped by Category

GET /api/v1/workflow-node-types/by-category

jsonCopy
{
  "data": {
    "triggers": [
      { "type": "trigger", "label": "Manual Trigger" },
      { "type": "trigger_webhook", "label": "Webhook Trigger" },
      { "type": "trigger_schedule", "label": "Schedule Trigger" },
      { "type": "trigger_form", "label": "Form Submission" },
      { "type": "trigger_data_table", "label": "Data Table Event" }
    ],
    "actions": [
      { "type": "action_ai", "label": "AI Processing" },
      { "type": "action_http", "label": "HTTP Request" },
      { "type": "action_email", "label": "Send Email" },
      { "type": "action_tool", "label": "Execute Tool" },
      { "type": "action_code", "label": "Run Code" },
      { "type": "action_delay", "label": "Delay" },
      { "type": "action_data_source", "label": "Read Data" },
      { "type": "action_data_write", "label": "Write Data" },
      { "type": "action_data_lookup", "label": "Lookup Data" },
      { "type": "action_notification", "label": "Send Notification" }
    ],
    "logic": [
      { "type": "condition", "label": "Condition" },
      { "type": "loop", "label": "Loop" },
      { "type": "transform", "label": "Transform" },
      { "type": "approval", "label": "Approval" }
    ],
    "control": [
      { "type": "end", "label": "End" }
    ]
  }
}

---

Node Configuration Examples

AI Node (action_ai)

jsonCopy
{
  "id": "ai_node_1",
  "type": "action_ai",
  "data": {
    "label": "Analyze Input",
    "agent_id": "agent_abc123",
    "prompt": "Analyze the following data:\n\n{{input}}",
    "temperature": 0.7,
    "max_tokens": 1000
  }
}

HTTP Node (action_http)

jsonCopy
{
  "id": "http_node_1",
  "type": "action_http",
  "data": {
    "label": "Call External API",
    "url": "https://api.example.com/data",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{secrets.API_KEY}}"
    },
    "body": { "data": "{{previous_node.output}}" },
    "timeout_ms": 30000,
    "retry_on_error": true,
    "max_retries": 3
  }
}

Condition Node

jsonCopy
{
  "id": "cond_1",
  "type": "condition",
  "data": {
    "label": "Check Value",
    "conditions": [
      { "id": "c1", "expression": "{{input.score}} >= 80", "label": "High" },
      { "id": "c2", "expression": "{{input.score}} >= 50", "label": "Medium" }
    ],
    "default_branch": "Low"
  }
}

Loop Node

jsonCopy
{
  "id": "loop_1",
  "type": "loop",
  "data": {
    "label": "Process Items",
    "items": "{{input.items}}",
    "item_variable": "current_item",
    "index_variable": "index",
    "max_iterations": 100
  }
}

Data Write Node (action_data_write)

jsonCopy
{
  "id": "write_1",
  "type": "action_data_write",
  "data": {
    "label": "Save to Data Table",
    "table_id": "dt_abc123",
    "operation": "insert",
    "row_data": {
      "name": "{{input.name}}",
      "email": "{{input.email}}",
      "score": "{{node_2.output.score}}"
    }
  }
}

Approval Node

jsonCopy
{
  "id": "approval_1",
  "type": "approval",
  "data": {
    "label": "Manager Approval",
    "approvers": ["user_123", "user_456"],
    "approval_type": "any",
    "timeout_hours": 48,
    "message": "Please review:\n\n{{input.summary}}"
  }
}

---

Template Expressions

Workflow nodes support template expressions using double curly braces:

Variable Access

{{input}}                    - Workflow input data
{{input.email}}              - Nested property
{{node_1.output}}            - Previous node output
{{node_1.output.data.id}}    - Deep property access
{{secrets.API_KEY}}          - Secret variables
{{env.NODE_ENV}}             - Environment variables

Filters

{{input.name | uppercase}}         - Convert to uppercase
{{input.name | lowercase}}         - Convert to lowercase
{{input.items | length}}           - Array length
{{input.data | json}}              - JSON stringify
{{input.text | truncate:50}}       - Truncate to 50 chars
{{input.date | date:'YYYY-MM-DD'}} - Format date

Defaults

{{input.value ?? 'default'}}  - Default if null/undefined
{{input.name || 'Anonymous'}} - Fallback if falsy

---

Error Handling

All error responses follow a consistent format:

jsonCopy
{
  "error": {
    "code": "workflow_validation_error",
    "message": "Workflow definition is invalid",
    "details": {
      "errors": [
        { "node_id": "node_3", "message": "Condition expression is malformed" },
        { "message": "Node 'node_7' has no incoming connections" }
      ]
    }
  }
}