API Playground

The API Playground component renders a single, runnable endpoint inside your page. Readers fill in the parameters, hit Send, and see the actual HTTP response — without leaving the docs.

It's the building block behind the auto-generated OpenAPI reference. You can also drop a single playground into any page when you want a focused example.

Example#

Source#

<APIPlayground
  method="GET"
  url="https://api.example.com/v1/users/{id}"
  parameters={[
    { name: "id", type: "string", required: true, description: "User ID" }
  ]}
/>

Props#

Authentication#

The playground reads project-level auth config from Settings → API → Authentication. Readers see an "Add token" field above the request form; tokens are stored in browser local storage only — never sent to Dokly servers.

If you set auth="none" on a specific playground, the auth field is hidden — useful for public endpoints.

Body schema#

For POST/PUT/PATCH endpoints, define the body shape:

<APIPlayground
  method="POST"
  url="https://api.example.com/v1/users"
  body={{
    type: "object",
    properties: {
      name: { type: "string", description: "Full name" },
      email: { type: "string", format: "email" }
    },
    required: ["name", "email"]
  }}
/>

The playground generates a form from the schema. Readers can also switch to "Raw JSON" mode to paste a body directly.

Response viewer#

The response panel shows:

• Status — color-coded (green for 2xx, yellow for 4xx, red for 5xx).
• Time — request duration.
• Headers — collapsible.
• Body — pretty-printed JSON with syntax highlighting. Auto-collapsed if longer than 50 lines.

If the API returns CORS errors, the playground shows a friendly error explaining why and links to your CORS configuration page.

CORS configuration#

For the playground to actually call your API, your API must allow requests from *.dokly.co (or your custom domain). Add to your CORS config:

Access-Control-Allow-Origin: https://docs.acme.com
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE

For development, you can also add https://localhost:3000 and https://*.dokly.co.

When to use a single playground vs OpenAPI#

The OpenAPI import is just a way to generate one playground per endpoint at scale. The component is the same.

Where next#