Workflows API

Execute Workflow

Execute workflows in single mode or parallel batch mode. The API auto-detects execution mode based on request structure.

Endpoint

POST /api/workflows/execute

Single Mode Execution

Execute a single workflow with full debugging support including breakpoints and builder mode.

Request Body

workflow

object

required

Workflow definition containing nodes and edges

Show Workflow Object

nodes

array

required

Array of workflow nodes. Each node represents an action (click, type, navigate, etc.)

edges

array

required

Array of edges connecting nodes, defining execution flow

groups

array

Optional array of node groups for organization

executionMode

string

default:"auto"

Execution mode: single, parallel, or auto (auto-detects)

workflowFileName

string

Filename for the workflow (used in reports and logs)

traceLogs

boolean

default:false

Enable detailed trace logging for debugging

recordSession

boolean

default:false

Enable video recording of browser session

screenshotConfig

object

Configure screenshot capture

Show Screenshot Configuration

enabled

boolean

required

Enable screenshot capture

timing

string

default:"post"

When to capture: pre, post, or both

reportConfig

object

Configure report generation

Show Report Configuration

enabled

boolean

required

Enable report generation

reportTypes

array

required

Report formats: html, allure, json, junit, csv, markdown

outputPath

string

default:"./output"

Output directory for reports

reportRetention

number

default:10

Number of reports to keep (older reports are deleted)

breakpointConfig

object

Configure breakpoints for debugging (single mode only)

Show Breakpoint Configuration

enabled

boolean

required

Enable breakpoints

breakpointAt

string

default:"pre"

When to pause: pre, post, or both

breakpointFor

string

default:"all"

Which nodes to pause: all or marked

builderModeEnabled

boolean

default:false

Enable builder mode for action recording (single mode only)

Example Request

curl -X POST http://localhost:3003/api/workflows/execute \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": {
      "nodes": [
        {
          "id": "start-1",
          "type": "start",
          "position": { "x": 0, "y": 0 },
          "data": {
            "url": "https://example.com",
            "headless": false
          }
        },
        {
          "id": "click-1",
          "type": "click",
          "position": { "x": 200, "y": 0 },
          "data": {
            "selector": "button.submit",
            "selectorType": "css"
          }
        }
      ],
      "edges": [
        {
          "id": "e-start-1-click-1",
          "source": "start-1",
          "target": "click-1"
        }
      ]
    },
    "executionMode": "single",
    "workflowFileName": "example-workflow.json",
    "traceLogs": true,
    "reportConfig": {
      "enabled": true,
      "reportTypes": ["html"],
      "reportRetention": 10
    }
  }'

Response

executionId

string

required

Unique execution identifier

status

string

required

Execution status: running, completed, error, stopped, idle

executionMode

string

required

Execution mode: single

Response Example

{
  "executionId": "exec-1709856234567",
  "status": "running",
  "executionMode": "single"
}

Parallel Mode Execution

Execute multiple workflows in parallel with worker pool management.

Execution Methods

Folder Path
Workflows Array
File Upload

Execute all workflows from a folder

{
  "folderPath": "./tests/workflows/sample",
  "executionMode": "parallel",
  "workers": 4,
  "recursive": true,
  "pattern": "*.json"
}

Execute workflows from an array

{
  "workflows": [
    { "nodes": [...], "edges": [...] },
    { "nodes": [...], "edges": [...] }
  ],
  "executionMode": "parallel",
  "workers": 2
}

Upload workflow files via multipart/form-data

curl -X POST http://localhost:3003/api/workflows/execute \
  -F '[email protected]' \
  -F '[email protected]' \
  -F '[email protected]' \
  -F 'workers=4' \
  -F 'traceLogs=false'

Request Parameters (Parallel Mode)

folderPath

string

Path to folder containing workflow JSON files (required for folder mode)

workflows

array

Array of workflow objects (required for workflows array mode)

workers

number

default:4

Maximum concurrent workers. Use 1 for MCP/API to avoid wait node pauses

outputPath

string

default:"./output"

Output directory for reports, logs, screenshots, and videos

recursive

boolean

default:false

Scan subdirectories when using folderPath

pattern

string

default:"*.json"

File pattern for folder scanning (glob pattern)

batchPriority

number

default:0

Batch priority for queue ordering. Higher priority batches are processed first. Default 0 = FIFO order

startNodeOverrides

object

Override Start node properties for all workflows

Show Start Node Overrides

recordSession

boolean

Override video recording setting

screenshotAllNodes

boolean

Override screenshot capture for all nodes

screenshotTiming

string

Override screenshot timing: pre, post, both

slowMo

number

Override delay in milliseconds between actions

