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

# Where a worked sample belongs: endpoint overlay vs recipe cookbook

> How the docs split worked samples between the per-endpoint overlay blocks and the REST API recipe cookbook, and the rules of thumb for choosing between them.

# Where a worked sample belongs

These docs publish worked request and response samples through two different surfaces: the editorial overlay attached to each endpoint reference page, and the task-oriented cookbook at [REST API recipes](/guides/api-recipes). They are not redundant — they answer different questions. This page explains the split so the next sample lands on the right surface, and readers know which surface to reach for.

## What the recipe page covers

[REST API recipes](/guides/api-recipes) owns 25 numbered, task-shaped flows — from sending and tracking a message to the pillar-level loops for voice, numbers, WhatsApp, loyalty, flows, knowledge bases, and the Orby copilot — plus the thin A–D pack covering Telegram, USSD, MMS, and Voice. Each flow pairs curl with an SDK tab and walks a full loop: request, success envelope, polling or webhook, error branch.

Everything outside those flows is deliberately not there. The cookbook assumes no endpoint-ordering knowledge a single endpoint would impose, which is why account, auth, SAML headers, and feedback categories live in overlays instead of recipes. Readers looking for those use the per-endpoint pages; only flows that span several endpoints graduate to the cookbook.

## Endpoint-level overlay vs recipe-level cookbook

Every endpoint reference page (the auto-generated pages under [API reference](/api-reference/endpoints)) carries an editorial overlay — the `Worked request and response samples` block — sewn into the page at regeneration time. Use this decision rule when you add a sample:

**Pick the endpoint overlay when the sample needs exactly one endpoint.** One call, one success envelope, one error set. The overlay sits next to the parameter table so a reader can resolve the contract without leaving the page. Examples in the shipped tree: the [Feedback](/api-reference/endpoints/feedback) submit sample, the [Auth](/api-reference/endpoints/auth) SAML round-trip steps, the [Account](/api-reference/endpoints/account) error classes.

**Pick the recipe cookbook when the value is the chain.** The sample steps across endpoints (send → poll → webhook → error path) or stitches an SDK tab for several languages. Recipes are numbered so support can cite them; the per-endpoint pages link back to the recipe for the canonical loop. Example: the [Messaging](/api-reference/endpoints/messaging) overlay is self-sufficient, but [Task 1 of the cookbook](/guides/api-recipes#1-send-a-message-poll-status-receive-the-webhook) is the canonical send → poll → webhook chain.

When both fit, prefer the overlay: shorter samples age better, and the cookbook's task index stays readable at 25 entries. Split the decision at the intent you are serving — a contract question (one endpoint) or a workflow question (several).

## Cross-links to lean on

* [How to read a worked sample](/guides/using-orbit-samples) — the four response envelope shapes and how to translate any sample into a runnable call. Every overlay points readers here instead of re-describing envelopes.
* [REST API recipes](/guides/api-recipes) — the 25-task cookbook this page triages against.
* [Messaging API](/api-reference/endpoints/messaging) — the canonical worked-sample shape to copy: a **send → poll → receive the delivery webhook** DLR chain with per-step envelopes. New overlays should imitate that sequencing whenever the endpoint has a delivery or status lifecycle.

## Contributing rules for new samples

Consistency beats style preference. When you add or update a worked sample:

1. **Match the platform envelope exactly.** Success samples carry `{ data, meta }`; error samples carry `{ error, meta }` with a stable `error.code`. Never invent a shape outside the four envelopes in [How to read a worked sample](/guides/using-orbit-samples).
2. **Use sandbox keys in every sample.** `dv_test_sk_YOUR_KEY` (cURL) or `process.env.ORBIT_API_KEY` (code tabs) — never a live-prefix key, and never a concrete-looking key a reader might copy verbatim.
3. **Keep request ids stable and tagged.** Render `meta.request_id` as `req_<tag>` (for example `req_sms_send`, `req_msg_get`) so two samples on the same page never share an id and a reader can tell ids from data.
4. **Copy a shipped shape before inventing one.** The messaging DLR chain above is the reference; for pure failures-only pages the [Account overlay](/api-reference/endpoints/account) matrix is the reference.

Docs readers run samples against the sandbox first; a sample that drifts from these rules costs them a debugging session. Keep the receipt small and the envelope exact.