Flows

Worked flows samples

The endpoint list below documents each operation’s parameters; this overlay walks the chain a runner actually executes, in order, with the exact envelopes you branch on: create the draft → publish → execute → poll the execution → inspect node results, plus the two error shapes to handle. Every request uses your API key (X-API-Key) against https://api.orbit.devotel.io. Links on this page are relative to it; the examples below tab cURL and Node.js (TypeScript). See the recipes guide for templated use cases — welcome series, appointment reminders, support triage, surveys, and order updates with copy-ready definitions. This overlay stays at envelope level: what you send per operation, and what comes back.

1. Create the flow draft

POST /api/v1/flows creates the flow as a draft at version: 1. The definition graph carries nodes (each with an id and type) and edges (source → target between node ids). trigger_type is one of manual, webhook, schedule, event, or workflow; a schedule trigger also needs a 5-field cron_expr and optionally an IANA cron_tz (UTC otherwise) — a missing or unparseable expression is rejected with a 422 (see Errors).

curl -X POST "https://api.orbit.devotel.io/api/v1/flows" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly re-engagement",
    "description": "Message opted-in customers who went quiet this week.",
    "definition": {
      "nodes": [
        { "id": "trigger_1", "type": "trigger" },
        { "id": "sms_1", "type": "send_sms", "config": { "message": "Still interested? Reply YES." } }
      ],
      "edges": [
        { "source": "trigger_1", "target": "sms_1" }
      ]
    },
    "trigger_type": "schedule",
    "cron_expr": "0 9 * * 1",
    "cron_tz": "America/New_York"
  }'

const res = await fetch("https://api.orbit.devotel.io/api/v1/flows", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ORBIT_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Weekly re-engagement",
    description: "Message opted-in customers who went quiet this week.",
    definition: {
      nodes: [
        { id: "trigger_1", type: "trigger" },
        { id: "sms_1", type: "send_sms", config: { message: "Still interested? Reply YES." } },
      ],
      edges: [{ source: "trigger_1", target: "sms_1" }],
    },
    trigger_type: "schedule",
    cron_expr: "0 9 * * 1",
    cron_tz: "America/New_York",
  }),
});
console.log(await res.json());

201

{
  "data": {
    "id": "flow_9c3f1a8e",
    "name": "Weekly re-engagement",
    "status": "draft",
    "version": 1,
    "trigger_type": "schedule",
    "cron_expr": "0 9 * * 1",
    "cron_tz": "America/New_York"
  },
  "meta": {
    "request_id": "req_flow_create",
    "timestamp": "2026-08-27T12:00:00Z"
  }
}

Nothing runs while the flow is a draft. Publishing freezes the current definition as an immutable version and returns the flow with its new status and version:

curl -X POST "https://api.orbit.devotel.io/api/v1/flows/flow_9c3f1a8e/publish" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

200

{
  "data": {
    "id": "flow_9c3f1a8e",
    "name": "Weekly re-engagement",
    "status": "published",
    "version": 2
  },
  "meta": {
    "request_id": "req_flow_publish",
    "timestamp": "2026-08-27T12:01:00Z"
  }
}

2. Execute and poll

POST /api/v1/flows/{id}/execute starts one run. trigger_data is merged into the execution’s trigger context, so a node template like {{order_total}} resolves at run time. The run is accepted asynchronously (202) with the new execution id — poll GET /api/v1/flows/executions/{id} for the outcome.

curl -X POST "https://api.orbit.devotel.io/api/v1/flows/flow_9c3f1a8e/execute" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_data": {
      "contact_id": "ctt_4d1e9a72",
      "order_total": "129.00",
      "currency": "USD"
    }
  }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/flows/flow_9c3f1a8e/execute",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      trigger_data: {
        contact_id: "ctt_4d1e9a72",
        order_total: "129.00",
        currency: "USD",
      },
    }),
  },
);
console.log(await res.json());

202

{
  "data": {
    "id": "exec_7b2d1aa4",
    "flow_id": "flow_9c3f1a8e",
    "status": "running"
  },
  "meta": {
    "request_id": "req_flow_execute",
    "timestamp": "2026-08-27T12:02:00Z"
  }
}

Poll the execution until data.status leaves running (waiting means a defer node is parked; terminal states are completed, completed_with_errors, failed, timeout). The response carries the normalized per-node step trace — each step’s name, mapped status, and duration_ms — so you can see exactly which node a run stopped on:

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

200

{
  "data": {
    "id": "exec_7b2d1aa4",
    "flow_id": "flow_9c3f1a8e",
    "status": "completed",
    "steps": [
      { "name": "Trigger", "node_id": "trigger_1", "status": "completed", "duration_ms": 4 },
      { "name": "Send sms", "node_id": "sms_1", "status": "completed", "duration_ms": 231 }
    ],
    "error": null,
    "started_at": "2026-08-27T12:02:01Z",
    "completed_at": "2026-08-27T12:02:02Z"
  },
  "meta": {
    "request_id": "req_flow_execution_get",
    "timestamp": "2026-08-27T12:02:05Z"
  }
}

When the fan-out you want is a contact or a list rather than raw context, use POST /api/v1/flows/{id}/start below — it merges your context the same way but also records which subject was enrolled.

3. Errors

Errors follow the { error, meta } envelope; quote meta.request_id when reporting a failure. 422 — invalid node graph or schedule. The create call below declares a schedule trigger with no cron_expr (the same 422 fires for an unparseable expression, or a graph whose edges reference a node id that doesn’t exist):

curl -X POST "https://api.orbit.devotel.io/api/v1/flows" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Broken schedule",
    "definition": { "nodes": [], "edges": [] },
    "trigger_type": "schedule"
  }'

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "trigger_type='schedule' requires a cron_expr",
    "status": 422,
    "details": { "field": "cron_expr" }
  },
  "meta": {
    "request_id": "req_flow_create_422",
    "timestamp": "2026-08-27T12:03:00Z"
  }
}

404 — unknown execution id. Polling an execution id your tenant doesn’t have (a typo, or an id from a different environment) returns 404 in the same envelope:

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

404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Flow execution not found",
    "status": 404
  },
  "meta": {
    "request_id": "req_flow_execution_404",
    "timestamp": "2026-08-27T12:04:00Z"
  }
}

API Reference

All Endpoints

Worked flows samples

1. Create the flow draft

2. Execute and poll

3. Errors

​Worked flows samples

​1. Create the flow draft

​2. Execute and poll

​3. Errors

Worked flows samples

1. Create the flow draft

2. Execute and poll

3. Errors