# Try it playground

> For the complete documentation index, see [llms.txt](https://docs.writedocs.io/llms.txt).

How the API reference's Try it playground sends requests, and writedocs.json's api.proxy and api.playground settings.

Every page of an [API reference](https://docs.writedocs.io/docs/openapi/overview/) has a **Try it** button. It opens a playground where the reader fills in the parameters, body and credentials, sends a real request to your API, and sees the response - status, headers and body.

## `api.playground`

```json
{
  "api": {
    "playground": "scalar"
  }
}
```

**`playground`** `"writedocs" | "scalar"` default: `writedocs`

The client the **Try it** button opens, on every API page of the site. An OpenAPI group shown as [Scalar's API reference](https://docs.writedocs.io/docs/openapi/overview/#scalars-api-reference) (`"renderer": "scalar"`) always has Scalar's client, built into the reference, whatever this says.

- **`"writedocs"`** (the default): Writedocs' own playground.
- **`"scalar"`**: [Scalar](https://scalar.com)'s open-source API client, opened on the operation of the page.

With `scalar`, your API pages stay the same: one page per operation, in your site's layout, with your navigation, search, page menu, `llms.txt`, MCP server and [protected sections](https://docs.writedocs.io/docs/configuration/protected-sections/). Only what **Try it** opens changes - Scalar's client, already on the page's operation, with its parameters, body, examples and authentication from your OpenAPI spec. The request examples beside the page are Writedocs' in both cases.

### What the reader gets

- **Your site's look**: the client takes your site's colors, its body font, and its light or dark mode - including a `styles.appearance` that fixes one - and follows the reader when they switch.
- **Loaded on the first click**: an API page carries only a small script. Scalar's client - about 1 MB compressed - downloads when a reader clicks **Try it** for the first time - the button reads "Loading…" meanwhile - and the browser keeps it for the next pages. A reader who never clicks downloads nothing more than with Writedocs' playground; an API page is even slightly smaller, since it no longer carries Writedocs' playground.
- **Served from your site**: the client comes with the site, at the version of Writedocs that built it. Nothing loads from a third-party server: no CDN, no Scalar fonts, no Scalar account.

### Requests and the proxy

[`api.proxy`](#apiproxy) works the same with both playgrounds: a request goes straight to your API; only if the browser blocks it, and `proxy` is on, it's sent again through Writedocs' proxy - except a `POST` that may already have run. With Scalar, a response that came through the proxy lists an `x-writedocs-proxy` header among its response headers. Scalar's own hosted proxy is never used.

### Credentials

What a reader types in Scalar's client - a token, an API key, a username and password - stays in that browser tab: it's there on the other API pages of the visit, and in [Scalar's API reference](https://docs.writedocs.io/docs/openapi/overview/#scalars-api-reference) of the same site, and forgotten when the tab closes, as with Writedocs' playground. It's sent only with the reader's own requests.

### Limits

- **One choice for the whole site** - every API page opens the same client. A group shown as Scalar's API reference has Scalar's client either way.
- **Below 1150 px wide** (phones and small tablets), API pages have no **Try it** button, with either playground.
- **In `writedocs dev`**, switching `playground` takes effect on the next page load.

## `api.proxy`

```json
{
  "api": {
    "proxy": false
  }
}
```

**`proxy`** `boolean` default: `true`

Retry requests the browser blocks through Writedocs' proxy.

The playground sends each request from the reader's browser, straight to your API. A browser only lets a page read the response when the API allows that page's site - through CORS headers like `Access-Control-Allow-Origin`. Many APIs don't allow other sites, so the browser blocks the request.

With `proxy` on, a blocked request is sent again through Writedocs' proxy, which isn't subject to that rule, and the response says it went through the proxy. One exception: a `POST` with no JSON body, no credentials and no custom headers can reach your API even when the browser blocks its response, so it isn't sent again - that could run it twice.

With `proxy` off, requests never go through a third party, and a blocked request shows a message about CORS. To make the playground work without the proxy, allow your docs' domain in your API's CORS settings.

## Credentials

An API key or token the reader enters in the playground stays in that browser tab, and is forgotten when the tab closes. It's sent only with the reader's own requests - to your API, or through the proxy when a request is retried there.