Events API

A read-only feed of recent notable events in the platform — message sent, message delivered, agent run, flow step, contact updated, conversation created, webhook endpoint updated, etc. Two access patterns:

Polled — GET /api/v1/events pages over a bounded recent-window replay buffer (see below).
Live — GET /api/v1/events/stream opens an SSE connection that delivers events in real time.

This is not durable history. The Events API is a bounded, in-memory replay buffer (a per-tenant Redis Stream), not a system of record. It retains only the most recent ~5000 events per tenant, and the buffer expires after ~15 minutes of tenant inactivity. Older events are evicted and are gone — they cannot be paged back to. GET /api/v1/events/{id} resolves only ids still inside the current window; an evicted id returns 404. If the real-time store is briefly unavailable the surface degrades open — the list returns an empty page and a single-event lookup returns 404 rather than erroring.For a durable, complete, retry-handled record of every event — anything you’d build a system of record, audit log, or reconciliation job off of — use Webhooks instead. Do not treat this endpoint as an event log. If you do resolve event ids, handle the evicted-id 404 as a skip, not a failure — the single-event lookup sample below shows the shape.

Base path: /api/v1/events Authentication: API key (X-API-Key) or session JWT.

Method	Path	Purpose
`GET`	`/api/v1/events/`	List recent events from the replay window (paginated)
`GET`	`/api/v1/events/{id}`	Get a single recent event — only if still in the window
`GET`	`/api/v1/events/stream`	Subscribe via Server-Sent Events
`GET`	`/api/v1/events/schema-registry`	Versioned JSON Schema catalog of every event type Orbit emits

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

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

const res = await orbit.events.list();

Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

`GET /api/v1/events` response

The list endpoint returns pages of recent events inside the standard paginated envelope. Each data[] entry is one event envelope: the canonical stream id (pass it back as cursor to page forward, or as Last-Event-ID on the SSE stream to resume), the event type, the publish time ts (epoch milliseconds), and the type-specific data object.

curl "https://api.orbit.devotel.io/api/v1/events?limit=2" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "1725148800125-0",
      "type": "message.delivered",
      "ts": 1725148800090,
      "data": {
        "message_id": "msg_xyz789",
        "channel": "sms",
        "to": "+1415555****",
        "from": "+1415000****",
        "status": "delivered",
        "delivered_at": "2026-08-31T12:00:00.000Z"
      }
    },
    {
      "id": "1725148700031-2",
      "type": "agent.response",
      "ts": 1725148700004,
      "data": {
        "agent_id": "agt_abc123",
        "conversation_id": "cnv_8842",
        "status": "completed"
      }
    }
  ],
  "meta": {
    "request_id": "req_8f3a1c",
    "timestamp": "2026-08-31T12:00:04.512Z",
    "pagination": {
      "cursor": "1725148700031-2",
      "has_more": true,
      "total": 2
    }
  }
}

meta.pagination.cursor is the id of the last event on the page. When has_more is true, pass it back as ?cursor= to fetch the next page; when it is null, you are at the head of the retained window.

`GET /api/v1/events/{id}` response

A single-event lookup returns the same event envelope under data, un-wrapped from data[]:

curl "https://api.orbit.devotel.io/api/v1/events/1725148800125-0" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "1725148800125-0",
    "type": "message.delivered",
    "ts": 1725148800090,
    "data": {
      "message_id": "msg_xyz789",
      "channel": "sms",
      "to": "+1415555****",
      "from": "+1415000****",
      "status": "delivered",
      "delivered_at": "2026-08-31T12:00:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_8f3a2b",
    "timestamp": "2026-08-31T12:00:05.104Z"
  }
}

Live stream — SSE

curl -N "https://api.orbit.devotel.io/api/v1/events/stream?token=dv_live_sk_your_key_here"

Events arrive as data: lines (one JSON object per line). Reconnect on error with the Last-Event-ID header set so you don’t lose events. A consumer that just opens the stream and dies with it will miss every event emitted between the last delivered event and the reconnect. Track the last id you received and send it back as the Last-Event-ID header (or the ?lastEventId= query parameter, for clients like browser EventSource that can’t set headers) — the server replays the buffered window from that id before switching to the live tail.

// Node.js consumer (MIT: `eventsource` package)
import { EventSource } from "eventsource";

const KEY = process.env.ORBIT_API_KEY;
let lastId = null; // back this up in durable storage between restarts

