API Playground
The interactive API playground lets readers test API endpoints directly from your documentation pages.
Overview
The HolyDocs API Playground is an interactive tool embedded in your API reference pages. Readers can fill in parameters, set headers, and execute real API requests without leaving your documentation.
Features
How It Works
The playground is automatically enabled for all API pages generated from OpenAPI specs. When a reader clicks Try It, the playground:
- Renders input fields for all parameters defined in the spec
- Pre-fills required fields with example values from the spec
- Shows the authentication header based on your
api.mdx.authconfiguration - Sends the request through the HolyDocs proxy to avoid CORS issues
- Displays the response with syntax highlighting
Proxy
API requests from the playground are routed through the HolyDocs proxy at:
texthttps://api.holydocs.com/api/v1/proxy/{projectId}
The proxy:
- Adds CORS headers to the response
- Calls only hosts your project declares (see below)
- Includes SSRF protection to prevent requests to internal networks
- Logs request metadata for analytics (no request bodies are stored)
- Strips sensitive headers from the response
Allowed hosts
The proxy sends a request only when its host is one of:
- a host from the
serversof your deployed OpenAPI spec, including per-operation servers and everyenumvalue of a server variable - the host of
api.mdx.auth.oauth2TokenUrl, for the playground's OAuth flow - a host listed in
api.playground.allowedHosts
Any other host gets a 403 (error code 6005), including a Custom URL typed into the playground. Redirects are followed only to allowed hosts; a redirect elsewhere is returned to the playground as is. To let readers try a sandbox or a regional host that is not in your spec, list it:
json{ "api": { "playground": { "allowedHosts": ["sandbox.example.com", "eu.api.example.com"] } }}
Entries are host names (a full URL also works; only its host is used). Changes apply on the next deploy.
The proxy has SSRF protections that block requests to private IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x, localhost), even for an allowed host. API servers must be publicly accessible.
Configuration
Display Mode
Control the playground display in docs.json:
json{ "api": { "playground": { "display": "interactive" } }}
| Mode | Description |
|---|---|
interactive | Full playground with request builder and execution (default) |
simple | Read-only examples without live execution |
none | No playground — only schema documentation |
Example Defaults
Control how examples are pre-filled:
json{ "api": { "examples": { "defaults": "required", "prefill": true, "languages": ["javascript", "python", "curl", "go", "ruby", "php", "java"] } }}
| Option | Values | Description |
|---|---|---|
defaults | required | all | Pre-fill only required params, or all params |
prefill | boolean | Whether to pre-fill fields with example values |
languages | string[] | Which languages to show in code samples |
Authentication
Bearer Token
The playground includes an authentication section where readers can paste their API key or bearer token:
json{ "api": { "mdx": { "auth": { "method": "bearer", "name": "Authorization" } } }}
Base URL
Set the default server URL for API requests:
json{ "api": { "mdx": { "server": "https://api.yourcompany.com" } }}
Multiple servers can be listed, allowing readers to switch between environments:
json{ "api": { "mdx": { "server": [ "https://api.yourcompany.com", "https://staging-api.yourcompany.com" ] } }}
Response Examples
If your OpenAPI spec includes response examples, they are displayed below the playground as reference:
yamlresponses: '200': description: Success content: application/json: example: id: "usr_123" name: "Jane Doe" email: "jane@example.com"
Plan Requirements
| Plan | API Playground |
|---|---|
| Free | Not available |
| Starter | Available |
| Pro | Available |
| Business | Available |
| Enterprise | Available |
The API Playground requires the Starter plan or above. Free plan users see read-only API documentation without the interactive playground.