Developer surface: worked examples with full response bodies

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/inbound-webhooks"

{
  "data": {
    "versions": [
      {
        "version": "2026-01-15",
        "status": "current",
        "released_at": "2026-01-15",
        "deprecated_at": null,
        "sunset_at": null,
        "summary": "Current stable API contract"
      }
    ],
    "default_version": "2026-01-15",
    "resolved_version": "2026-01-15",
    "migration_guide_url": "https://docs.orbit.devotel.io/guides/api-versioning"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/inbound-webhooks"

{
  "data": {
    "versions": [
      {
        "version": "2026-01-15",
        "status": "current",
        "released_at": "2026-01-15",
        "deprecated_at": null,
        "sunset_at": null,
        "summary": "Current stable API contract"
      }
    ],
    "default_version": "2026-01-15",
    "resolved_version": "2026-01-15",
    "migration_guide_url": "https://docs.orbit.devotel.io/guides/api-versioning"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

The developer surface

The developer surface is the programmatic mirror of the dashboard’s developer hub: governance and budgets for your API keys, event-stream sinks and inbound sources, API analytics, contract downloads (AsyncAPI, GraphQL SDL, Postman), SDK and connector catalogs, and OAuth marketplace metadata. It is what to hit first when provisioning an integration — everything below is read-mostly config and observability, never outbound message origination.

Sandbox routing for every operation on this page rides on the X-Test-Mode request header the auto-generated sections annotate: a sandbox opt-in for Clerk-session-authenticated calls that routes through the test-mode pipeline (no provider delivery, no credits deducted, meta.test_mode: true). Live API keys (dv_live_sk_*) ignore it; server-to-server clients exercise sandbox with a test-prefixed key (dv_test_sk_*), which enables sandbox unconditionally. The per-request pin is the same one the sandbox test-mode guide covers.

Samples below show the real success envelope a 200 returns — data plus a meta block carrying request_id and timestamp. On the download-style endpoints (contracts, blueprints, SDK sources) the body is the artifact itself rather than an envelope; those shots are quoted verbatim per the console. Errors follow the { error, meta } shape spelt out under Errors worth branching on and the tables at the bottom. For SDK walkthroughs in your language, start from the Node.js guide — the catalog endpoint below (GET /api/v1/developer/sdks) is how you discover the published coordinates programmatically, and the /api/v1/developers/cdp-sdk/* endpoints below download tenant-wired tracking SDK sources. The guides that pair with this page: developer hub overview, API governance console, developer API playground, and error handling examples for the decision matrix.

Response envelopes for the generated shells

The operations below all return a 200 whose JSON body the generated sections render as the empty "data": {} shell. Each block ships the real { data, meta } envelope the route returns — copy it as the parsing target, then pull the fields your integration actually branches on. Download operations (AsyncAPI, GraphQL SDL, Postman, connector blueprints, SDK sources, OAuth manifest) wrap a download pointer or the artifact payload inside the same envelope.

1. List dated API versions and deprecation lifecycle

GET /api/v1/developer/api-versions

{
  "data": {
    "versions": [
      {
        "version": "2026-01-15",
        "status": "current",
        "released_at": "2026-01-15",
        "deprecated_at": null,
        "sunset_at": null,
        "summary": "Current stable API contract"
      }
    ],
    "default_version": "2026-01-15",
    "resolved_version": "2026-01-15",
    "migration_guide_url": "https://docs.orbit.devotel.io/guides/api-versioning"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

2. View per-API-key spend budgets

GET /api/v1/developer/budgets

{
  "data": {
    "rows": [
      {
        "key_id": "key_01J0API",
        "name": "Production app",
        "budget": {
          "limit_minor": 10000,
          "currency": "USD",
          "alert_thresholds": [
            50,
            80,
            100
          ]
        },
        "usage": {
          "requests_minute": 42,
          "requests_month": 68420,
          "spend_minor": 1840
        },
        "alerts_triggered": []
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

3. Get the event-streaming sink config for one kind

GET /api/v1/developer/event-sinks/{kind}

{
  "data": {
    "kind": "kafka",
    "enabled": true,
    "events": [
      "message.created",
      "message.delivered"
    ],
    "destination": {
      "kind": "kafka",
      "topic": "orbit-events",
      "partition_key_path": "$.organization_id",
      "headers": {}
    },
    "brokers": [
      "kafka.example.com:9092"
    ],
    "sasl_mechanism": "scram-sha-256",
    "sasl_username": "orbit-ingest",
    "credentials_configured": true,
    "last_run_status": "ok",
    "last_produced_count": 128
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

4. Get the inbound event-source config for one kind

GET /api/v1/developer/event-sources/{kind}

{
  "data": {
    "kind": "kafka",
    "enabled": true,
    "source": {
      "kind": "kafka",
      "topic": "customer-events",
      "consumer_group": "orbit-inbound-prod",
      "type_path": "event.type"
    },
    "filter": [
      "order.created"
    ],
    "brokers": [
      "kafka.example.com:9092"
    ],
    "sasl_mechanism": "scram-sha-256",
    "sasl_username": "orbit-consumer",
    "credentials_configured": true,
    "transport_enabled": true
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

5. View API rate-limit & quota governance

GET /api/v1/developer/governance

{
  "data": {
    "organization": {
      "requests_per_minute": 1000,
      "monthly_request_quota": 1000000,
      "monthly_spend_limit_minor": 50000
    },
    "keys": [
      {
        "key_id": "key_01J0API",
        "name": "Production app",
        "effective_requests_per_minute": 500,
        "requests_minute": 42,
        "requests_month": 68420,
        "spend_month_minor": 1840,
        "quota_remaining": 931580,
        "spend_remaining_minor": 48160,
        "over_alert_threshold": false
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

6. Download the developer GraphQL schema (SDL)

GET /api/v1/developer/graphql/schema

{
  "data": {
    "filename": "orbit-graphql-schema.graphql",
    "content_type": "application/graphql",
    "download_url": "https://orbit.devotel.io/downloads/orbit-graphql-schema.graphql"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

7. List received inbound webhooks

GET /api/v1/developer/inbound-webhooks

{
  "data": {
    "status": "ok"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

8. Get an inbound webhook by id

GET /api/v1/developer/inbound-webhooks/{id}

{
  "data": {
    "id": "whlog_01J0WEBHOOK",
    "organization_id": "org_01J0ORBIT",
    "channel": "sms",
    "provider": "telnyx",
    "signature_status": "valid",
    "error_msg": null,
    "received_at": "2026-08-26T11:56:04.000Z",
    "raw_body_b64": "eyJldmVudCI6Im1lc3NhZ2UucmVjZWl2ZWQifQ==",
    "raw_body_size": 32,
    "headers": {
      "content-type": "application/json"
    },
    "parsed_event": {
      "event": "message.received"
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

9. List official SDK libraries

GET /api/v1/developer/sdks

{
  "data": {
    "sdks": [
      {
        "language": "node",
        "package_name": "@devotel-orbit/node",
        "version": "0.3.1",
        "published": true,
        "install_command": "npm install @devotel-orbit/node",
        "registry_url": "https://www.npmjs.com/package/@devotel-orbit/node",
        "docs_url": "https://docs.orbit.devotel.io/sdks/node",
        "source_url": "https://github.com/devotel/orbit-node"
      }
    ],
    "api_base_url": "https://api.orbit.devotel.io/api/v1"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

10. Get API usage statistics for the current tenant

GET /api/v1/developer/usage-stats

{
  "data": {
    "period": "30d",
    "totals": {
      "messages": 68420,
      "delivered": 67110,
      "failed": 1310,
      "error_rate": 1.91
    },
    "by_channel": {
      "sms": {
        "messages": 48200,
        "delivered": 47410,
        "failed": 790
      },
      "whatsapp": {
        "messages": 20220,
        "delivered": 19700,
        "failed": 520
      }
    },
    "daily": [
      {
        "date": "2026-08-25",
        "messages": 2410,
        "delivered": 2368,
        "failed": 42
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

11. API analytics by API key

GET /api/v1/developers/api-analytics/by-key

{
  "data": {
    "window": "30d",
    "sort": "count_30d",
    "total_keys": 2,
    "rows": [
      {
        "api_key_id": "key_01J0API",
        "name": "Production app",
        "key_prefix": "dv_live_sk_",
        "last_four_chars": "7f2a",
        "count_today": 2380,
        "count_7d": 16420,
        "count_30d": 68420,
        "error_count_30d": 410,
        "cost_month_minor": 1840,
        "last_used_at": "2026-08-26T11:58:12.000Z",
        "last_used_ip": "203.0.113.42",
        "revoked": false
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

12. API analytics by endpoint

GET /api/v1/developers/api-analytics/endpoints

{
  "data": {
    "window": "24h",
    "sort": "count",
    "rows": [
      {
        "method": "GET",
        "path_pattern": "/api/v1/messages",
        "count": 12480,
        "error_count": 96,
        "error_rate": 0.77,
        "p50_latency_ms": 84,
        "p95_latency_ms": 242,
        "p99_latency_ms": 610
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

13. API analytics overview

GET /api/v1/developers/api-analytics/overview

{
  "data": {
    "window": "24h",
    "total_requests": 18420,
    "api_key_requests": 17640,
    "requests_today": 2380,
    "error_count": 96,
    "error_rate": 0.54,
    "avg_latency_ms": 118,
    "avg_latency_all_ms": 121,
    "p50_latency_ms": 84,
    "p95_latency_ms": 242,
    "top_endpoints": [
      {
        "method": "GET",
        "path_pattern": "/api/v1/messages",
        "count": 12480,
        "error_count": 52,
        "p50_latency_ms": 84,
        "p95_latency_ms": 242
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

14. API analytics rate-limit usage

GET /api/v1/developers/api-analytics/rate-limits

{
  "data": {
    "window": "24h",
    "total_429s": 21,
    "rows": [
      {
        "method": "POST",
        "path_pattern": "/api/v1/messages",
        "count": 12
      },
      {
        "method": "GET",
        "path_pattern": "/api/v1/contacts",
        "count": 9
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

15. API analytics time series

GET /api/v1/developers/api-analytics/timeseries

{
  "data": {
    "window": "24h",
    "groupBy": "hour",
    "points": [
      {
        "ts": "2026-08-26T10:00:00.000Z",
        "count": 820,
        "error_count": 4
      },
      {
        "ts": "2026-08-26T11:00:00.000Z",
        "count": 960,
        "error_count": 7
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

16. Download the AsyncAPI contract for platform events

GET /api/v1/developers/asyncapi.json

{
  "data": {
    "filename": "orbit-asyncapi.json",
    "content_type": "application/json",
    "download_url": "https://orbit.devotel.io/downloads/orbit-asyncapi.json"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

17. List available CDP client tracking SDKs

GET /api/v1/developers/cdp-sdk/catalog

{
  "data": {
    "status": "ok"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

18. Download a CDP client SDK source for a platform

GET /api/v1/developers/cdp-sdk/source/{platform}

{
  "data": {
    "filename": "orbit-analytics.js",
    "content_type": "text/javascript",
    "download_url": "https://orbit.devotel.io/downloads/orbit-analytics.js"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

19. List connector triggers and actions

GET /api/v1/developers/connector/catalog

{
  "data": {
    "connectors": [
      {
        "name": "zapier",
        "triggers": [
          "message.received"
        ],
        "actions": [
          "messages.create"
        ]
      },
      {
        "name": "make",
        "triggers": [
          "message.received"
        ],
        "actions": [
          "messages.create"
        ]
      },
      {
        "name": "n8n",
        "triggers": [
          "message.received"
        ],
        "actions": [
          "messages.create"
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

20. Download the Make (Integromat) app blueprint

GET /api/v1/developers/connector/make

{
  "data": {
    "filename": "orbit-acme.make-app.json",
    "content_type": "application/json",
    "download_url": "https://orbit.devotel.io/downloads/integration-definition.json"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

21. Download the n8n node-pack definition

GET /api/v1/developers/connector/n8n

{
  "data": {
    "filename": "orbit-acme.n8n-nodes.json",
    "content_type": "application/json",
    "download_url": "https://orbit.devotel.io/downloads/integration-definition.json"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

22. Download the Zapier app definition

GET /api/v1/developers/connector/zapier

{
  "data": {
    "filename": "orbit-acme.zapier-app.json",
    "content_type": "application/json",
    "download_url": "https://orbit.devotel.io/downloads/integration-definition.json"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

GET /api/v1/developers/oauth/consent-preview

{
  "data": {
    "requested_scopes": [
      "messages:read",
      "contacts:read"
    ],
    "scopes": [
      {
        "scope": "messages:read",
        "label": "Read messages",
        "grantable": true
      },
      {
        "scope": "contacts:read",
        "label": "Read contacts",
        "grantable": true
      }
    ],
    "invalid_scopes": []
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

24. Download the OAuth app-registration manifest

GET /api/v1/developers/oauth/manifest

{
  "data": {
    "filename": "orbit-acme.oauth-app.json",
    "content_type": "application/json",
    "download_url": "https://orbit.devotel.io/downloads/orbit-acme.oauth-app.json"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

25. List grantable OAuth scopes

GET /api/v1/developers/oauth/scopes

{
  "data": {
    "scopes": [
      {
        "scope": "messages:read",
        "label": "Read messages",
        "role": "developer"
      },
      {
        "scope": "messages:write",
        "label": "Send messages",
        "role": "developer"
      },
      {
        "scope": "contacts:read",
        "label": "Read contacts",
        "role": "developer"
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

26. Download a Postman collection for this workspace

GET /api/v1/developers/postman-collection

{
  "data": {
    "filename": "orbit-acme.postman_collection.json",
    "content_type": "application/json",
    "download_url": "https://orbit.devotel.io/downloads/orbit-acme.postman_collection.json"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

27. Download a Postman environment for this workspace

GET /api/v1/developers/postman-environment

{
  "data": {
    "filename": "orbit-acme.postman_environment.json",
    "content_type": "application/json",
    "download_url": "https://orbit.devotel.io/downloads/orbit-acme.postman_environment.json"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

28. Dry-run one polled batch through the inbound consume core

POST /api/v1/developer/event-sources/{kind}/consume-batch

{
  "data": {
    "dispositions": [
      {
        "partition": 3,
        "offset": 1842,
        "status": "landable",
        "idempotency_key": "kafka:customer-events:3:1842"
      },
      {
        "partition": 3,
        "offset": 1843,
        "status": "duplicate",
        "idempotency_key": "kafka:customer-events:3:1843"
      }
    ],
    "commit_offsets": [
      {
        "partition": 3,
        "offset": 1844
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

29. Run a GraphQL query over CPaaS/CDP resources

POST /api/v1/developer/graphql

{
  "data": {
    "data": {
      "contacts": [
        {
          "id": "ct_01J0CONTACT",
          "displayName": "Ada Lovelace",
          "lifecycleStage": "customer",
          "tags": [
            "vip"
          ]
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

30. Register interest in the Network APIs early-access program

POST /api/v1/developer/network-apis/early-access

{
  "data": {
    "registered": true
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

31. Proxy an API request from the try-it console

POST /api/v1/developer/try-it

{
  "data": {
    "status_code": 200,
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "data": {
        "id": "msg_01J0MESSAGE"
      },
      "meta": {
        "request_id": "req_01J0PROXY"
      }
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

32. Ask-Orbit — natural-language API analytics

POST /api/v1/developers/api-analytics/ask

{
  "data": {
    "question": "How many requests did we make today?",
    "answer": "Your API received 2,380 requests today.",
    "metric": "requests",
    "window": "24h",
    "value": 2380,
    "unit": "count",
    "understood": true,
    "data": {
      "total_requests": 18420,
      "requests_today": 2380,
      "error_count": 96,
      "error_rate": 0.54,
      "avg_latency_ms": 118,
      "p50_latency_ms": 84,
      "p95_latency_ms": 242,
      "total_429s": 21,
      "top_endpoints": [
        {
          "method": "GET",
          "path_pattern": "/api/v1/messages",
          "count": 12480,
          "error_count": 52,
          "p50_latency_ms": 84,
          "p95_latency_ms": 242
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

33. Set per-API-key spend budget

PUT /api/v1/developer/budgets/{keyId}

{
  "data": {
    "key_id": "key_01J0API",
    "budget": {
      "limit_minor": 10000,
      "currency": "USD",
      "alert_thresholds": [
        50,
        80,
        100
      ]
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

34. Set per-API-key rate-limit & spend override

PUT /api/v1/developer/governance/keys/{keyId}

{
  "data": {
    "key_id": "key_01J0API",
    "override": {
      "requests_per_minute": 500,
      "monthly_request_quota": 1000000,
      "monthly_spend_limit_minor": 50000
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

35. Set org-wide API rate-limit & spend governance default

PUT /api/v1/developer/governance/org

{
  "data": {
    "status": "ok"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

36. Update the event-streaming sink config for one kind

PATCH /api/v1/developer/event-sinks/{kind}

{
  "data": {
    "kind": "kafka",
    "enabled": true,
    "events": [
      "message.created",
      "message.delivered"
    ],
    "destination": {
      "kind": "kafka",
      "topic": "orbit-events",
      "partition_key_path": "$.organization_id",
      "headers": {}
    },
    "brokers": [
      "kafka.example.com:9092"
    ],
    "sasl_mechanism": "scram-sha-256",
    "sasl_username": "orbit-ingest",
    "credentials_configured": true,
    "last_run_status": "ok",
    "last_produced_count": 128
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

37. Update the inbound event-source config for one kind

PATCH /api/v1/developer/event-sources/{kind}

{
  "data": {
    "kind": "kafka",
    "enabled": true,
    "source": {
      "kind": "kafka",
      "topic": "customer-events",
      "consumer_group": "orbit-inbound-prod",
      "type_path": "event.type"
    },
    "filter": [
      "order.created"
    ],
    "brokers": [
      "kafka.example.com:9092"
    ],
    "sasl_mechanism": "scram-sha-256",
    "sasl_username": "orbit-consumer",
    "credentials_configured": true,
    "transport_enabled": true
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Errors worth branching on

These five failures cover the webhook register + test-fire (POST /api/v1/developer/webhooks, POST /api/v1/developer/webhooks//test), which connect-checks every save. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same five classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_developea1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_developea1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "webhook_url", "value": "http://127.0.0.1:3000", "expected": "a publicly reachable https:// URL" }
    },
    "meta": {
      "request_id": "req_developeb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with a publicly reachable https:// webhook URL instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_developec3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

402 — Feature gate

  {
    "error": {
      "code": "DEVELOPER_QUOTA_EXCEEDED",
      "message": "This developer SKU has hit its quota for the current window.",
      "status": 402,
      "details": { "window_seconds": 900, "allowed_per_window": 120 }
    },
    "meta": {
      "request_id": "req_developed4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Back off for window_seconds — same-class calls keep 402ing until the window opens.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`DEVELOPER_QUOTA_EXCEEDED` (402 feature gate)	Back off for window_seconds	Branch on `error.code`. Same-class calls keep 402ing until the window opens.

Worked request and response samples

Copy the request as written, substitute your own ids, and compare the response envelope — a success in the same shape the numbered error sections spell out.

List inbound webhooks

GET /api/v1/developer/inbound-webhooks

The registered sinks that receive provider callbacks — each row announces the subscribed event kinds it accepts. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/inbound-webhooks"

{
  "data": [
    {
      "id": "wh_8f3a7b1c4d2e6095",
      "url": "https://hooks.acme.example/orbit/voice-status",
      "events": ["voice.status", "voice.dtmf"]
    }
  ],
  "meta": {
    "request_id": "req_developer",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Read one inbound webhook in full

GET /api/v1/developer/inbound-webhooks/{id}

The raw body (base64), headers, and the provider’s parsed event from the received log — the payload the webhook debugging guide walks through. A row owned by another organization is a 404, not a 403. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/inbound-webhooks/inlog_01HZQXA4E7JQ4M2E2H2DM9XE5F"

{
  "data": {
    "row": {
      "id": "inlog_01HZQXA4E7JQ4M2E2H2DM9XE5F",
      "organization_id": "org_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3",
      "channel": "voice",
      "provider": "telnyx",
      "signature_status": "valid",
      "error_msg": null,
      "received_at": "2026-09-08T11:58:31Z",
      "raw_body_size": 4096,
      "raw_body_b64": "eyJ0ZWxueXgiOiJweXRyZXh0In0=",
      "headers": {
        "content-type": "application/json",
        "telnyx-signature-ed25519": "qsBl..."
      },
      "parsed_event": {
        "data": {
          "event_type": "status",
          "payload": {
            "session_id": "call_01HZQXC2E7J8M3E2H2DM9XE5F2",
            "status": "answered"
          }
        }
      }
    }
  },
  "meta": {
    "request_id": "req_developer_inoutro",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Inspect dated API versions

GET /api/v1/developer/api-versions

The lifecycle registry: which versions exist, which is current, what version your request resolved to from the X-Api-Version pin header, and where the migration guide lives. Pin a dated version with the X-Api-Version request header. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/api-versions"

{
  "data": {
    "current_version": "2026-03-01",
    "requested_version": null,
    "resolved_version": "2026-03-01",
    "requested_version_unknown": false,
    "migration_url": "https://docs.orbit.devotel.io/api-reference/versioning",
    "pin_header": "X-Api-Version",
    "versions": [
      {
        "version": "2026-03-01",
        "status": "current",
        "released_on": "2026-03-01",
        "deprecated_on": null,
        "sunset_on": null,
        "summary": "Current stable API. Stripe-style rate-limit headers and dated version pinning.",
        "is_current": true
      }
    ]
  },
  "meta": {
    "request_id": "req_developer_vers",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

View per-API-key spend budgets

GET /api/v1/developer/budgets

Every active key with its monthly spend ceiling (minor currency units), alert thresholds, the last-notified-per-percent watermark, and live request usage. Keys with no budget return budget: null. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/budgets"

{
  "data": {
    "keys": [
      {
        "api_key_id": "key_01HZQXC2E7J8M3E2H2DM9XE5F2",
        "name": "Production runtime",
        "key_prefix": "dv_live_sk_",
        "last_four": "4KF9",
        "active": true,
        "budget": {
          "limit_minor": 500000,
          "currency": "USD",
          "period": "monthly",
          "alert_thresholds": [50, 80, 100],
          "last_notified_percent": 50
        },
        "usage": {
          "requests_this_minute": 12,
          "requests_this_month": 38401
        }
      },
      {
        "api_key_id": "key_01HZY4P8E7J8M3E2H2DM9XE3QJ",
        "name": "Sandbox test",
        "key_prefix": "dv_test_sk_",
        "last_four": "AAWZ",
        "active": true,
        "budget": null,
        "usage": {
          "requests_this_minute": 0,
          "requests_this_month": 132
        }
      }
    ],
    "keys_truncated": false,
    "defaults": {
      "alert_thresholds": [50, 80, 100],
      "max_alert_thresholds": 10
    }
  },
  "meta": {
    "request_id": "req_developer_budg",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Set a per-key spend budget

PUT /api/v1/developer/budgets/{keyId}

Caps the monthly spend on one key; clearing (limit_minor: null) removes the cap and re-arms the alert watermark. Only the fields you send change. Request

curl -X PUT "https://api.orbit.devotel.io/api/v1/developer/budgets/key_01HZQXC2E7J8M3E2H2DM9XE5F2" \
  -H "Content-Type: application/json" \
  -d '{ "limit_minor": 1000000, "currency": "USD", "alert_thresholds": [50, 80, 100] }'

{
  "data": {
    "api_key_id": "key_01HZQXC2E7J8M3E2H2DM9XE5F2",
    "budget": {
      "limit_minor": 1000000,
      "currency": "USD",
      "period": "monthly",
      "alert_thresholds": [50, 80, 100],
      "last_notified_percent": 0
    }
  },
  "meta": {
    "request_id": "req_developer_budgput",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

View the event-streaming sink config

GET /api/v1/developer/event-sinks/{kind}

The platform-event sink configuration — how the message.* / call.* taxonomy streams to your Kafka topic or batch HTTP collector. Credentials never leave storage encrypted; the response carries only a credentials_configured flag. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/event-sinks/kafka"

{
  "data": {
    "kind": "kafka",
    "enabled": true,
    "credentials_configured": true,
    "events": ["message.*"],
    "destination": {
      "kind": "kafka",
      "topic": "orbit-events",
      "partition_key_path": "data.contact.id",
      "headers": { "x-source": "orbit" }
    },
    "brokers": ["kafka.acme.example:9092"],
    "sasl_mechanism": "scram-sha-512",
    "sasl_username": "orbit-stream",
    "last_run_at": "2026-09-08T11:58:31Z",
    "last_run_status": "ok",
    "last_produced_count": 72
  },
  "meta": {
    "request_id": "req_developer_snk",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Update the event-streaming sink config

PATCH /api/v1/developer/event-sinks/{kind}

Merge the fields you send; the destination’s kind discriminator must match the path segment. last_run_* fields are worker-owned and never accepted through this route. Request

curl -X PATCH "https://api.orbit.devotel.io/api/v1/developer/event-sinks/kafka" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "events": ["message.*"], "destination": { "kind": "kafka", "topic": "orbit-events" }, "brokers": ["kafka.acme.example:9092"], "sasl_mechanism": "scram-sha-512", "sasl_username": "orbit-stream" }'

{
  "data": {
    "kind": "kafka",
    "enabled": true,
    "credentials_configured": false,
    "events": ["message.*"],
    "destination": {
      "kind": "kafka",
      "topic": "orbit-events"
    },
    "brokers": ["kafka.acme.example:9092"],
    "sasl_mechanism": "scram-sha-512",
    "sasl_username": "orbit-stream"
  },
  "meta": {
    "request_id": "req_developer_snkpatch",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Read the inbound event-source config

GET /api/v1/developer/event-sources/{kind}

The inbound mirror of the sink surface — a subscription-shaping config (topic, consumer group, type path) over your own Kafka source, ingested INTO Orbit. transport_enabled tells you whether the managed consumer is armed. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/event-sources/kafka"

{
  "data": {
    "kind": "kafka",
    "enabled": true,
    "source": {
      "kind": "kafka",
      "topic": "crm-updates",
      "consumer_group": "orbit-inbound",
      "type_path": "message.type"
    },
    "credentials_configured": true,
    "filter": ["contact.*"],
    "brokers": ["kafka.acme.example:9092"],
    "sasl_mechanism": "scram-sha-512",
    "sasl_username": "orbit-inbound",
    "transport_enabled": true
  },
  "meta": {
    "request_id": "req_developer_src",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Update the inbound event-source config

PATCH /api/v1/developer/event-sources/{kind}

Same merge-only-fields semantics as the sink surface; run the dry-run below against your patched subscription before the transport worker polls. Request

curl -X PATCH "https://api.orbit.devotel.io/api/v1/developer/event-sources/kafka" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "source": { "kind": "kafka", "topic": "crm-updates", "consumer_group": "orbit-inbound", "type_path": "message.type" }, "filter": ["contact.*"] }'

{
  "data": {
    "kind": "kafka",
    "enabled": true,
    "source": {
      "kind": "kafka",
      "topic": "crm-updates",
      "consumer_group": "orbit-inbound",
      "type_path": "message.type"
    },
    "filter": ["contact.*"],
    "credentials_configured": false,
    "transport_enabled": true
  },
  "meta": {
    "request_id": "req_developer_srcpatch",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Dry-run one polled batch through the inbound consume core

POST /api/v1/developer/event-sources/{kind}/consume-batch

Pipes one batch of raw Kafka messages through the deterministic consume engine and returns per-message disposition (landable / duplicate / filtered / dead_letter) plus per-partition commit offsets. Side-effect-free: no persist, no broker connection. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/developer/event-sources/kafka/consume-batch" \
  -H "Content-Type: application/json" \
  -d '{ "topic": "crm-updates", "filter": ["contact.*"], "messages": [{ "partition": 0, "offset": 42, "value": "{\"message\":{\"type\":\"contact.updated\",\"id\":\"ctct_01HZQXC2\"}}" }] }'

{
  "data": {
    "kind": "kafka",
    "topic": "crm-updates",
    "received": 1,
    "landable": 1,
    "duplicate": 0,
    "filtered": 0,
    "dead_letter": 0,
    "commit_offsets": { "0": 42 },
    "results": [
      {
        "partition": 0,
        "offset": 42,
        "disposition": "landable",
        "type": "contact.updated"
      }
    ],
    "persisted": false,
    "transport_enabled": true
  },
  "meta": {
    "request_id": "req_developer_dryrun",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

View org-wide rate-limit & quota governance

GET /api/v1/developer/governance

The governance console: the org default, every key’s effective limits (org default as overridden), and live usage with monthly headroom + alert flags. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/governance"

{
  "data": {
    "org_default": {
      "requests_per_minute": 600,
      "monthly_request_quota": 400000,
      "monthly_spend_limit_minor": null
    },
    "alert_threshold_percent": 80,
    "spend_alert_thresholds": [50, 80, 100],
    "bounds": {
      "max_requests_per_minute": 60000,
      "max_monthly_request_quota": 1000000000,
      "max_monthly_spend_limit_minor": 1000000000,
      "max_spend_alert_thresholds": 10
    },
    "keys": [
      {
        "api_key_id": "key_01HZQXC2E7J8M3E2H2DM9XE5F2",
        "name": "Production runtime",
        "key_prefix": "dv_live_sk_",
        "last_four": "4KF9",
        "active": true,
        "effective_limits": {
          "requests_per_minute": 600,
          "monthly_request_quota": 400000,
          "monthly_spend_limit_minor": null
        },
        "override": null,
        "usage": { "requests_this_minute": 12, "requests_this_month": 38401 },
        "monthly_quota": {
          "limit": 400000,
          "used": 38401,
          "remaining": 361599,
          "usage_percent": 9.6,
          "over_quota": false
        },
        "monthly_spend": null,
        "alerting": false
      }
    ],
    "keys_truncated": false
  },
  "meta": {
    "request_id": "req_developer_gov",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Set the org-wide governance default

PUT /api/v1/developer/governance/org

Sets the org-wide defaults applied to every key without an override. Send null on a field to clear it; only the fields you send change. Request

curl -X PUT "https://api.orbit.devotel.io/api/v1/developer/governance/org" \
  -H "Content-Type: application/json" \
  -d '{ "requests_per_minute": 600, "monthly_request_quota": 400000, "alert_threshold_percent": 80, "spend_alert_thresholds": [50, 80, 100] }'

{
  "data": {
    "org_default": {
      "requests_per_minute": 600,
      "monthly_request_quota": 400000,
      "monthly_spend_limit_minor": null
    },
    "alert_threshold_percent": 80,
    "spend_alert_thresholds": [50, 80, 100]
  },
  "meta": {
    "request_id": "req_developer_govorg",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Set a per-API-key governance override

PUT /api/v1/developer/governance/keys/{keyId}

Tightens (or raises within platform bounds) a key’s limits over the org default. All-null clears the override. Request

curl -X PUT "https://api.orbit.devotel.io/api/v1/developer/governance/keys/key_01HZQXC2E7J8M3E2H2DM9XE5F2" \
  -H "Content-Type: application/json" \
  -d '{ "requests_per_minute": 100, "monthly_request_quota": 50000 }'

{
  "data": {
    "api_key_id": "key_01HZQXC2E7J8M3E2H2DM9XE5F2",
    "override": {
      "requests_per_minute": 100,
      "monthly_request_quota": 50000,
      "monthly_spend_limit_minor": null
    },
    "effective_limits": {
      "requests_per_minute": 100,
      "monthly_request_quota": 50000,
      "monthly_spend_limit_minor": null
    }
  },
  "meta": {
    "request_id": "req_developer_govkey",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

List official SDK libraries

GET /api/v1/developer/sdks

The SDK coordinate machine-readable catalog — each entry carries a published flag, the registry install command, and docs_url / source_url only where they resolve. Every pre-launch coordinate comes back published: false. This is the programmatic surface the SDK catalog guide and Node.js SDK page point back to. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/sdks"

{
  "data": {
    "sdks": [
      {
        "language": "node",
        "name": "Node.js / TypeScript",
        "package_name": "@devotel-orbit/node",
        "version": "0.3.1",
        "published": true,
        "install_command": "npm install @devotel-orbit/node",
        "registry_url": "https://www.npmjs.com/package/@devotel-orbit/node",
        "docs_url": "https://docs.orbit.devotel.io/sdks/node",
        "source_url": "https://github.com/devotel/orbit-node"
      },
      {
        "language": "python",
        "name": "Python",
        "package_name": "devotel-orbit-sdk",
        "version": "0.1.0",
        "published": true,
        "install_command": "pip install devotel-orbit-sdk",
        "registry_url": "https://pypi.org/project/devotel-orbit-sdk/",
        "source_url": "https://github.com/Devotel/orbit-python"
      },
      {
        "language": "go",
        "name": "Go",
        "package_name": "github.com/devotel/orbit-go",
        "version": "0.1.0",
        "published": false,
        "install_command": "go get github.com/devotel/orbit-go",
        "registry_url": "https://pkg.go.dev/github.com/devotel/orbit-go"
      }
    ],
    "api_base_url": "https://api.orbit.devotel.io/api/v1",
    "docs_url": "https://docs.orbit.devotel.io"
  },
  "meta": {
    "request_id": "req_developer_sdkcat",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Get API usage statistics for the current tenant

GET /api/v1/developer/usage-stats

Per-channel messaging totals and a daily series over the chosen window, scoped to terminal outbound statuses (delivered + failed) so the error rate is computed on the same denominator the dashboard does. The query uses the tenant’s own message store. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/usage-stats?period=24h"

{
  "data": {
    "period": "24h",
    "summary": {
      "total_messages": 13301,
      "total_outbound": 13301,
      "total_inbound": 2218,
      "total_delivered": 13157,
      "total_failed": 144,
      "total_cost": "1034.1200",
      "active_channels": 3,
      "error_rate_percent": "1.08"
    },
    "by_channel": [
      {
        "channel": "sms",
        "total_messages": 12290,
        "outbound": 12290,
        "inbound": 2218,
        "delivered": 12180,
        "failed": 110,
        "total_cost": "983.2000"
      },
      {
        "channel": "whatsapp",
        "total_messages": 1011,
        "outbound": 1011,
        "inbound": 0,
        "delivered": 977,
        "failed": 34,
        "total_cost": "50.9200"
      }
    ],
    "daily": [
      { "date": "2026-09-07", "messages": 6610, "errors": 169 },
      { "date": "2026-09-08", "messages": 6691, "errors": 175 }
    ]
  },
  "meta": {
    "request_id": "req_developer_usage",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

API analytics overview

GET /api/v1/developers/api-analytics/overview

The developer hub’s headline figures: all-traffic volume, api-key-scoped traffic, success/error split, and percentiles. Quality ratios (error_rate, p50_latency_ms, p95_latency_ms) are scoped to genuine api-key traffic and are null (not 0) when the key-scoped scope has no rows in the window — render an explicit unavailable placeholder, as they do on the dashboard. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/api-analytics/overview?window=24h"

{
  "data": {
    "window": "24h",
    "total_requests": 13301,
    "api_key_requests": 12840,
    "requests_today": 12840,
    "error_count": 144,
    "error_rate": 1.08,
    "avg_latency_ms": 214,
    "avg_latency_all_ms": 187,
    "p50_latency_ms": 41,
    "p95_latency_ms": 493,
    "top_endpoints": [
      {
        "method": "POST",
        "path_pattern": "/api/v1/messages/sms",
        "count": 12840,
        "error_count": 144,
        "p50_latency_ms": 41,
        "p95_latency_ms": 493
      }
    ]
  },
  "meta": {
    "request_id": "req_developer_ov",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

API analytics by endpoint

GET /api/v1/developers/api-analytics/endpoints

Per-endpoint breakdown — request count, error rate, and latency percentiles for every method+path driven by API keys. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/api-analytics/endpoints?window=24h&sort=count"

{
  "data": {
    "window": "24h",
    "sort": "count",
    "rows": [
      {
        "method": "POST",
        "path_pattern": "/api/v1/messages/sms",
        "count": 12840,
        "error_count": 144,
        "error_rate": 1.12,
        "p50_latency_ms": 41,
        "p95_latency_ms": 493,
        "p99_latency_ms": 912
      },
      {
        "method": "GET",
        "path_pattern": "/api/v1/contacts",
        "count": 461,
        "error_count": 0,
        "error_rate": 0,
        "p50_latency_ms": 12,
        "p95_latency_ms": 40,
        "p99_latency_ms": 88
      }
    ]
  },
  "meta": {
    "request_id": "req_developer_endp",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

API analytics time series

GET /api/v1/developers/api-analytics/timeseries

A gap-filled series the dashboard charts over: bucket boundaries, request volume, and error count for plotting. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/api-analytics/timeseries?window=24h"

{
  "data": {
    "window": "24h",
    "groupBy": "hour",
    "points": [
      { "ts": "2026-09-08T00:00:00Z", "count": 482, "error_count": 6 },
      { "ts": "2026-09-08T01:00:00Z", "count": 501, "error_count": 4 },
      { "ts": "2026-09-08T02:00:00Z", "count": 0, "error_count": 0 }
    ]
  },
  "meta": {
    "request_id": "req_developer_ts",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

API analytics rate-limit usage

GET /api/v1/developers/api-analytics/rate-limits

How close the tenant is running to configured per-bucket limits — the same guard the governance console writes feed. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/api-analytics/rate-limits?window=24h"

{
  "data": {
    "window": "24h",
    "total_429s": 144,
    "rows": [
      {
        "method": "POST",
        "path_pattern": "/api/v1/messages/sms",
        "count": 140
      },
      {
        "method": "GET",
        "path_pattern": "/api/v1/contacts",
        "count": 4
      }
    ]
  },
  "meta": {
    "request_id": "req_developer_rl",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

API analytics by API key

GET /api/v1/developers/api-analytics/by-key

Per-key attribution: rolling counts joined to the key’s human-readable name, last-used-at, and last-used-ip — with total_keys revealing when the view is truncated. Sentinel ids mark unattributed (Clerk session) or deleted keys. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/api-analytics/by-key?sort=count_30d"

{
  "data": {
    "window": "30d",
    "sort": "count_30d",
    "total_keys": 3,
    "rows": [
      {
        "api_key_id": "key_01HZQXC2E7J8M3E2H2DM9XE5F2",
        "name": "Production runtime",
        "key_prefix": "dv_live_sk_",
        "last_four_chars": "4KF9",
        "count_today": 482,
        "count_7d": 3311,
        "count_30d": 12840,
        "error_count_30d": 144,
        "cost_month_minor": 103412,
        "last_used_at": "2026-09-08T11:58:31Z",
        "last_used_ip": "34.102.21.14",
        "revoked": false
      },
      {
        "api_key_id": "__none__",
        "name": "Dashboard / session",
        "key_prefix": null,
        "last_four_chars": null,
        "count_today": 92,
        "count_7d": 611,
        "count_30d": 2043,
        "error_count_30d": 0,
        "cost_month_minor": null,
        "last_used_at": "2026-09-08T11:40:02Z",
        "last_used_ip": "73.158.44.10",
        "revoked": false
      }
    ]
  },
  "meta": {
    "request_id": "req_developer_bk",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Ask-Orbit — natural-language API analytics

POST /api/v1/developers/api-analytics/ask

A plain-English question over your own telemetry, parsed deterministically into a metric + window — no LLM round-trip. The response carries the one-line answer, the resolved metric, the telemetry snapshot, and understood: false when the question fell back to the default request-volume metric. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/developers/api-analytics/ask" \
  -H "Content-Type: application/json" \
  -d '{ "question": "how many requests today?" }'

{
  "data": {
    "question": "how many requests today?",
    "answer": "Your API has received 12,840 requests since midnight.",
    "metric": "requests_today",
    "window": "24h",
    "value": 12840,
    "unit": "count",
    "understood": true,
    "data": {
      "total_requests": 12840,
      "requests_today": 12840,
      "error_count": 144,
      "error_rate": 1.08,
      "avg_latency_ms": 214,
      "p50_latency_ms": 41,
      "p95_latency_ms": 493,
      "total_429s": 144,
      "top_endpoints": []
    }
  },
  "meta": {
    "request_id": "req_developer_ask",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Run a GraphQL query over CPaaS/CDP resources

POST /api/v1/developer/graphql

A read-only shaped-round-trip surface over contacts, conversations, messages, and segments. Returns the standard GraphQL { data, errors } envelope (not the REST envelope) — a well-formed request whose query fails to parse still 200s with an errors array. The SDL below is served at GET /developer/graphql/schema. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/developer/graphql" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ contact(id: \"ctct_01HZQXC2E7J8M3E2H2DM9XE5F2\") { id displayName phone conversations { id channel status } } }" }'

{
  "data": {
    "contact": {
      "id": "ctct_01HZQXC2E7J8M3E2H2DM9XE5F2",
      "displayName": "Ada Lovelace",
      "phone": "+14155551234",
      "conversations": [
        {
          "id": "conv_01HZY4P8E7J8M3E2H2DM9XE3QJ",
          "channel": "sms",
          "status": "open"
        }
      ]
    }
  }
}

Download the GraphQL schema (SDL)

GET /api/v1/developer/graphql/schema

The SDL document the query surface validates against. Content-Type: text/plain so a browser / codegen tool reads it directly. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developer/graphql/schema"

scalar DateTime

type Query {
  contact(id: String): Contact
  contacts(limit: Int = 25, offset: Int = 0, lifecycleStage: String): [Contact!]!
  conversation(id: String): Conversation
  conversations(limit: Int = 25, offset: Int = 0, status: String): [Conversation!]!
  segments(limit: Int = 25, offset: Int = 0): [Segment!]!
}

type Contact {
  id: String!
  externalId: String
  phone: String
  email: String
  firstName: String
  lastName: String
  displayName: String

Download the AsyncAPI contract for platform events

GET /api/v1/developers/asyncapi.json

AsyncAPI 2.6.0 document for the platform event taxonomy — one JSON-Schema envelope per event type, declarable download alongside OpenAPI / Postman. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/asyncapi.json"

{
  "asyncapi": "2.6.0",
  "info": {
    "title": "Devotel Orbit Platform Events",
    "version": "2026-03-01"
  },
  "channels": {
    "message.delivered": {},
    "message.received": {},
    "call.started": {}
  },
  "components": {
    "schemas": {
      "PlatformEventEnvelope": {}
    }
  }
}

List available CDP client tracking SDKs

GET /api/v1/developers/cdp-sdk/catalog

The dashboard picker surface — which client SDK artifacts the next endpoint downloads per platform, with the Segment-compatible method set each ships. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/cdp-sdk/catalog"

{
  "data": {
    "platforms": [
      {
        "platform": "web",
        "filename": "orbit-analytics.js",
        "language": "javascript",
        "methods": ["identify", "track", "page"]
      },
      {
        "platform": "ios",
        "filename": "OrbitAnalytics.swift",
        "language": "swift",
        "methods": ["identify", "track"]
      },
      {
        "platform": "android",
        "filename": "OrbitAnalytics.kt",
        "language": "kotlin",
        "methods": ["identify", "track"]
      }
    ]
  },
  "meta": {
    "request_id": "req_developer_cdpcat",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Download a CDP client SDK source for a platform

GET /api/v1/developers/cdp-sdk/source/{platform}

The drop-in tracking SDK source for web | ios | android, pre-wired to this tenant’s public ingest host — sent as a file attachment. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/cdp-sdk/source/web" -O

// Orbit Analytics — generated for Acme Corp (public ingest host pre-wired)
const orbitIngest = 'https://sdk.orbit.devotel.io';
function identify(userId, traits) { /* ... */ }
function track(event, properties) { /* ... */ }
function page(name, properties) { /* ... */ }

List connector triggers and actions

GET /api/v1/developers/connector/catalog

The “what can I automate?” preview — every trigger (subscribed webhook event) and action (routed REST endpoint) the Zapier / Make / n8n blueprints below expose. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/connector/catalog"

{
  "data": {
    "authHeader": "X-API-Key",
    "triggers": [
      {
        "key": "inbound_message",
        "label": "New Inbound Message",
        "event": "message.received"
      }
    ],
    "actions": [
      {
        "key": "send_sms",
        "label": "Send SMS",
        "path": "/messages/sms"
      }
    ]
  },
  "meta": {
    "request_id": "req_developer_conn",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Download the Zapier app definition

GET /api/v1/developers/connector/zapier

A Zapier Platform app definition pre-wired to this tenant’s base URL — sent as an attachment. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/connector/zapier" -O

{
  "app": "orbit",
  "version": "1.0.0",
  "authentication": {
    "type": "custom",
    "fields": [{ "key": "apiKey", "label": "API Key", "required": true }]
  },
  "triggers": {
    "inbound_message": {
      "key": "inbound_message",
      "noun": "Message",
      "display": { "label": "New Inbound Message" },
      "operation": { "type": "hook" }
    }
  }
}

Download the Make blueprint

GET /api/v1/developers/connector/make

A Make (Integromat) custom-app blueprint pre-wired to this tenant’s base URL — sent as an attachment. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/connector/make" -O

{
  "name": "orbit-acme-corp",
  "label": "Orbit (Acme Corp)",
  "theme": "#0F62FE",
  "connection": {
    "parameters": [{ "id": "apiKey", "type": "string", "label": "API Key" }],
    "communication": { "base": "https://api.orbit.devotel.io" }
  },
  "modules": []
}

Download the n8n node-pack definition

GET /api/v1/developers/connector/n8n

The n8n-nodes-orbit community node-pack definition, pre-wired to this tenant’s base URL — sent as an attachment. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/connector/n8n" -O

{
  "packageName": "n8n-nodes-orbit",
  "displayName": "Orbit",
  "description": "n8n nodes for Devotel Orbit",
  "credentials": [
    {
      "name": "orbitApi",
      "displayName": "Orbit API"
    }
  ]
}

List grantable OAuth scopes

GET /api/v1/developers/oauth/scopes

The closed set of scopes a marketplace app may request — the same taxonomy the API-key middleware enforces; admin, the * wildcard, and billing are never grantable. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/oauth/scopes"

{
  "data": {
    "resources": ["Messages", "Contacts"],
    "scopes": [
      {
        "scope": "messages:read",
        "resource": "messages",
        "access": "read",
        "label": "Read messages",
        "consentCopy": "Read your SMS, MMS, WhatsApp and email message history.",
        "resolvesToScope": "viewer",
        "sensitive": false
      },
      {
        "scope": "messages:write",
        "resource": "messages",
        "access": "write",
        "label": "Write messages",
        "consentCopy": "Send SMS, MMS, WhatsApp and email messages on your behalf.",
        "resolvesToScope": "developer",
        "sensitive": false
      },
      {
        "scope": "contacts:read",
        "resource": "contacts",
        "access": "read",
        "label": "Read contacts",
        "consentCopy": "Read your contacts and their attributes.",
        "resolvesToScope": "viewer",
        "sensitive": false
      }
    ]
  },
  "meta": {
    "request_id": "req_developer_scopes",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

GET /api/v1/developers/oauth/consent-preview

Renders the install/consent rows for a space-delimited scope request and flags any scopes outside the grantable catalog. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/oauth/consent-preview?scope=messages:read%20contacts:read"

{
  "data": {
    "requested": ["messages:read", "contacts:read"],
    "granted": ["messages:read", "contacts:read"],
    "rejected": [],
    "consent": [
      {
        "scope": "messages:read",
        "label": "Read messages",
        "consent": "Read your SMS, MMS, WhatsApp and email message history.",
        "sensitive": false
      },
      {
        "scope": "contacts:read",
        "label": "Read contacts",
        "consent": "Read your contacts and their attributes.",
        "sensitive": false
      }
    ]
  },
  "meta": {
    "request_id": "req_developer_cons",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Download the OAuth app-registration manifest

GET /api/v1/developers/oauth/manifest

The deterministic RFC 7591-shaped client-registration manifest — pre-wired to this tenant’s API host, with the authorization-code + PKCE flow metadata and the scope catalog. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/oauth/manifest" -O

{
  "schema": "orbit.oauth-app/v1",
  "appVersion": "1.0.0",
  "connectionLabel": "Orbit (Acme Corp)",
  "authorization": {
    "grantTypes": ["authorization_code", "refresh_token"],
    "responseTypes": ["code"],
    "tokenEndpointAuthMethods": ["client_secret_basic", "client_secret_post"],
    "codeChallengeMethods": ["S256"],
    "authorizationEndpoint": "https://api.orbit.devotel.io/api/v1/oauth/authorize",
    "tokenEndpoint": "https://api.orbit.devotel.io/api/v1/oauth/token",
    "revocationEndpoint": "https://api.orbit.devotel.io/api/v1/oauth/revoke"
  },
  "defaultRequestedScopes": ["messages:read", "contacts:read", "conversations:read"],
  "scopeCatalog": []
}

Download a Postman collection

GET /api/v1/developers/postman-collection

A Postman v2.1 collection with every public endpoint pre-configured for your organization — sent as an attachment. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/postman-collection" -O

{
  "info": {
    "name": "Devotel Orbit — Acme Corp",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "orbit_base_url", "value": "https://api.orbit.devotel.io" },
    { "key": "orbit_api_key", "value": "" },
    { "key": "orbit_org_id", "value": "org_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" }
  ],
  "item": []
}

Download a Postman environment

GET /api/v1/developers/postman-environment

A Postman environment pre-filled with the base URL and org id — the API-key variable is secret and deliberately blank. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/postman-environment" -O

{
  "name": "Devotel Orbit — Acme Corp",
  "values": [
    { "key": "orbit_base_url", "value": "https://api.orbit.devotel.io", "type": "default", "enabled": true },
    { "key": "orbit_api_key", "value": "", "type": "secret", "enabled": true },
    { "key": "orbit_org_id", "value": "org_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", "type": "default", "enabled": true }
  ]
}

Proxy an API request from the try-it console

POST /api/v1/developer/try-it

The network proxy the dashboard’s try-it console runs through. Key-prefix validity is checked (dv_live_sk_, dv_test_sk_, dv_live_pk_, dv_test_pk_), and for GETs a body object becomes query-string parameters. The upstream response is echoed verbatim — the status_code + parsed headers + body are the live API’s. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/developer/try-it" \
  -H "Content-Type: application/json" \
  -d '{ "method": "GET", "path": "/api/v1/contacts/", "api_key": "dv_test_sk_your_key_here", "body": { "limit": "2" } }'

{
  "data": {
    "status_code": 200,
    "headers": {
      "content-type": "application/json; charset=utf-8",
      "x-request-id": "req_upstream_1"
    },
    "body": {
      "data": {
        "rows": [
          {
            "id": "ctct_01HZQXC2E7J8M3E2H2DM9XE5F2",
            "phone": "+14155551234",
            "display_name": "Ada Lovelace"
          }
        ],
        "pagination": { "next_cursor": null, "total": 1 }
      },
      "meta": { "request_id": "req_upstream_1", "timestamp": "2026-09-08T11:58:31Z" }
    }
  },
  "meta": {
    "request_id": "req_developer_tryit",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Register interest in Network APIs early access

POST /api/v1/developer/network-apis/early-access

Capture a lead for the GSMA Open Gateway / CAMARA Network APIs roadmap — number-verification, SIM-swap, KYC-match, device-location — with no provider routing pre-launch. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/developer/network-apis/early-access" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@acme.example", "company_name": "Acme Corp", "use_case": "number-verification" }'

{
  "data": { "registered": true },
  "meta": {
    "request_id": "req_developer_lead",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Error shapes worth branching on

The developer surface returns the same { error, meta } envelope across every endpoint — the fields the webhooks register + 402/429 matrix at the top uses, extended to the config writes below. The retry decision comes from error.code (and, for RATE_LIMITED, error.details.retry_after).

Status	`error.code`	Where it fires	How to respond
400	`VALIDATION_ERROR`	sink/source PATCH (bad broker format, destination.kind mismatch, SSRF-rejected http_batch URL); try-it (key prefix not recognized); consume-batch dry run (bad body shape); cdp-sdk `UNSUPPORTED_PLATFORM`	Fix, then resend intentionally. For sink/source PATCH, re-check `destination.kind` / `source.kind` matches the `{kind}` path segment and that an `http_batch` URL is https-only public.
401	`UNAUTHORIZED`	every endpoint	Surface. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.
404	`NOT_FOUND` / `ORG_NOT_FOUND`	governance/budget PUT (key exists in a different org); inbound-webhooks/ (row belongs to another org, or no trigger/subscription settings key yet); downloads (org absent)	Surface. A 404 never means “resource data is wrong” — it means the scope is off-tenant, the row is from another org, or the org simply doesn’t resolve.
422	`VALIDATION_ERROR`	network-apis early-access (Zod schema); the webhook register + test-fire envelope at top	Fix, then resend intentionally. Branch on `error.details.field`, quote the requested body in your client, and try again.
429	`RATE_LIMITED`	every endpoint, including downloads + analytics reads	Retry after the lower of the `Retry-After` header or `error.details.retry_after`, same request body.
402	`DEVELOPER_QUOTA_EXCEEDED`	governance-enforced quota	Back off for `window_seconds`. Same-class calls keep 402ing until the window opens.
500/503	`INTERNAL_ERROR` / `SERVICE_UNAVAILABLE`	usage-stats (anything except an unprovisioned tenant messages table is a 503, not fabricated zeros); network-apis early-access insert	Retry after the first failure slot is clear — a redeploy usually resolves it; otherwise call support with `meta.request_id`.

For the webhooks register + test-fire envelope ({ error, meta } and the retry matrix), see Errors worth branching on at the top of this page. The error handling guide covers the same decision table for every pillar.

​The developer surface

​Response envelopes for the generated shells

​1. List dated API versions and deprecation lifecycle

​2. View per-API-key spend budgets

​3. Get the event-streaming sink config for one kind

​4. Get the inbound event-source config for one kind

​5. View API rate-limit & quota governance

​6. Download the developer GraphQL schema (SDL)

​7. List received inbound webhooks

​8. Get an inbound webhook by id

​9. List official SDK libraries

​10. Get API usage statistics for the current tenant

​11. API analytics by API key

​12. API analytics by endpoint

​13. API analytics overview

​14. API analytics rate-limit usage

​15. API analytics time series

​16. Download the AsyncAPI contract for platform events

​17. List available CDP client tracking SDKs

​18. Download a CDP client SDK source for a platform

​19. List connector triggers and actions

​20. Download the Make (Integromat) app blueprint

​21. Download the n8n node-pack definition

​22. Download the Zapier app definition

​23. Preview the consent screen for a scope request

​24. Download the OAuth app-registration manifest

​25. List grantable OAuth scopes

​26. Download a Postman collection for this workspace

​27. Download a Postman environment for this workspace

​28. Dry-run one polled batch through the inbound consume core

​29. Run a GraphQL query over CPaaS/CDP resources

​30. Register interest in the Network APIs early-access program

​31. Proxy an API request from the try-it console

​32. Ask-Orbit — natural-language API analytics

​33. Set per-API-key spend budget

​34. Set per-API-key rate-limit & spend override

​35. Set org-wide API rate-limit & spend governance default

​36. Update the event-streaming sink config for one kind

​37. Update the inbound event-source config for one kind

​Errors worth branching on

​401 — Unauthorized

​403 — Forbidden

​422 — Schema

​429 — Rate

​402 — Feature gate

​60-second retry matrix

​Worked request and response samples

​List inbound webhooks

​Read one inbound webhook in full

​Inspect dated API versions

​View per-API-key spend budgets

​Set a per-key spend budget

​View the event-streaming sink config

​Update the event-streaming sink config

​Read the inbound event-source config

​Update the inbound event-source config

​Dry-run one polled batch through the inbound consume core

​View org-wide rate-limit & quota governance

​Set the org-wide governance default

​Set a per-API-key governance override

​List official SDK libraries

​Get API usage statistics for the current tenant

​API analytics overview

​API analytics by endpoint

​API analytics time series

​API analytics rate-limit usage

​API analytics by API key

​Ask-Orbit — natural-language API analytics

​Run a GraphQL query over CPaaS/CDP resources

​Download the GraphQL schema (SDL)

​Download the AsyncAPI contract for platform events

​List available CDP client tracking SDKs

​Download a CDP client SDK source for a platform

​List connector triggers and actions

​Download the Zapier app definition

​Download the Make blueprint

​Download the n8n node-pack definition

​List grantable OAuth scopes

​Preview the consent screen for a scope request

​Download the OAuth app-registration manifest

The developer surface

Response envelopes for the generated shells

1. List dated API versions and deprecation lifecycle

2. View per-API-key spend budgets

3. Get the event-streaming sink config for one kind

4. Get the inbound event-source config for one kind

5. View API rate-limit & quota governance

6. Download the developer GraphQL schema (SDL)

7. List received inbound webhooks

8. Get an inbound webhook by id

9. List official SDK libraries

10. Get API usage statistics for the current tenant

11. API analytics by API key

12. API analytics by endpoint

13. API analytics overview

14. API analytics rate-limit usage

15. API analytics time series

16. Download the AsyncAPI contract for platform events

17. List available CDP client tracking SDKs

18. Download a CDP client SDK source for a platform

19. List connector triggers and actions

20. Download the Make (Integromat) app blueprint

21. Download the n8n node-pack definition

22. Download the Zapier app definition

23. Preview the consent screen for a scope request

24. Download the OAuth app-registration manifest

25. List grantable OAuth scopes

26. Download a Postman collection for this workspace

27. Download a Postman environment for this workspace

28. Dry-run one polled batch through the inbound consume core

29. Run a GraphQL query over CPaaS/CDP resources

30. Register interest in the Network APIs early-access program

31. Proxy an API request from the try-it console

32. Ask-Orbit — natural-language API analytics

33. Set per-API-key spend budget

34. Set per-API-key rate-limit & spend override

35. Set org-wide API rate-limit & spend governance default

36. Update the event-streaming sink config for one kind

37. Update the inbound event-source config for one kind

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

402 — Feature gate

60-second retry matrix

Worked request and response samples

List inbound webhooks

Read one inbound webhook in full

Inspect dated API versions

View per-API-key spend budgets

Set a per-key spend budget

View the event-streaming sink config

Update the event-streaming sink config

Read the inbound event-source config

Update the inbound event-source config

Dry-run one polled batch through the inbound consume core

View org-wide rate-limit & quota governance

Set the org-wide governance default

Set a per-API-key governance override

List official SDK libraries

Get API usage statistics for the current tenant

API analytics overview

API analytics by endpoint

API analytics time series

API analytics rate-limit usage

API analytics by API key

Ask-Orbit — natural-language API analytics

Run a GraphQL query over CPaaS/CDP resources

Download the GraphQL schema (SDL)

Download the AsyncAPI contract for platform events

List available CDP client tracking SDKs

Download a CDP client SDK source for a platform

List connector triggers and actions

Download the Zapier app definition

Download the Make blueprint

Download the n8n node-pack definition

List grantable OAuth scopes

Preview the consent screen for a scope request

Download the OAuth app-registration manifest