function connect() {
  const suffix = lastId ? `&lastEventId=${encodeURIComponent(lastId)}` : "";
  const es = new EventSource(`https://api.orbit.devotel.io/api/v1/events/stream?token=${KEY}${suffix}`);
  es.onmessage = (msg) => {
    if (msg.id) lastId = msg.id;
    const evt = JSON.parse(msg.data);
    // handle evt ... keep the error handler registered
  };
  es.onerror = () => {
    es.close();
    // reconnect with backoff; lastId carries the resume point
    setTimeout(connect, 1000);
  };
}
connect();

# Python consumer (`pip install requests`)
import json
import time

import requests

KEY = ""
LAST_ID = None  # back this up in durable storage between restarts

def run():
    global LAST_ID
    headers = {"X-API-Key": KEY}
    if LAST_ID:
        headers["Last-Event-ID"] = LAST_ID
    with requests.get(
        "https://api.orbit.devotel.io/api/v1/events/stream",
        headers=headers,
        stream=True,
        timeout=None,
    ) as response:
        for line in response.iter_lines(decode_unicode=True):
            if line and line.startswith("id:"):
                LAST_ID = line[len("id:"):].strip()
            if line and line.startswith("data:"):
                event = json.loads(line[len("data:"):].strip())
                # handle event ...

while True:
    try:
        run()
    except requests.RequestException:
        time.sleep(1)  # LAST_ID carries the resume point on reconnect

Either pattern is enough to survive a dropped connection, but only if the last id is stored durably enough to survive a process restart. For anything you’d call a system of record, use Webhooks instead — the bounded-window warning above explains. The ?token= query parameter is promoted to X-API-Key server-side so browsers (which can’t set arbitrary headers on EventSource) can authenticate. As with every Orbit endpoint, query strings are stripped from access logs platform-wide before they’re written, so the token value is never persisted to log storage.

Schema registry — `GET /api/v1/events/schema-registry`

Before you build a pipeline off the event stream or webhooks, you need to know the shape of each event — and when that shape changes. The schema registry returns the versioned catalog of every event type Orbit emits.

curl "https://api.orbit.devotel.io/api/v1/events/schema-registry" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Each entry in data.schemas carries:

event_type — the wire-level type, e.g. message.delivered.
json_schema — the Draft-07 JSON Schema for the event envelope, with the type literal pinned. Use it to validate incoming events or to generate types.
example_payload — a realistic example envelope that validates against json_schema.
fingerprint — a sha256:<hex> content fingerprint of json_schema, so you can pin one event’s schema and detect drift.

The response also includes a top-level catalog_version (a single sha256:<hex> over every (event_type, fingerprint) pair), an event_count, and the JSON Schema dialect.

{
  "data": {
    "catalog_version": "sha256:1a2b3c4d5e6f7890",
    "event_count": 42,
    "dialect": "http://json-schema.org/draft-07/schema#",
    "schemas": [
      {
        "event_type": "message.delivered",
        "fingerprint": "sha256:0f1e2d3c4b5a6978",
        "json_schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object" },
        "example_payload": { "id": "evt_...", "type": "message.delivered", "data": {} }
      }
    ]
  },
  "meta": { "request_id": "req_...", "timestamp": "2026-08-09T12:00:00.000Z" }
}

Polling for drift. Store the catalog_version you last processed. Poll this endpoint on a schedule: while catalog_version is unchanged, nothing in the contract moved and you can skip the work. When it changes, compare each entry’s fingerprint against the one you stored to find exactly which event schemas changed, and regenerate only those types or validators. A Node generation step that does exactly that:

import { readFileSync, writeFileSync } from "node:fs";

const KEY = process.env.ORBIT_API_KEY;
const response = await fetch("https://api.orbit.devotel.io/api/v1/events/schema-registry", {
  headers: { "X-API-Key": KEY },
});
let state = {};
try {
  state = JSON.parse(readFileSync("event-catalog.json", "utf8"));
} catch {
  // first run — no stored catalog yet
}
if (response.ok) {
  const { data } = await response.json();
  if (data.catalog_version !== state.catalog_version) {
    for (const schema of data.schemas) {
      if (schema.fingerprint !== state.fingerprints?.[schema.event_type]) {
        // regenerate types/validators for schema.event_type only
      }
    }
    writeFileSync(
      "event-catalog.json",
      JSON.stringify({
        catalog_version: data.catalog_version,
        fingerprints: Object.fromEntries(data.schemas.map((s) => [s.event_type, s.fingerprint])),
      }),
    );
  }
}

The same loop in Python:

import json
import os
import requests

