Skip to main content

​
API playground

The API playground is an interactive request builder inside the dashboard — a Stripe-style try-it console that works through the whole public API surface without leaving the browser. Pick an endpoint from the catalog, fill the fields, read the generated code in your language, hit Send, and inspect the response next to the snippet. It lives at Developer → API playground (/[locale]/developer/playground in the dashboard).

​
When to use it

Use the playground when you want to:
  • shape a real request against your own tenant before writing code — confirm the field names, the response shape, and the exact curl you will paste;
  • smoke-test sandbox behavior (magic-number scenarios, validation errors, rate-limit headers) without wiring a script;
  • hand a colleague a working snippet — the code panel renders the same request in six languages.
Reach for the full API reference or the SDK docs when you already know the endpoint and need every field; the playground catalog covers the roughly two dozen verbs that make up the first week of an integration.

​
Prerequisites

  • Role: the page is gated to owner, admin, and developer roles.
  • API key: at least one active key matching the mode you want to run in — dv_test_… for sandbox, dv_live_… for live. The playground picks the first active key on your account that matches the current mode. With no matching key the Send button stays disabled; create one under Settings → API keys.
  • A sender for write endpoints: POST /messages needs a number or sender in your tenant to send from; sandbox does not relax sender validation, only delivery.

​
The three panes

The playground lays out in three panes: The endpoint catalog is curated rather than generated from the full OpenAPI document — roughly the two dozen verbs that cover the first week of an integration, with field copy written for onboarding (“Recipient phone number in E.164”) rather than auto-extracted from the schema.

​
Worked example: send an SMS

The fastest way to learn the page is one full run of the best-exercised write endpoint.
  1. Open sandbox mode. Flip the Sandbox/Live toggle in the builder header to Sandbox. The status line at the bottom of the form should name a dv_test_… key; if it says No matching API key for this mode, create a test key under Settings → API keys first.
  2. Pick the endpoint. In the left pane, under Messages, choose Send SMS (POST /messages).
  3. Fill the form:
    • channel — leave it on sms (the dropdown covers sms, mms, whatsapp, rcs, viber, email).
    • to — +15551234567. The help text under the field flags the sandbox behavior: change the trailing digit to 9 and the simulated delivery flips to a failed DLR.
    • from — +15550100, the sandbox sender.
    • body — Hi from Orbit!
  4. Read the generated code. Switch the Code preview to your language. The cURL tab shows:
    The key is masked to prefix + last four — the playground never prints a usable credential into the snippet or the history list.
  5. Hit Send. The Response card appears with a green status badge, a duration in milliseconds, and a body carrying the new message id and its state. Below it, the rate-limit callout reads something like 95/100 remaining · resets in 42s.
  6. Force a simulated failure. Change to to end in 9 and send again — the body now reports the message in a failed state, which is the shape your DLR handling must parse. Sandbox magic numbers lists every trailing-digit scenario.
  7. Wrap up in history. Both runs are now in Recent requests with their status and duration. They stay in this browser only.
If the same fields return a 422 in live mode but succeed in sandbox, the response body names the field that live validation rejected — the playground surfaces that detail verbatim.

​
Sandbox vs live

The toggle in the builder header mirrors the dashboard-wide sandbox store: flip it to sandbox anywhere and the page follows. In sandbox mode the playground routes through your dv_test_… key, so nothing is delivered to a real carrier and nothing is charged. In live mode it uses your dv_live_… key and the request is real. The mode-vs-key pairing is enforced server-side: a request cannot sneak a live call through on a test key or vice versa — a mismatched pairing is refused before it reaches the endpoint. What you send in sandbox mode is fully deterministic — the delivery outcome is chosen by the trailing digit of the recipient you send to (see Sandbox magic numbers). The playground is the fastest way to try one of those scenarios without writing a script.

​
Use the generated code in your codebase

The snippet panel is the point of the playground: it renders the request the way you would write it, on the base URL you actually send to.
  • cURL — an X-API-Key header and the JSON body inline; paste it into a terminal.
  • Node, Python, Go, Ruby, PHP — the same request through the official SDK for that language, reading the key from ORBIT_API_KEY (live) or ORBIT_SANDBOX_KEY (sandbox).
The key in the preview is masked (prefix + last four) — swap in the full key from Settings → API keys before you paste the snippet into your codebase. The same masked form is what the request-history list records, so a snippet you copied out of history never carries a usable credential.

​
Failure modes and errors

​
Request history

Every run is appended to a per-user history that lives in your browser’s localStorage only — the last 50 requests, with method, path, mode, status, and duration. It never reaches a server; clearing browser data or switching browsers starts fresh, and the Clear button empties it. The panel shows the latest dozen; older entries within the 50 cap fall off the view as new runs land. For the durable, workspace-wide view of API traffic — full request/response payloads retained for a year — use the Request Logs console. The playground history is the scratchpad; Request Logs is the record.

​
See also