API Playground

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:

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
• 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

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). 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:

yaml
responses:  '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.