API Playground

The API playground adds an interactive "Try it" button to your API endpoint pages. Developers fill in parameters, see code examples update in real time, and send real HTTP requests from the docs page.

Quick Start

The playground is on by default, with no docs.json configuration. Every page with an openapi: or api: frontmatter field gets a "Try it" button. CORS needs no setup.

Display Modes

The display field controls what the playground can do:

Mode	"Try it" Button	Fill Params	Live Code	Send Request
`"interactive"` (default)	✓	✓	✓	✓
`"simple"`	✓	✓	✓	✗
`"none"`	✗	✗	✗	✗

Full playground experience. Developers fill in parameters, see code examples update live, and send real HTTP requests. Responses display inline with status codes, timing, and formatted bodies.

docs.json

{
  "api": {
    "playground": {
      "display": "interactive"
    }
  }
}

Authentication

The playground shows an auth input field at the top of the parameter form when your API requires authentication (configured via api.mdx.auth.method in docs.json). Developers enter their API key or token in the modal.

Credentials are held in memory only for the current session. They are never saved to localStorage or persisted between visits.

Pre-filling Example Values

The playground can pre-fill the example values on parameters and request bodies in your OpenAPI spec:

docs.json

{
  "api": {
    "examples": {
      "prefill": true
    }
  }
}

Developers start from realistic values instead of empty fields.

Per-Page Override

Override the global display mode on individual pages using the playground frontmatter field:

---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---

Use this to turn the playground off globally but on for specific demo endpoints, or the reverse.

Frontmatter	Behavior
`playground: interactive`	Full playground on this page
`playground: simple`	Code-only playground on this page
`playground: none`	No playground on this page

How It Works

Click 'Try it'

The playground opens as a full-screen modal overlay. Your docs page stays intact underneath.

Fill in parameters

Path, query, header, and body parameters are shown as form fields. Required fields are marked. The base URL is pulled from your OpenAPI spec's servers field.

Watch code update

Code examples regenerate as you type, in every configured language. Copy any example with one click.

Send the request

In interactive mode, click Send (or press Ctrl/Cmd+Enter) to execute the request. The response displays below with status code, duration, and formatted body.

API playground showing a 201 Created response with JSON body after sending a request

The URL gets ?playground=open while the playground is open. Share it to link straight to the playground view of an endpoint.

Multiple Servers

A server picker appears next to the endpoint URL when an endpoint's spec lists more than one entry under servers (production and sandbox, for example). The reader's pick sets the base URL, the copy-URL button, the code samples on the page, and the request the playground sends.

Endpoints with one server show no picker and add no page weight.

Keyboard Shortcuts

Shortcut	Action
`Ctrl/Cmd + Enter`	Send request
`Escape`	Close playground

Works With Both API Page Types

The playground works on pages using either the openapi: or api: frontmatter format:

Jamdesk pulls parameters and schemas from your OpenAPI spec. No setup needed.

---
openapi: POST /tickets
---

Local Development

The playground only works in production. jamdesk dev shows the "Try it" buttons. Clicking one shows a brief notification instead of opening the modal. Deploy your docs to use the full playground.

Try It Live

This site has the playground on. Open the OpenAPI Example page and click "Try it" to send a request to the demo API.

What's Next?

OpenAPI Example

See a live playground on an auto-generated endpoint page

docs.json Reference

Full configuration reference including api.playground

Request/Response Examples

Hand-authored API endpoint pages with MDX components

Code Examples

Configure which languages appear in code examples