Try-it playground

What it is

Every auto-generated endpoint page (and any manual MDX page that wraps an endpoint) gets a Try it button next to the URL. Clicking it opens a two-pane modal:

• Left pane — Auto-generated form with one input per parameter, plus a body textarea pre-filled with a JSON template from the request body schema

• Right pane — Live cURL preview that updates as the form fills out, plus the response (status, headers, body) once the request completes

The reader fires a real fetch() from the browser, sees the actual response, and copies the cURL one-click to drop into their own terminal.

How the form is built

The form is generated entirely from the parsed OpenAPI schema — no per-endpoint configuration needed:

Authorization

The auth input is separate from the headers section and supports three schemes:

The reader's auth value is never persisted — it lives in the modal's local state only. Close the modal and the value is gone. This keeps API tokens out of localStorage and out of your tenant analytics.

cURL preview

The right pane shows a live cURL command that mirrors the request the playground will fire. As the reader fills out the form, the cURL string updates in real time. One click on Copy as cURL ships it to the clipboard ready to paste into a terminal.

curl -X POST 'https://api.acme.com/v1/users' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice","email":"alice@example.com"}'

Sending the request

The Send request button calls fetch() directly from the browser. This means:

• CORS must be configured on your API for the docs site origin

• Mixed content rules apply — your API must be HTTPS if your docs site is HTTPS

• Cookies / credentials are NOT sent by default (the playground doesn't set credentials: "include")

If your API has strict CORS or you don't want to expose it to the docs origin, the Phase 4 follow-up will add an optional server-side proxy at /api/playground/proxy that the playground can route through.

Response viewer

The response panel shows:

• Status badge — green for 2xx, red for 4xx/5xx, with the HTTP status text

• Duration — milliseconds from button click to response

• Body — pretty-printed JSON if Content-Type: application/json, otherwise raw text

• Network errors — fall through with a friendly error message instead of a stack trace

The body viewer is plain <pre> for v1. JSON tree expansion ships in a Phase 4 follow-up.

When the playground appears

The Try-It button is enabled by default on every auto-generated endpoint page. To hide it for a specific endpoint or for the entire site, you have two options:

1. Per-spec disable — set playground: false (or playground: "none") in codiv.config.json#api:

   {
     "api": {
       "openapi": "openapi.json",
       "playground": false
     }
   }

2. Per-endpoint disable — when writing manual MDX that uses <ApiEndpoint>, pass playground={false} (Phase 4 follow-up — not yet wired into MDX exposure)

Differences from <RequestExample>

The two are complementary, not competing. Most endpoint pages use both: a <RequestExample> block at the top showing the canonical request shape, and a Try It modal for readers who want to experiment.

Known limits (v1)

• Single-language cURL output — multi-language Copy buttons are queued

• No JSON tree for the response — pretty-printed text only

• No streaming responses — waits for the full body before rendering

• No file uploads — multipart/form-data is not yet supported

• No save/share — you can't link to a pre-filled form state

• No history — reload the modal and your previous request is gone

These are all v1 trade-offs. The most-asked items will land in Phase 4 follow-up commits.

Try it

Find any auto-generated endpoint page on this site (e.g. /api-reference/projects/create-project once a tenant ships an OpenAPI spec) and click the Try it button next to the URL. The modal opens with the form pre-filled from the schema and you're ready to fire requests.