Make your API reference interactive — readers run real requests from inside the docs.

The Dokly API Playground lets readers send real requests to your API from inside the docs. Fill in parameters, hit Send, see the actual response. No copy-pasting curl into a terminal.

The playground component is documented in detail in Components → API Playground. This page is about the bigger picture — how to structure an API reference section that uses it well.

Pro plan or higher

The two ways to add a playground#

One playground at a time

Drop a single <APIPlayground> block into a guide. Right for tutorials and one-off examples.

From an OpenAPI spec

Upload your spec; Dokly generates one page per endpoint. Right for full API references.

What a good API reference looks like#

The reference is the spine of your developer docs. A good one has:

A landing page that orients

Not a list of endpoints — a brief explanation of what the API does, the auth model, the rate limits, and where to start. Link to the quickstart from here.

Endpoints grouped by resource

/users together. /projects together. /billing together. Don't sort alphabetically — group by what readers actually do together.

Each endpoint as its own page

With the playground at the top, prose context below, code samples in three or four languages, and a real response example.

A quickstart that uses the playground

The first page a developer reads should walk them through their first successful request — using the playground, not curl. The activation moment is when they see a 200 response in the docs.

Structure your sidebar#

Common pattern for an API reference section:

Text

API Reference
├ Overview                     ← what the API does, auth, rate limits
├ Authentication               ← how to get a token, where to put it
├ Errors                       ← error format, common codes
├ Users                        ← group
│   ├ List users
│   ├ Get user
│   ├ Create user
│   └ Delete user
├ Projects                     ← group
│   ├ List projects
│   └ ...
└ Webhooks                     ← group
    └ ...

OpenAPI import generates this structure automatically from your spec's tags.

Authentication setup#

The playground needs a way to authenticate against your API. Configure once, applies everywhere.

In Project Settings → API → Authentication:

Auth type	What you configure	What readers see
Bearer token	Header name (`Authorization`) and prefix (`Bearer`)	Token input field above the request form
API key	Header or query param name	Key input field
Basic	Realm	Username + password fields
OAuth 2.0	Authorize URL, token URL, scopes	"Sign in with..." button that opens the OAuth flow
None	—	No auth UI

Tokens entered by readers are stored in browser localStorage only. They never reach Dokly servers.

CORS#

For the playground to work, your API must allow cross-origin requests from your docs domain. See the API Playground component for the headers you need to send.

If CORS isn't set up, the playground returns a clear error explaining what's wrong, with a link to this page.

Playground