Skip to main content

​
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. 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 owns 36 numbered, task-shaped flows — from sending and tracking a message to the pillar-level loops for voice, numbers, WhatsApp, loyalty, flows, knowledge bases, the Orby copilot, and the visual email Builder chain (save → render → send → engagement webhooks), closing with the billing-reconciliation pair (drain the CDR feed to CSV; rate reseller usage into a branded invoice with the exemption branch and a credit note) and the campaign send round trip (create → send under an idempotency key → poll through the 429 branch → reconcile the per-recipient ledger) — plus the four-channel complement 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) 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 submit sample, the Auth SAML round-trip steps, the 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 overlay is self-sufficient, but Task 1 of the cookbook 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 36 entries. Split the decision at the intent you are serving — a contract question (one endpoint) or a workflow question (several).

​
Guard: a success envelope must carry concrete fields

{ data: {} } on a success envelope is the tell the generator was built to eliminate — the empty-body placeholder that ships when an operation’s OpenAPI 2xx response carries no JSON schema. The docs pipeline claims the OpenAPI spec is the single source of shapes: apps/api/openapi.yaml is synced to apps/docs/openapi.yaml by sync-openapi.ts at predev/prebuild, so a schema gap there lands on every endpoint page the operation touches. When you open an endpoint’s overlay and the success body is { data: {} }:
  1. Check the OpenAPI spec first. The pipeline resolves a schema-less 2xx body through fallbackResponseEnvelopeData(method, path) — a GET on a resource tail (…/{id}) renders an id-bearing resource row, and the route’s own path segment names a realistic feature flag otherwise (acd-auto-answer → { acd_auto_answer_enabled: true }). Where that resolution still returns a shape-less placeholder, the empty body reached the page. Fix the spec first — sync-openapi.ts syncs apps/api/openapi.yaml into the docs tree, so the next regeneration renders a concrete body.
  2. Never author { data: {} } by hand. A curated overlay or recipe sample must carry at least one concrete field in data — or, when the endpoint returns an empty list, an explicit [] on the envelope’s data member. The four envelope shapes in How to read a worked sample are the guard: rule 1’s { data, meta } success envelope needs the resource (or a resource id) to sit under data.
  3. The resolution hooks the overlay template. The same handler that splices the hand-curated overlay into the generated MDX immediately after the page title resolves the schema-less body: where the editorial overlay samples the same status, the hand-authored body wins over the schema-inferred shell; where no overlay sample exists for that status, fallbackResponseEnvelopeData(method, path) renders the shape-appropriate body instead of the literal placeholder.
  4. Fix the spec, not the sample. Fixing the OpenAPI input stops the placeholder; curating over it hides the regression and the placeholder ships again on the next regeneration. { data: {} } is the tell the rule exists to remove.
  • How to read a worked sample — 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 — the 36-task cookbook this page triages against.
  • Messaging API — 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.
  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 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.

​
Worked samples, worked

The rules above are easier to copy than to parse. Two minimal samples — one per surface — show exactly the shape each surface expects. The envelope shapes both use are defined in How to read a worked sample; nothing below invents outside those four shapes.

​
The endpoint overlay at its smallest

One call, one success envelope, sitting next to the parameter table so the contract resolves on the page:
That is the whole overlay: a copyable request, the exact { data, meta } envelope it returns, and a stable req_<tag> request id. Ship it beside the endpoint’s parameter table, not on a second page.

​
The cookbook sample at its smallest

A recipe step pairs the same call with an escape hatch for readers off the curl/Node path. Where How to read a worked sample carries cursor and bulk loops in TypeScript and Python, a cookbook step carries one curl block and one Python block over the Python SDK’s raw-request method:
cURL
```python Python — the SDK’s escape hatch, no requests needed from orbit_sdk import OrbitClient client = OrbitClient.from_api_key(“dv_test_sk_YOUR_KEY”) row = client.request(“GET”, “/messages/msg_e4d5c6b7a8b9c0d1e2f3a4b5c6d7e8f9”)

​
row[“data”][“status”] advances queued → sending → delivered