Try it playground

Every page of an API reference 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

{
  "api": {
    "playground": "scalar"
  }
}

• "writedocs" (the default): Writedocs’ own playground.
• "scalar": Scalar’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. 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 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 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

{
  "api": {
    "proxy": false
  }
}

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.