Skip to main content

​
Flows API

Build visual automation workflows that trigger on events (incoming message, webhook, schedule) and execute multi-step logic — send messages, call APIs, branch on conditions, invoke AI agents, and more. Base path: /v1/flows

​
Create Flow

POST /v1/flows Create a new automation flow.
​
name
string
required
Flow name
​
trigger_type
string
required
What starts this flow: inbound_message, webhook, schedule, api, event
​
definition
object
required
Flow definition — a JSON object representing the node graph from the visual builder. Contains nodes, edges, and configuration for each step.
curl -X POST https://orbit-api.devotel.io/api/v1/flows \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Flow",
    "trigger_type": "inbound_message",
    "definition": {
      "nodes": [
        { "id": "trigger", "type": "trigger", "data": { "channel": "whatsapp" } },
        { "id": "reply", "type": "send_message", "data": { "body": "Welcome! How can we help?" } }
      ],
      "edges": [
        { "source": "trigger", "target": "reply" }
      ]
    }
  }'

{
  "data": {
    "id": "flw_abc123",
    "name": "Welcome Flow",
    "trigger_type": "inbound_message",
    "status": "draft",
    "version": 1,
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_flw_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
List Flows

GET /v1/flows Retrieve all flows with cursor-based pagination.
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)

​
Get Flow

GET /v1/flows/{id} Retrieve a flow by ID, including its full definition.
​
id
string
required
Flow ID (e.g., flw_abc123)

​
Update Flow

PUT /v1/flows/{id} Update a flow’s name, trigger, or definition. Each update increments the version number.
​
id
string
required
Flow ID
​
name
string
Updated flow name
​
trigger_type
string
Updated trigger type
​
definition
object
Updated flow definition (node graph)
​
version
integer
Expected current version (for optimistic concurrency control). The update is rejected if the stored version does not match.

​
Delete Flow

DELETE /v1/flows/{id} Delete a flow. Running executions are allowed to complete but no new executions will start.
​
id
string
required
Flow ID
Response: 204 No Content

​
List Executions

GET /v1/flows/executions Retrieve flow execution logs across all flows, ordered by most recent.
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)
curl "https://orbit-api.devotel.io/api/v1/flows/executions?limit=10" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "exec_001",
      "flow_id": "flw_abc123",
      "flow_name": "Welcome Flow",
      "trigger_type": "inbound_message",
      "status": "completed",
      "steps_executed": 3,
      "started_at": "2026-03-08T11:00:00Z",
      "completed_at": "2026-03-08T11:00:02Z",
      "duration_ms": 2100
    },
    {
      "id": "exec_002",
      "flow_id": "flw_def456",
      "flow_name": "Order Notification",
      "trigger_type": "webhook",
      "status": "failed",
      "steps_executed": 2,
      "error": "Timeout waiting for external API response",
      "started_at": "2026-03-08T10:30:00Z",
      "completed_at": "2026-03-08T10:30:31Z",
      "duration_ms": 31000
    }
  ],
  "meta": {
    "request_id": "req_exec_001",
    "timestamp": "2026-03-08T12:00:00Z",
    "pagination": {
      "cursor": "cur_exec_abc",
      "has_more": true
    }
  }
}