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.
Pro plan or higherExample#
Screenshot needed
screenshot of the rendered playground showing parameter form, Send button, response viewer
Insert#
Use the slash menu: /api. After inserting, click the block to open the inspector — that's where you set the method, URL, parameters, body schema, headers, and auth scheme.
Settings#
| Setting | Description |
|---|---|
| Method | GET, POST, PUT, PATCH, DELETE |
| URL | Full URL, with {path} placeholders for path params |
| Parameters | Path and query params — name, type, required, description |
| Body | JSON Schema for the request body (POST/PUT/PATCH) |
| Headers | Name/value pairs (Authorization is added automatically) |
| Auth | Bearer, API key, Basic, or None — defaults to your project setting |
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 their browser only — never sent to Dokly servers.
Set Auth to None on a specific playground to hide the auth field — useful for public endpoints.
Body schema#
For POST, PUT, and PATCH endpoints, set the body schema in the inspector. 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, DELETEFor development, you can also add https://localhost:3000 and https://*.dokly.co.
When to use a single playground vs OpenAPI#
| Situation | Use |
|---|---|
| One or two endpoints in the middle of a guide | Single <APIPlayground> |
| Full API reference (10+ endpoints) | OpenAPI import |
The OpenAPI import is just a way to generate one playground per endpoint at scale. The component is the same.