Workflows API

Create, manage, and execute visual workflows.

Endpoints

Method	Endpoint	Description
GET	/api/agents/{id}/workflows	List workflows
POST	/api/agents/{id}/workflows	Create workflow
GET	/api/agents/{id}/workflows/{workflowId}	Get workflow
PUT	/api/agents/{id}/workflows/{workflowId}	Update workflow
DELETE	/api/agents/{id}/workflows/{workflowId}	Delete workflow
POST	/api/agents/{id}/workflows/execute	Execute workflow

List Workflows

GET /api/agents/{id}/workflows

Query Parameters

Parameter	Type	Description
status	string	Filter by status
limit	number	Max results (default: 50)
offset	number	Skip results

Response

{
  "workflows": [
    {
      "id": "workflow-123",
      "name": "Email Notification",
      "description": "Send email on events",
      "status": "active",
      "created_at": "2024-12-01T00:00:00Z",
      "updated_at": "2024-12-15T10:00:00Z"
    }
  ],
  "meta": {
    "total": 10,
    "limit": 50,
    "offset": 0
  }
}

Create Workflow

POST /api/agents/{id}/workflows
Content-Type: application/json

Request Body

{
  "name": "Email Notification",
  "description": "Send email on events",
  "nodes": [
    {
      "id": "trigger-1",
      "type": "trigger",
      "position": { "x": 100, "y": 100 },
      "data": { "event": "schedule" }
    },
    {
      "id": "email-1",
      "type": "email",
      "position": { "x": 300, "y": 100 },
      "data": {
        "to": "{{contact.email}}",
        "subject": "Notification",
        "body": "Hello {{contact.name}}"
      }
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "source": "trigger-1",
      "target": "email-1"
    }
  ],
  "status": "draft"
}

Response

{
  "id": "workflow-123",
  "name": "Email Notification",
  "status": "draft",
  "created_at": "2024-12-15T10:00:00Z"
}

Get Workflow

GET /api/agents/{id}/workflows/{workflowId}

Response

{
  "id": "workflow-123",
  "name": "Email Notification",
  "description": "Send email on events",
  "nodes": [...],
  "edges": [...],
  "status": "active",
  "created_at": "2024-12-01T00:00:00Z",
  "updated_at": "2024-12-15T10:00:00Z"
}

Update Workflow

PUT /api/agents/{id}/workflows/{workflowId}
Content-Type: application/json

Request Body

{
  "name": "Updated Workflow",
  "nodes": [...],
  "edges": [...],
  "status": "active"
}

Delete Workflow

DELETE /api/agents/{id}/workflows/{workflowId}

Response

{
  "success": true
}

Execute Workflow

POST /api/agents/{id}/workflows/execute
Content-Type: application/json

Request Body

{
  "workflow_id": "workflow-123",
  "input": {
    "contact": {
      "name": "John",
      "email": "john@example.com"
    }
  }
}

Response

{
  "execution_id": "exec-456",
  "status": "running",
  "started_at": "2024-12-15T10:00:00Z"
}

Execution Status

Get Execution

GET /api/agents/{id}/workflows/executions/{executionId}

Response

{
  "id": "exec-456",
  "workflow_id": "workflow-123",
  "status": "complete",
  "input": {...},
  "output": {...},
  "started_at": "2024-12-15T10:00:00Z",
  "completed_at": "2024-12-15T10:00:05Z",
  "node_results": [
    {
      "node_id": "trigger-1",
      "status": "complete",
      "duration_ms": 10
    },
    {
      "node_id": "email-1",
      "status": "complete",
      "duration_ms": 500
    }
  ]
}

Execution Statuses

Status	Description
queued	Waiting to start
running	Currently executing
complete	Finished successfully
errored	Failed with error
terminated	Manually stopped

List Executions

GET /api/agents/{id}/workflows/executions?workflow_id={workflowId}&limit=50

Response

{
  "executions": [
    {
      "id": "exec-456",
      "workflow_id": "workflow-123",
      "status": "complete",
      "started_at": "2024-12-15T10:00:00Z",
      "completed_at": "2024-12-15T10:00:05Z"
    }
  ]
}

Workflow Status

Status	Description
draft	Not ready for execution
active	Ready for execution
paused	Temporarily disabled
archived	No longer in use

Node Types

Type	Description
trigger	Start node
if-else	Conditional branching
switch	Multi-way branching
loop	Iterate over items
wait	Delay execution
http-request	Make HTTP requests
email	Send email
telegram	Send Telegram message
slack	Send Slack message
navigate	Browser navigation
click	Browser click
chat	AI conversation
code	Execute JavaScript

Errors

Code	Description
400	Invalid workflow data
404	Workflow not found
409	Execution already running

Examples

Create and Execute

# Create workflow
curl -X POST https://your-domain.com/api/agents/{id}/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Simple Flow",
    "nodes": [...],
    "edges": [...],
    "status": "active"
  }'

# Execute
curl -X POST https://your-domain.com/api/agents/{id}/workflows/execute \
  -d '{"workflow_id": "workflow-123", "input": {}}'