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://orbit-api.devotel.io/api/v1/

Authentication

Include your API key in the X-API-Key header with every request:

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

See 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., [phone])
• 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:

{
  "data": {
    "message_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:

{
  "data": [
    { "message_id": "msg_001", "status": "delivered" },
    { "message_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:

curl "https://orbit-api.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:

{
  "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. [phone]"
    }
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-03-08T12:00:00Z",
    "docs_url": "https://orbit-docs.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

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

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

Service	Base Path	Description
Messages	/v1/messages	Send SMS, WhatsApp, RCS, Viber, Email
Voice	/v1/voice	Calls, recordings, SIP
Agents	/v1/agents	AI agent management
Flows	/v1/flows	Workflow automation
Numbers	/v1/numbers	Phone number management
Verify	/v1/verify	OTP verification
Webhooks	/v1/webhooks	Webhook management

SDKs

Use an official SDK for a better development experience:

• Node.js / TypeScript
• Python
• Go