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

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"
      }
    ]
  }
}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://orbit-api.devotel.io/api/v1/flows', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "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"
      }
    ]
  }
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://orbit-api.devotel.io/api/v1/flows", headers=headers, json={
  "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"
      }
    ]
  }
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://orbit-api.devotel.io/api/v1/flows", bytes.NewBuffer([]byte(`{
  "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"
      }
    ]
  }
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://orbit-api.devotel.io/api/v1/flows')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "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"
      }
    ]
  }
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://orbit-api.devotel.io/api/v1/flows');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "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"
      }
    ]
  }
}
JSON);
echo curl_exec($ch);

{
  "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.

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.

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.

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

curl -X GET "https://orbit-api.devotel.io/api/v1/flows/executions?limit=10" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://orbit-api.devotel.io/api/v1/flows/executions?limit=10', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://orbit-api.devotel.io/api/v1/flows/executions?limit=10", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://orbit-api.devotel.io/api/v1/flows/executions?limit=10", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://orbit-api.devotel.io/api/v1/flows/executions?limit=10')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://orbit-api.devotel.io/api/v1/flows/executions?limit=10');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "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
    }
  }
}

Documentation Index

​Flows API

​Create Flow

​List Flows

​Get Flow

​Update Flow

​Delete Flow

​List Executions

Flows API

Create Flow

List Flows

Get Flow

Update Flow

Delete Flow

List Executions