> ## 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.

# How to read a worked sample

> Turn any worked request/response sample in these docs into a real call — translate the curl block into fetch or an SDK, recognize the four response envelope shapes, and find every worked example from one index.

# How to read a worked sample

Every endpoint guide in these docs ships a worked sample — a request you can copy verbatim, and the exact response envelope the platform returns. This index shows you how to turn a sample into a running call, and where the rest of the worked examples live.

## Reading an endpoint's sample

A worked sample is a complete request: method, path, headers, and body. Nothing in it is a placeholder except your API key — so translating the curl block to your language is mechanical.

1. **Copy the request as written.** Base URL is always `https://api.orbit.devotel.io/api/v1`; substitute a Test key (`dv_test_sk_…`) for `X-API-Key` and the sample runs against the sandbox.
2. **Translate it per language.** The headers and JSON body carry over unchanged — only the HTTP client differs.

```bash cURL theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155552671", "body": "Hello from Orbit." }'
```

```typescript fetch theme={null}
const res = await fetch("https://api.orbit.devotel.io/api/v1/messages/sms", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ORBIT_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ to: "+14155552671", body: "Hello from Orbit." }),
});
const { data } = await res.json(); // same envelope the sample documents
```

The [Node SDK](/sdks/node) collapses the same call to one line — `orbit.messages.send({ channel: "sms", to, body })` — and returns the same `data` the raw response carries. Pick whichever you read faster; the envelope below is identical either way.

## The four envelope shapes

Every response the platform returns is one of four shapes. Recognize the shape at a glance and you know how to read the body:

1. **Success envelope** — `{ data, meta }`, HTTP 2xx. The resource (or a resource id) sits under `data`; `meta` carries the request correlation id:
   ```json theme={null}
   { "data": { "id": "msg_9e8d7c6b5a4f3021e5d6c7b8a1b2c3d4", "status": "queued" }, "meta": { "request_id": "req_abc123" } }
   ```
2. **Success with pagination** — the same `{ data, meta }`, with `meta.pagination` telling you how to fetch the next page:
   ```json theme={null}
   { "data": [ ... ], "meta": { "pagination": { "cursor": "cur_msg_abc123", "has_more": true, "total": 1542 } } }
   ```
3. **207 Multi-Status batch envelope** — bulk endpoints answer `207` on partial success and give you one row per recipient; branch on `status` per row, never blanket-retry the batch:
   ```json theme={null}
   { "data": { "results": [ { "recipient": "+14155552671", "status": "sent", "verification_id": "vrf_3f1c0b…" }, { "recipient": "+1234", "status": "failed", "error": { "code": "INVALID_PHONE_NUMBER", "message": "…" } } ] } }
   ```
   Canonical sample: [Bulk sends (207 and all)](/troubleshooting/verify-otp) and the [Verify API](/api-reference/verify).
4. **Error envelope** — `{ error, meta }` on any non-2xx status. Branch on the stable `error.code`, never on the human-readable `error.message`:
   ```json theme={null}
   { "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry after 4 seconds.", "status": 429, "retry_after": 4 }, "meta": { "request_id": "req_xyz789" } }
   ```
   Canonical sample: [API error handling by example](/guides/error-handling-examples).

## Where the worked examples live

Samples are spread across the docs deliberately — each sits next to the endpoint it exercises. This page is the index:

* [REST API recipes](/guides/api-recipes) — sixteen task-by-task worked samples (messaging, voice, campaigns, CDP, webhook round trips), each pairing curl with Node or Python.
* [Error handling by example](/guides/error-handling-examples) — three worked failures with the fix in code.
* [Endpoint worked samples](/api-reference/overview) — each endpoint family page carries a curated sample block ([messaging](/api-reference/endpoints/messaging), [campaigns](/api-reference/endpoints/campaigns), [voice](/api-reference/endpoints/voice), and the rest).
* [Starter examples](/guides/starter-examples) and the [Quickstart](/quickstart) — five runnable repos and the end-to-end first call, when a single request/response isn't enough.

## Pagination in one paragraph

List endpoints paginate one of two ways, and the response tells you which: most endpoints are **cursor-based** — read `meta.pagination.cursor` when `has_more` is true and pass it back as `?cursor=…`; a smaller set of dashboard-oriented families is **offset-based** — the page metadata (`items`, `total`, `limit`, `offset`) lives inside the `data` envelope instead. The shape of the response you're holding identifies the style. The full contract, with both loops in code: [Pagination](/guides/pagination).