---
title: Playground
description: An interactive request console readers can send real API calls from.
icon: api
---

# Playground

The Playground component embeds a working API console in a page. Readers pick an
environment, supply a key, edit the request, and send it — the response comes back
with its status and timing.

Requests go **directly from the reader's browser to your API**. Nothing is proxied
through Syntext, and the key the reader types is never sent anywhere else. Your API
must therefore allow CORS from your doc site's origin, or the browser will block
the call before it leaves.

## Basic usage

```mdx
<Playground
  method="POST"
  path="/v1/transfers"
  servers='[{"name":"Sandbox","url":"https://sandbox.api.example.com"},
            {"name":"Production","url":"https://api.example.com"}]'
  key-label="Sandbox key"
  body='{"amount": "100.00", "currency": "USDC"}'
/>
```

## Attributes

| Attribute | Default | Description |
|---|---|---|
| `method` | `GET` | HTTP method. Also selects the colour of the method pill |
| `path` | `/` | Request path, shown in an editable field |
| `servers` | — | JSON array of `{ name, url }` environments, rendered as the environment toggle |
| `base-url` | — | Shorthand for a single unnamed environment. Ignored when `servers` is set |
| `auth-label` | `Authorization` | Placeholder for the credential field |
| `key-label` | — | Text of the chip beside the credential field, e.g. `Sandbox key` |
| `body` | — | Initial request body. Only rendered for methods that take one |

<Warning>
A Playground with neither `servers` nor `base-url` has nothing to call, and renders
nothing at all. If your console does not appear, that is the first thing to check.
</Warning>

## Layout

Above 1000px the console splits into two columns — request configuration on the
left, response on the right. Below that they stack. The response column is reserved
but empty until the first send, so the layout does not jump.

The body tab opens by default whenever the request has a body; otherwise the
console opens on Params.

## Environments

The environment toggle switches which base URL the request is sent to. Name the
environments the way your readers think about them:

```mdx
<Playground
  method="GET"
  path="/v1/customers"
  servers='[{"name":"Sandbox","url":"https://sandbox.api.example.com"},
            {"name":"Production","url":"https://api.example.com"}]'
/>
```

<Note>
Pair a sandbox environment with a `key-label` of `Sandbox key` so readers do not
paste a live credential into a page by reflex.
</Note>

## Related

- [API components](/components/api-components) — parameter and response fields for reference pages
- [Code blocks](/components/code-blocks) — static, non-interactive request examples
- [`features.playground`](/configuration/syntext-json#feature-flags) — the separate "Try it" console on generated API reference pages