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

Live Requests

Execute real HTTP requests against your API directly from the docs.

Request Builder

Visual form for path params, query params, headers, and request body.

Response Viewer

Formatted JSON response with status code, headers, and timing.

Code Samples

Auto-generated code in 7 languages that updates as you fill in parameters.

How It Works

The playground is automatically enabled for all API pages generated from OpenAPI specs. When a reader clicks Try It, the playground:

  1. Renders input fields for all parameters defined in the spec
  2. Pre-fills required fields with example values from the spec
  3. Shows the authentication header based on your api.mdx.auth configuration
  4. Sends the request through the HolyDocs proxy to avoid CORS issues
  5. Displays the response with syntax highlighting

Proxy

API requests from the playground are routed through the HolyDocs proxy at:

text
https://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 servers of your deployed OpenAPI spec, including per-operation servers and every enum value 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" } }}
ModeDescription
interactiveFull playground with request builder and execution (default)
simpleRead-only examples without live execution
noneNo 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"] } }}
OptionValuesDescription
defaultsrequired | allPre-fill only required params, or all params
prefillbooleanWhether to pre-fill fields with example values
languagesstring[]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:

yaml
responses: '200': description: Success content: application/json: example: id: "usr_123" name: "Jane Doe" email: "jane@example.com"

Plan Requirements

PlanAPI Playground
FreeNot available
StarterAvailable
ProAvailable
BusinessAvailable
EnterpriseAvailable

The API Playground requires the Starter plan or above. Free plan users see read-only API documentation without the interactive playground.

Ask a question... ⌘I