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

# API playground: build and run requests in the dashboard

> Pick an endpoint, fill the form, read the generated curl/SDK snippet, and send it — the dashboard's interactive request builder, with a sandbox/live toggle and a per-user request history.

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

The page is gated to `owner`, `admin`, and `developer` roles.

## The three panes

The playground lays out in three panes:

| Pane                         | What it holds                                                                                                                                                                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Endpoints (left)**         | A hand-curated catalog of the most-exercised public endpoints — Messages, Voice, Contacts, Campaigns, Templates, Numbers, Webhooks, and Analytics groups, each with the HTTP method color-coded.                                              |
| **Request builder (centre)** | A form rendered from the endpoint's schema — required fields flagged, `json` fields as a textarea, enum fields as a dropdown. The global **Sandbox/Live toggle** sits in the builder header and stays in sync with the rest of the dashboard. |
| **Code + result (right)**    | The generated snippet in cURL, Node, Python, Go, Ruby, or PHP (tab between them), the response when you send, and your recent-request history.                                                                                                |

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.

## Run a request

1. **Pick an endpoint** in the left pane — for example *Messages → Send SMS* (`POST /messages`).
2. **Fill the form.** Required fields carry a `required` badge; fields with a fixed choice render as a dropdown (channel, direction); free-form JSON fields render as a text area. Number fields are sent as numbers, `json` fields are parsed before sending.
3. **Check the key.** The status line shows which API key the request will run under — the playground picks the first active key on your account that matches the current mode (`dv_test_…` in sandbox, `dv_live_…` in live). No matching key means the Send button stays disabled until you create one under **Settings → API keys**.
4. **Read the generated code.** The right pane renders the request as cURL and as a snippet for each official SDK language; it updates live as you type in the form.
5. **Hit Send.** The response panel shows the status code (color-coded: 2xx green, 4xx amber, 5xx red), the duration in milliseconds, the response body, and the response headers.

Rate-limit headers are promoted to a first-class callout: `X-RateLimit-Limit` / `-Remaining` / `-Reset` (plus `Retry-After` when the bucket is exhausted) show as a line — `remaining/limit remaining · resets in Ns` — that turns amber under 20% remaining and red when exhausted, instead of hiding in the headers dump.

Errors come back through the same error-envelope masking the rest of the platform uses: genuine validation detail (`422` with the bad field named) surfaces verbatim, while opaque internals are mapped to a friendly fallback.

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

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

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](/sandbox/magic-numbers)). The playground is the fastest way to try one of those scenarios without writing a script.

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

For the durable, workspace-wide view of API traffic — full request/response payloads retained for a year — use the [Request Logs console](/guides/api-request-logs-console). The playground history is the scratchpad; Request Logs is the record.

## See also

* [Request Logs console](/guides/api-request-logs-console) — inspect the full payloads of the requests you made here
* [Sandbox magic numbers](/sandbox/magic-numbers) — deterministic delivery outcomes keyed by trailing digit
* [Developer Portal guide](/guides/developer-portal) — the try-it endpoint, usage stats, key governance, and webhook debugging
* [API Integration quickstart](/guides/api-integration) — take the request you built here into your codebase
* [Authentication](/authentication) — key formats, roles, and rotation