response = requests.get(
    "https://api.orbit.devotel.io/api/v1/events/schema-registry",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
try:
    state = json.load(open("event-catalog.json"))
except (FileNotFoundError, IOError):
    state = {}
if response.ok:
    data = response.json()["data"]
    if data["catalog_version"] != state.get("catalog_version"):
        for schema in data["schemas"]:
            if schema["fingerprint"] != state.get("fingerprints", {}).get(schema["event_type"]):
                pass  # regenerate types/validators for this event_type
        json.dump(
            {
                "catalog_version": data["catalog_version"],
                "fingerprints": {s["event_type"]: s["fingerprint"] for s in data["schemas"]},
            },
            open("event-catalog.json", "w"),
        )

The catalog is read-only, takes no query parameters, and is identical for every account — so you can cache it and check it cheaply.

Event type samples

Every event shares the same envelope — id, type, ts, and a data object whose shape is specific to the event type. The tabs below show the data shape for three common types. For the full catalog of every event type and its JSON Schema, see Webhook events, or fetch the machine-readable schema registry above.

message.sent / message.delivered
agent.response
flow.execution.started

{
  "message_id": "msg_xyz789",
  "channel": "sms",
  "to": "+1415555****",
  "from": "+1415000****",
  "status": "delivered",
  "delivered_at": "2026-08-31T12:00:00.000Z"
}

A failed delivery replaces delivered_at with carrier detail in error_code / error_message.

{
  "agent_id": "agt_abc123",
  "conversation_id": "cnv_8842",
  "status": "completed"
}

All agent.* lifecycle and runtime events (agent.created, agent.updated, agent.deployed, agent.response, agent.handoff.*) key their resource id on agent_id; conversation events add conversation_id.

{
  "flow_id": "flw_runbook",
  "execution_id": "exe_91aa",
  "id": "exe_91aa"
}

flow.* events key their resource id on flow_id; execution events add execution_id (mirrored as a top-level id on flow.execution.started).

Handling `404` on evicted ids

A single-event lookup (GET /api/v1/events/{id}) that returns 404 is not an error for a consumer pipeline — it means the id aged out of the bounded window described above. The body looks like this:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Event '1725148800125-0' not found",
    "status": 404
  },
  "meta": {
    "request_id": "req_8f3a3d",
    "timestamp": "2026-08-31T12:00:06.221Z"
  }
}

Treat it as a skipped event, not a failed request:

const response = await fetch(`https://api.orbit.devotel.io/api/v1/events/${id}`, {
  headers: { "X-API-Key": KEY },
});
if (response.status === 404) {
  // the id aged out of the replay window — skip and continue
} else if (response.ok) {
  const { data } = await response.json();
  // handle data ...
}

The same guard applies anywhere you resolve ids you haven’t verified inside the current window. If the resolve path is the critical path of what you rebuild — don’t rebuild from this feed; subscribe to Webhooks instead.

Ingesting events — `POST /api/v1/events/track`

To record your own product events (rather than read the feed above), POST to the ingestion endpoint with an event name, an optional contact identifier (contact_email or contact_phone — omit both to store the event without linking it to a contact), and an optional properties object:

curl -X POST "https://api.orbit.devotel.io/api/v1/events/track" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Order Placed",
    "contact_email": "buyer@example.com",
    "properties": { "order_id": "ord_123", "total_cents": 4999 }
  }'

properties payload ceiling — 1 MiB. The serialized properties JSON for a single event must not exceed 1 MiB (1,048,576 bytes). An event over the ceiling is rejected with HTTP 413 and error.code = EVENT_PAYLOAD_TOO_LARGE — nothing is stored and the contact timeline is unchanged. Keep individual attributes small: store large blobs (raw documents, base64 media, full request dumps) in your own object storage and reference them from properties by URL or id rather than embedding them inline.

API Reference

All Endpoints

Events API: platform event firehose over REST and SSE

Events API

Using the SDKs

`GET /api/v1/events` response

`GET /api/v1/events/{id}` response

Live stream — SSE

Schema registry — `GET /api/v1/events/schema-registry`

Event type samples

Handling `404` on evicted ids

Ingesting events — `POST /api/v1/events/track`

See also

​Events API

​Using the SDKs

​GET /api/v1/events response

​GET /api/v1/events/{id} response

​Live stream — SSE

​Schema registry — GET /api/v1/events/schema-registry

​Event type samples

​Handling 404 on evicted ids

​Ingesting events — POST /api/v1/events/track

​See also

Events API

Using the SDKs

`GET /api/v1/events` response

`GET /api/v1/events/{id}` response

Live stream — SSE

Schema registry — `GET /api/v1/events/schema-registry`

Event type samples

Handling `404` on evicted ids

Ingesting events — `POST /api/v1/events/track`

See also