/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Components Playground

Playground

An interactive request console readers can send real API calls from.

3 min read

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.

Note

<Playground> is doc engine v1 only, and on v1 it is built on guide pages only. Doc engine v2 renders nothing for it — endpoint pages there get Try it instead.

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"}]'
keyLabel="Sandbox key"
body='{"amount": "100.00", "currency": "USDC"}'
/>

Attributes

AttributeDefaultDescription
methodGETHTTP 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
baseUrl—Shorthand for a single unnamed environment. Ignored when servers is set
authLabelAuthorizationPlaceholder for the credential field
keyLabel—Text of the chip beside the credential field, e.g. Sandbox key
body—Initial request body. Only rendered for methods that take one

base-url, auth-label and key-label are the older, hyphenated names of baseUrl, authLabel and keyLabel. They still work, but they're deprecated: the build log warns with the file and line, and stx migrate renames them.

Warning

A Playground with neither servers nor baseUrl has nothing to call, and renders nothing at all. If your console does not appear, that is the first thing to check.

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 keyLabel of Sandbox key so readers do not paste a live credential into a page by reflex.

Which hosts a request can reach

<Playground> does not use this — it calls your API straight from the browser. The rule below is for the dashboard's API playground, which sends requests on your behalf so the browser doesn't have to deal with CORS. It reaches public hosts only: the URL must be http or https, and private or local addresses (such as localhost or a host on your internal network) are refused with a BLOCKED_HOST error. Write IPv4 addresses in plain dotted form.

A hostname that resolves to a private address is refused the same way, with 403 BLOCKED_HOST.

•
Redirects are followed up to 5 times, each checked the same way. When a redirect goes to another origin, your key and other credentials are not passed on.
•
Responses are cut at 512 KB, ending with [Response truncated at 512KB].
•
Concurrency: at most 5 requests in flight per project and 20 per organization. Over that, the playground answers 429 RATE_LIMITED; try again in a moment.
•
Host, Cookie and connection headers you set are not sent.
Note

If your API only listens on a private network, the playground cannot reach it. Point the environment at a publicly reachable staging host, or delete the <Playground> tag. features.playground controls only Try it on API reference pages.

•
API components — parameter and response fields for reference pages
•
Code blocks — static, non-interactive request examples
•
features.playground — the separate "Try it" console on generated API reference pages
Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext