> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

**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:

```
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.