scrollThenAction

boolean

Override scroll-before-action behavior

Example Request (Folder)

curl -X POST http://localhost:3003/api/workflows/execute \
  -H "Content-Type: application/json" \
  -d '{
    "folderPath": "./tests/workflows/sample",
    "executionMode": "parallel",
    "workers": 4,
    "recursive": true,
    "pattern": "*.json",
    "traceLogs": false,
    "reportConfig": {
      "enabled": true,
      "reportTypes": ["html", "json"],
      "reportRetention": 20
    },
    "startNodeOverrides": {
      "screenshotAllNodes": true,
      "screenshotTiming": "both"
    }
  }'

Response (Parallel Mode)

batchId

string

required

Unique batch identifier

executionMode

string

required

Execution mode: parallel

sourceType

string

required

Source type: folder, files, or workflows

folderPath

string

Folder path (if sourceType is folder)

totalWorkflows

number

required

Total number of workflows in batch

validWorkflows

number

required

Number of valid workflows

invalidWorkflows

number

required

Number of invalid workflows

validationErrors

array

Array of validation errors for invalid workflows

executions

array

required

Array of execution details

Show Execution Object

executionId

string

required

Execution ID

workflowFileName

string

required

Workflow filename

workflowPath

string

Full path to workflow file

status

string

required

Execution status

Response Example

{
  "batchId": "batch-1709856234567",
  "executionMode": "parallel",
  "sourceType": "folder",
  "folderPath": "./tests/workflows/sample",
  "totalWorkflows": 5,
  "validWorkflows": 5,
  "invalidWorkflows": 0,
  "validationErrors": [],
  "executions": [
    {
      "executionId": "exec-1709856234567-1",
      "workflowFileName": "workflow1.json",
      "workflowPath": "./tests/workflows/sample/workflow1.json",
      "status": "running"
    },
    {
      "executionId": "exec-1709856234567-2",
      "workflowFileName": "workflow2.json",
      "workflowPath": "./tests/workflows/sample/workflow2.json",
      "status": "queued"
    }
  ]
}

Scan Folder

Preview workflows in a folder without executing them. Returns validation status for each discovered file.

Endpoint

GET /api/workflows/scan

Query Parameters

folderPath

string

required

Path to folder containing workflow JSON files (relative or absolute)

recursive

boolean

default:false

Scan subdirectories

pattern

string

default:"*.json"

Glob pattern for file matching

Example Request

cURL

curl "http://localhost:3003/api/workflows/scan?folderPath=./tests/workflows&recursive=true&pattern=*.json"

Response

[
  {
    "fileName": "workflow1.json",
    "filePath": "./tests/workflows/workflow1.json",
    "isValid": true,
    "validationErrors": [],
    "workflow": {
      "nodes": [...],
      "edges": [...]
    }
  },
  {
    "fileName": "invalid-workflow.json",
    "filePath": "./tests/workflows/invalid-workflow.json",
    "isValid": false,
    "validationErrors": [
      "Missing required field: nodes",
      "Missing required field: edges"
    ]
  }
]

Error Responses

error

string

required

Error message

message

string

Detailed error description

Example Errors

400 Bad Request
404 Not Found
500 Server Error

{
  "error": "Invalid workflow format",
  "message": "Workflow must contain nodes and edges arrays"
}

{
  "error": "Folder not found",
  "message": "Path is not a directory: ./invalid/path"
}

{
  "error": "Failed to execute workflow",
  "message": "Unexpected error during execution"
}

Overview

Endpoints

Execute Workflow

Endpoint

Single Mode Execution

Request Body

Example Request

Response

Parallel Mode Execution

Execution Methods

Request Parameters (Parallel Mode)

Example Request (Folder)

Response (Parallel Mode)

Scan Folder

Endpoint

Query Parameters

Example Request

Response

Error Responses

Example Errors

Build docs developers (and LLMs) love

Overview

Endpoints

​Execute Workflow

​Endpoint

​Single Mode Execution

​Request Body

​Example Request

​Response

​Parallel Mode Execution

​Execution Methods

​Request Parameters (Parallel Mode)

​Example Request (Folder)

​Response (Parallel Mode)

​Scan Folder

​Endpoint

​Query Parameters

​Example Request

​Response

​Error Responses

​Example Errors

Build docs developers (and LLMs) love

Execute Workflow

Endpoint

Single Mode Execution

Request Body

Example Request

Response

Parallel Mode Execution

Execution Methods

Request Parameters (Parallel Mode)

Example Request (Folder)

Response (Parallel Mode)

Scan Folder

Endpoint

Query Parameters

Example Request

Response

Error Responses

Example Errors