> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # API Overview > Orbit REST API reference — base URL, authentication, response format, and error handling # API Overview The Orbit API is a RESTful JSON API that provides programmatic access to all Orbit services — messaging, voice, AI agents, flows, numbers, and verification. ## Base URL All API requests are made to: ``` https://api.orbit.devotel.io/api/v1/ ``` ## Authentication Include your API key in the `X-API-Key` header with every request: ```bash theme={null} curl https://api.orbit.devotel.io/api/v1/messages \ -H "X-API-Key: dv_live_sk_your_key_here" ``` See [Authentication](/authentication) for details on API key types and JWT bearer tokens. ## Request Format * All request bodies must be JSON with `Content-Type: application/json` * Phone numbers must be in E.164 format (e.g., `+14155552671`) * Timestamps are ISO 8601 in UTC (e.g., `2026-03-08T12:00:00Z`) * Pagination uses cursor-based pagination (no offset-based) ## Response Format ### Successful Response Every successful response returns a `data` object and a `meta` object: ```json theme={null} { "data": { "id": "msg_abc123", "status": "queued", "channel": "sms" }, "meta": { "request_id": "req_xyz789", "timestamp": "2026-03-08T12:00:00Z" } } ``` ### List Response (Paginated) List endpoints include cursor-based pagination in `meta`: ```json theme={null} { "data": [ { "id": "msg_001", "status": "delivered" }, { "id": "msg_002", "status": "delivered" } ], "meta": { "request_id": "req_xyz789", "timestamp": "2026-03-08T12:00:00Z", "pagination": { "cursor": "cur_abc123", "has_more": true, "total": 1542 } } } ``` Fetch the next page by passing the cursor: ```bash theme={null} curl "https://api.orbit.devotel.io/api/v1/messages?cursor=cur_abc123&limit=20" \ -H "X-API-Key: dv_live_sk_..." ``` ### Error Response Errors include a structured `error` object with a machine-readable `code`: ```json theme={null} { "error": { "code": "INVALID_PHONE_NUMBER", "message": "The 'to' field must be a valid E.164 phone number", "status": 422, "details": { "field": "to", "value": "+1234", "expected": "E.164 format e.g. +14155552671" } }, "meta": { "request_id": "req_xyz789", "timestamp": "2026-03-08T12:00:00Z", "docs_url": "https://docs.orbit.devotel.io/errors/INVALID_PHONE_NUMBER" } } ``` ## HTTP Status Codes | Status | Meaning | | ------ | ---------------------------------------------------------------------------------------------- | | `200` | Success | | `201` | Resource created | | `400` | Bad request — malformed JSON or missing fields | | `401` | Unauthorized — invalid or missing API key | | `403` | Forbidden — insufficient permissions | | `404` | Not found — resource doesn't exist | | `409` | Conflict — duplicate request or state conflict | | `422` | Unprocessable — validation failed | | `429` | Rate limited — too many requests | | `500` | Internal server error | | `503` | Service unavailable — transient dependency failure or unprovisioned secret; retry with backoff | ## Rate Limiting Rate limits are enforced per API key. Current limits are returned in response headers: | Header | Description | | ----------------------- | -------------------------------------------------------------- | | `X-RateLimit-Limit` | Maximum requests per window | | `X-RateLimit-Remaining` | Remaining requests in current window | | `X-RateLimit-Reset` | Unix timestamp when the window resets | | `X-RateLimit-Bucket` | Identifier of the rate-limit bucket (present on 429 responses) | | `RateLimit-Limit` | IETF standard equivalent of `X-RateLimit-Limit` | | `RateLimit-Remaining` | IETF standard equivalent of `X-RateLimit-Remaining` | | `RateLimit-Reset` | IETF standard equivalent of `X-RateLimit-Reset` | When rate limited, you receive a `429` response. Implement exponential backoff and respect the `X-RateLimit-Reset` header. ## Request ID Every response includes an `X-Request-Id` header and a `request_id` in the `meta` object. Include this ID when contacting support for faster debugging. ## API Endpoints The table below covers the major service groups. It is not exhaustive — the [OpenAPI spec](https://api.orbit.devotel.io/openapi.json) at `/openapi.json` is the authoritative, complete list of endpoints, parameters, and schemas. | Service | Base Path | Description | | ------------- | ----------------------- | ---------------------------------------------------------- | | Messages | `/api/v1/messages` | Send SMS, WhatsApp, RCS, Viber, Email | | Voice | `/api/v1/voice` | Calls, recordings, SIP | | Fax | `/api/v1/fax` | Send and receive fax (T.38) | | WhatsApp | `/api/v1/whatsapp` | WhatsApp Business templates, sessions, media | | RCS | `/api/v1/rcs` | RCS Business Messaging agents and rich cards | | Email | `/api/v1/email` | Transactional email, senders, deliverability, suppressions | | Agents | `/api/v1/agents` | AI agent management | | Flows | `/api/v1/flows` | Workflow automation | | Numbers | `/api/v1/numbers` | Phone number management | | Verify | `/api/v1/verify` | OTP verification | | Contacts | `/api/v1/contacts` | Contact records and custom fields | | Segments | `/api/v1/segments` | Dynamic audience segments | | CDP | `/api/v1/cdp` | Customer data platform, reverse ETL, activations | | Campaigns | `/api/v1/campaigns` | Bulk and scheduled campaign sends | | Conversations | `/api/v1/conversations` | Unified inbox threads across channels | | Surveys | `/api/v1/surveys` | Survey distribution and responses | | Video | `/api/v1/video` | Video rooms, recordings, live captions | | Analytics | `/api/v1/analytics` | Reporting, dashboards, goals | | Billing | `/api/v1/billing` | Usage, invoices, and billing data | | Integrations | `/api/v1/integrations` | Third-party connectors | | Webhooks | `/api/v1/webhooks` | Webhook management | For the complete set of service groups (including ads, channels, commerce, compliance, knowledge, notifications, SCIM, team chat, Telegram, USSD, and more), refer to the [OpenAPI spec](https://api.orbit.devotel.io/openapi.json). ## SDKs Use an official SDK for a better development experience: * [Node.js / TypeScript](/sdks/node) — server-side * [Web (browser)](/sdks/web) — client-side / embeddable widgets * Python, Go, Java, PHP, Ruby, .NET — coming soon. Until then, the REST API is fully usable from any HTTP client.