Build with the Developer API

The Developer API is the pillar behind Orbit’s own developer dashboard — it is not a channel like SMS or Voice, it is the tooling you use while integrating with those channels. This guide walks through what it’s for and when to reach for each piece: exercising an endpoint before you write code, watching usage and errors as you ship, capping what a key can do, debugging a webhook that didn’t arrive, streaming the platform event feed into your own Kafka topic or HTTP collector, and registering a marketplace app that requests scoped access to a customer’s org. Every endpoint in this guide requires an owner, admin, or developer role on the calling key or session; read-only usage endpoints also accept viewer.

Explore the API without leaving the dashboard

The try-it console proxies a request through your browser session using a key you supply, so you can hit any endpoint without copying curl into a terminal:

curl -X POST https://api.orbit.devotel.io/api/v1/developer/try-it \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "path": "/messages?limit=5",
    "api_key": "dv_live_sk_the_key_to_exercise"
  }'

The response wraps the real upstream status_code, headers, and body so failures (a 422 from a bad query param, a 429 from rate limiting) show up exactly as they would to your own code. api_key only accepts dv_live_sk_, dv_test_sk_, dv_live_pk_, or dv_test_pk_ prefixed values — it will not forward a request signed with something else. Pair it with two read-only catalogs when you’re deciding what to integrate against:

GET /developer/sdks — every official SDK (Node, web, Python, Go, PHP, Ruby, Java, C#) with its package name, install command, and a published flag. A published: false entry describes the future registry shape — don’t ship an install command for it yet.
GET /developer/api-versions — the dated version registry. Send X-Api-Version: 2026-01-15 (or similar) on any request to pin a specific dated behavior; the response echoes back resolved_version so you can confirm what you actually got.

When the read you need spans related resources — a contact with its conversations and messages, or a segment with its contacts — the developer GraphQL surface returns that tree in one request instead of fanning out over per-resource REST endpoints. Query the GraphQL surface covers the endpoints, the published schema, and the dashboard Explorer (Developer → GraphQL).

Track usage and spend

Two endpoints answer “how is my integration doing” at different resolutions. GET /developer/usage-stats?period=7d (24h / 7d / 30d / 90d) rolls up messages per channel — sent, delivered, failed, and cost — for the developer dashboard’s summary cards:

curl "https://api.orbit.devotel.io/api/v1/developer/usage-stats?period=7d" \
  -H "X-API-Key: dv_live_sk_your_key_here"

The /developers/api-analytics/* group goes deeper, over raw HTTP request telemetry rather than message sends:

Endpoint	Answers
`GET /developers/api-analytics/overview`	Request volume, success/error split, latency percentiles
`GET /developers/api-analytics/endpoints`	Per-endpoint request count, error rate, latency
`GET /developers/api-analytics/timeseries`	Gap-filled time series for charting volume and errors
`GET /developers/api-analytics/rate-limits`	How close each bucket is running to its configured cap
`GET /developers/api-analytics/by-key`	Per-key attribution — volume, last-used-at, last-used-ip
`POST /developers/api-analytics/ask`	Plain-English question over your own telemetry, e.g. `"what's my p95 latency this week?"`

curl -X POST https://api.orbit.devotel.io/api/v1/developers/api-analytics/ask \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "question": "which endpoints error the most today?" }'

Govern what each key can do

GET /developer/governance returns the org-wide default requests-per-minute cap and monthly quota, plus every key’s effective limits, live usage, and whether it has crossed the alert threshold:

curl https://api.orbit.devotel.io/api/v1/developer/governance \
  -H "X-API-Key: dv_live_sk_your_key_here"

Tighten (or loosen, within platform bounds) one key without touching the org default:

curl -X PUT https://api.orbit.devotel.io/api/v1/developer/governance/keys/key_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "requests_per_minute": 60, "monthly_request_quota": 100000 }'

Send null on a field to make that key inherit the org default again; PUT /developer/governance/org changes the org-wide default the same way. Only the fields you send change — omitted fields keep their current value.

Debug your inbound webhook deliveries

GET /developer/inbound-webhooks lists every inbound webhook call your endpoint received (or should have), and GET /developer/inbound-webhooks/:id returns one call’s full request/response detail — the fastest way to answer “did Orbit actually send this, and what did my server say back”:

curl "https://api.orbit.devotel.io/api/v1/developer/inbound-webhooks?limit=20" \
  -H "X-API-Key: dv_live_sk_your_key_here"

See Webhooks → Security for verifying the signature on what you receive.

Stream platform events to your own infrastructure

If you’d rather consume Orbit’s event feed (message.*, call.*, and the rest of the webhook event taxonomy) as a stream instead of one HTTP callback per event, configure a sink. kind is kafka or http_batch:

curl -X PATCH https://api.orbit.devotel.io/api/v1/developer/event-sinks/http_batch \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "destination": { "kind": "http_batch", "url": "https://collector.example.com/ingest" },
    "credentials": "Bearer your-collector-token"
  }'

GET /developer/event-sinks/:kind reads the config back — the credential is write-only and never returned in plaintext, only a credentials_configured flag. The inverse direction — pulling your own Kafka topic into Orbit — is the event-source surface. Configure it the same way, then dry-run one batch before wiring up a permanent consumer:

curl -X POST https://api.orbit.devotel.io/api/v1/developer/event-sources/kafka/consume-batch \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "orbit.events.sample",
    "messages": [
      { "partition": 0, "offset": 1001, "value": "{\"type\":\"custom.example\"}" }
    ]
  }'

consume-batch runs one polled batch through Orbit’s validation and returns the per-message disposition — no broker connection is opened and nothing is persisted, so it’s safe to run against production credentials while you’re still mapping your event types.

Register a marketplace OAuth app

Building an app that requests scoped access to a customer’s Orbit org (rather than using your own API key) goes through the OAuth app surface:

GET /developers/oauth/scopes — the closed catalog of grantable scopes (e.g. messages:read, contacts:write), each with its consent-screen label.
GET /developers/oauth/consent-preview?scope=messages:read%20contacts:write — renders the exact consent rows a customer would see for a scope string, and flags any scope outside the grantable catalog before you ship a request that would be rejected.
GET /developers/oauth/manifest — downloads the deterministic client-registration manifest, pre-wired to your org’s API host, as orbit-<your-org>.oauth-app.json.

curl "https://api.orbit.devotel.io/api/v1/developers/oauth/consent-preview?scope=messages:read%20contacts:write" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Automate without writing an SDK integration

For no-code and low-code workflows, download a pre-wired definition instead of hand-rolling requests:

GET /developers/postman-collection / GET /developers/postman-environment — a full Postman collection covering every public endpoint, plus an environment pre-filled with your base URL and org id (the API-key variable ships blank for you to paste in).
GET /developers/connector/zapier, GET /developers/connector/make, GET /developers/connector/n8n — platform-specific app/blueprint/node-pack definitions for Zapier, Make, and n8n. GET /developers/connector/catalog lists every trigger and action across all three without downloading the full definitions.
GET /developers/cdp-sdk/catalog and GET /developers/cdp-sdk/source/:platform (web / ios / android) — drop-in client tracking SDKs, pre-wired to your org’s ingest host, for sending Customer Data Platform events straight from a browser or mobile app.

All of these are downloads (Content-Disposition: attachment) meant to be imported directly into the target tool, not parsed as an API response.

Frequently asked questions

Does the try-it console work with a live production key?

Yes — it proxies to the real API using whichever key you supply, live or test. Anything it returns is exactly what your own integration would get back, including errors and rate limiting.

Can I set a rate limit lower than the org default for one key but not others?

Yes. A per-key override in /developer/governance/keys/:keyId always wins over the org-wide default for that one key; every other key keeps inheriting the default.

What happens to event-sink deliveries if my collector is down?

Configuration and delivery are separate: this API only manages the sink’s config and credentials. The delivery worker that reads the config and pushes matching events records last_run_* status fields back onto the same config — check GET /developer/event-sinks/:kind for the latest run status.

Do I need a marketplace OAuth app just to call the API myself?

No — OAuth apps are for building something a different Orbit customer installs into their own org. If you’re integrating your own org’s API key, skip straight to Authentication.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Developer Portal: console, usage, keys, and webhook debug

Build with the Developer API

Explore the API without leaving the dashboard

Track usage and spend

Govern what each key can do

Debug your inbound webhook deliveries

Stream platform events to your own infrastructure

Register a marketplace OAuth app

Automate without writing an SDK integration

Frequently asked questions

Does the try-it console work with a live production key?

Can I set a rate limit lower than the org default for one key but not others?

What happens to event-sink deliveries if my collector is down?

Do I need a marketplace OAuth app just to call the API myself?

See also

​Build with the Developer API

​Explore the API without leaving the dashboard

​Track usage and spend

​Govern what each key can do

​Debug your inbound webhook deliveries

​Stream platform events to your own infrastructure

​Register a marketplace OAuth app

​Automate without writing an SDK integration

​Frequently asked questions

​Does the try-it console work with a live production key?

​Can I set a rate limit lower than the org default for one key but not others?

​What happens to event-sink deliveries if my collector is down?

​Do I need a marketplace OAuth app just to call the API myself?

​See also

Build with the Developer API

Explore the API without leaving the dashboard

Track usage and spend

Govern what each key can do

Debug your inbound webhook deliveries

Stream platform events to your own infrastructure

Register a marketplace OAuth app

Automate without writing an SDK integration

Frequently asked questions

Does the try-it console work with a live production key?

Can I set a rate limit lower than the org default for one key but not others?

What happens to event-sink deliveries if my collector is down?

Do I need a marketplace OAuth app just to call the API myself?

See also