Workflows API

Complete API reference for managing workflows with JavaScript, cURL, and MCP examples.

Overview

Workflows define the processing logic for incoming messages. Each workflow contains:

Workflow Data: A tree structure of connected entities (events, prompts, actions)
isActive: Whether the workflow processes incoming messages
Organization/Environment: Scope for the workflow

Endpoints

Operation	Method	Endpoint
List	GET	`/api/workflows`
Create	POST	`/api/workflows`
Get by ID	GET	`/api/workflows/{id}`
Update	PUT	`/api/workflows/{id}`
Delete	DELETE	`/api/workflows/{id}`
Trigger	POST	`/api/workflows/{id}/trigger`
List Versions	GET	`/api/workflows/{id}/versions`
Get Version	GET	`/api/workflows/{id}/versions/{versionId}`

List Workflows

Retrieve workflows with optional filtering.

cURL

curl -X GET "https://console.rocketwavelabs.io/api/workflows?organizationId=ORG_UUID&environmentId=ENV_UUID&page=1&limit=10" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

JavaScript

// Using fetch directly
const response = await fetch('/api/workflows?organizationId=ORG_UUID&environmentId=ENV_UUID', {
  credentials: 'include'
});
const data = await response.json();
console.log(data.data);       // Array of workflows
console.log(data.pagination); // { page, limit, total, totalPages }

MCP

const response = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'workflows_list',
    arguments: {
      organizationId: 'ORG_UUID',
      environmentId: 'ENV_UUID',
      page: 1,
      limit: 10
    }
  })
});

Query Parameters

Parameter	Type	Required	Description
`organizationId`	UUID	Yes	Filter by organization
`environmentId`	UUID	No	Filter by environment
`isActive`	boolean	No	Filter by active status
`hasScheduledEvents`	boolean	No	Filter workflows with scheduled events
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 10)

Response

{
  "data": [
    {
      "id": "60b623c2-c144-46b1-abec-83b684a41555",
      "organizationId": "ORG_UUID",
      "environmentId": "ENV_UUID",
      "name": "Social Media Pipeline",
      "description": "Process social media events",
      "isActive": true,
      "hasScheduledEvents": true,
      "workflowData": { ... },
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-01-29T14:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 5, "totalPages": 1 }
}

Create Workflow

Create a new workflow.

cURL

curl -X POST "https://console.rocketwavelabs.io/api/workflows" \
  -H "Content-Type: application/json" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN" \
  -d '{
    "organizationId": "ORG_UUID",
    "environmentId": "ENV_UUID",
    "name": "My Workflow",
    "description": "Process incoming events",
    "isActive": false,
    "workflowData": {
      "nodes": {
        "n1": {
          "entityId": "EVENT_ENTITY_UUID",
          "name": "Start Event",
          "entityType": "event",
          "tfCondition": "Single Path",
          "presentation": { "type": "circle", "position": { "x": 100, "y": 200 } }
        }
      },
      "connectors": {},
      "workflow": {
        "ref": "n1",
        "children": []
      },
      "presentation": { "viewport": { "x": 0, "y": 0, "zoom": 100 } }
    }
  }'

JavaScript

const response = await fetch('/api/workflows', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    organizationId: 'ORG_UUID',
    environmentId: 'ENV_UUID',
    name: 'My Workflow',
    description: 'Process incoming events',
    isActive: false,
    workflowData: {
      nodes: {
        n1: {
          entityId: 'EVENT_ENTITY_UUID',
          name: 'Start Event',
          entityType: 'event',
          tfCondition: 'Single Path',
          presentation: { type: 'circle', position: { x: 100, y: 200 } }
        }
      },
      connectors: {},
      workflow: { ref: 'n1', children: [] },
      presentation: { viewport: { x: 0, y: 0, zoom: 100 } }
    }
  })
});

MCP

const response = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'workflows_create',
    arguments: {
      organizationId: 'ORG_UUID',
      environmentId: 'ENV_UUID',
      name: 'My Workflow',
      description: 'Process incoming events',
      isActive: true
    }
  })
});

Request Body

Field	Type	Required	Description
`organizationId`	UUID	Yes	Organization ID
`environmentId`	UUID	Yes	Environment ID
`name`	string	Yes	Workflow name
`description`	string	No	Workflow description
`isActive`	boolean	No	Whether workflow is active (default: false)
`workflowData`	object	No	Workflow tree structure

Get Workflow by ID

Retrieve a single workflow by its ID.

cURL

curl -X GET "https://console.rocketwavelabs.io/api/workflows/WORKFLOW_UUID" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

JavaScript

const response = await fetch('/api/workflows/WORKFLOW_UUID', {
  credentials: 'include'
});
const workflow = await response.json();

MCP

const response = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'workflows_get',
    arguments: { id: 'WORKFLOW_UUID' }
  })
});

Update Workflow

Update an existing workflow.

cURL

curl -X PUT "https://console.rocketwavelabs.io/api/workflows/WORKFLOW_UUID" \
  -H "Content-Type: application/json" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN" \
  -d '{
    "name": "Updated Workflow Name",
    "isActive": true
  }'

JavaScript

const response = await fetch('/api/workflows/WORKFLOW_UUID', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'Updated Workflow Name',
    isActive: true
  })
});

MCP

const response = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'workflows_update',
    arguments: {
      id: 'WORKFLOW_UUID',
      name: 'Updated Workflow Name',
      isActive: true
    }
  })
});

Delete Workflow

Permanently delete a workflow.

cURL

curl -X DELETE "https://console.rocketwavelabs.io/api/workflows/WORKFLOW_UUID" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

JavaScript

await fetch('/api/workflows/WORKFLOW_UUID', {
  method: 'DELETE',
  credentials: 'include'
});

MCP

const response = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'workflows_delete',
    arguments: { id: 'WORKFLOW_UUID' }
  })
});

Trigger Workflow (Manual Execution)

Manually trigger a workflow execution. This is useful for testing workflows or triggering them on-demand without waiting for an incoming message or scheduled event.

cURL

curl -X POST "https://console.rocketwavelabs.io/api/workflows/WORKFLOW_UUID/trigger" \
  -H "Content-Type: application/json" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN" \
  -d '{}'

JavaScript

const response = await fetch('/api/workflows/WORKFLOW_UUID/trigger', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({})
});

const result = await response.json();
console.log(result.success);  // true
console.log(result.message);  // "Workflow triggered successfully"

MCP

const response = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'workflows_trigger',
    arguments: { id: 'WORKFLOW_UUID' }
  })
});

Response

{
  "success": true,
  "message": "Workflow triggered successfully"
}

note

The workflow must be active (isActive: true) to be triggered. The trigger creates a synthetic message that flows through the workflow's event tree.

Version History

Workflows maintain a version history. Each update increments the version number.

List Versions

curl -X GET "https://console.rocketwavelabs.io/api/workflows/WORKFLOW_UUID/versions" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

Get Specific Version

curl -X GET "https://console.rocketwavelabs.io/api/workflows/WORKFLOW_UUID/versions/VERSION_UUID" \
  -H "Cookie: rocketwave_session=YOUR_SESSION_TOKEN"

MCP

// List versions
const versionsResponse = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'workflows_versions',
    arguments: { id: 'WORKFLOW_UUID' }
  })
});

// Get specific version
const versionResponse = await fetch('/api/mcp/tools/call', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'workflows_version_get',
    arguments: { 
      id: 'WORKFLOW_UUID',
      versionId: 'VERSION_UUID'
    }
  })
});

Workflow Data Schema

The workflowData field uses a normalized format that separates node definitions, connectors, and flow structure. See Workflow Data Schema for the complete specification.

interface WorkflowData {
  nodes: Record<string, WorkflowNodeDef>;       // Node definitions by ID (n1, n2, ...)
  connectors: Record<string, WorkflowConnector>; // Connector definitions by ID (c1, c2, ...)
  workflow: WorkflowRef;                         // Tree structure using refs
  presentation?: {
    viewport: { x: number; y: number; zoom: number; }
  };
}

interface WorkflowNodeDef {
  entityId?: string;             // UUID of WorkflowEntity (omitted for logic-branch and inline blueprint nodes)
  name: string;                  // Display name
  entityType: string;            // 'event' | 'prompt' | 'action' | 'result' | 'logic-branch' | 'workflow'
  tfCondition?: string;          // 'Single Path' | 'True/False' | 'Multi' | 'Iterable'
  logicField?: string;           // Variable name for Multi/Iterable branching
  logicValues?: Array<{ name: string; value: string }>;  // Branch definitions (mirrors entity logic)
  branchValue?: string;          // For logic-branch nodes: the value to match
  workflowId?: string;           // For workflow nodes: target sub-workflow UUID
  presentation: {
    type: string;                // 'circle' | 'star' | 'octagon' | 'brain' | 'rounded-square' | 'logic-branch'
    position: { x: number; y: number; }
  };
}

interface WorkflowConnector {
  source: string;                // Source node ID (e.g., "n1")
  target: string;                // Target node ID (e.g., "n2")
  sourcePort: string;            // 'out', 'true', 'false'
  targetPort: string;            // 'in'
}

interface WorkflowRef {
  ref: string;                   // Node ID reference (e.g., "n1")
  value?: string;                // Branch value for logic-branch refs
  children: WorkflowRef[];       // Child references
}

Multi-Branch Workflows

When building a workflow with Multi branching via the API, ensure the entity has logic values set (see Entity API). The logic-branch nodes in workflowData must have branchValue entries that correspond to the entity's logic values, and the workflow tree refs must carry matching value fields.

Workflow Canvas — Visual workflow builder
Workflow Entities — Entity management
Scheduled Events — Scheduled workflow triggers
MCP API — Model Context Protocol integration

Overview​

Endpoints​

List Workflows​

cURL​

JavaScript​

MCP​

Query Parameters​

Response​

Create Workflow​

cURL​

JavaScript​

MCP​

Request Body​

Get Workflow by ID​

cURL​

JavaScript​

MCP​

Update Workflow​

cURL​

JavaScript​

MCP​

Delete Workflow​

cURL​

JavaScript​

MCP​

Trigger Workflow (Manual Execution)​

cURL​

JavaScript​

MCP​

Response​

Version History​

List Versions​

Get Specific Version​

MCP​

Workflow Data Schema​

Related Topics​

Overview

Endpoints

List Workflows

cURL

JavaScript

MCP

Query Parameters

Response

Create Workflow

cURL

JavaScript

MCP

Request Body

Get Workflow by ID

cURL

JavaScript

MCP

Update Workflow

cURL

JavaScript

MCP

Delete Workflow

cURL

JavaScript

MCP

Trigger Workflow (Manual Execution)

cURL

JavaScript

MCP

Response

Version History

List Versions

Get Specific Version

MCP

Workflow Data Schema

Related Topics