Skip to main content
The API playground is an interactive environment that lets users test and explore your API endpoints. Developers can craft API requests, submit them, and view responses without leaving your documentation.
API playground for the trigger an update endpoint.
The playground generates interactive pages for your endpoints based on your OpenAPI specification or AsyncAPI schema. If you modify your API, the playground automatically updates the relevant pages.
We recommend generating your API playground from an OpenAPI specification. However, you can manually create API reference pages after defining a base URL and authentication method in your docs.json.

​
Get started

1

Add your OpenAPI specification file

Validate your OpenAPI specification file using the Swagger Editor or Mint CLI command mint openapi-check <filename>.
/your-project
  |- docs.json
  |- openapi.json
2

Generate endpoint pages

Update your docs.json to reference your OpenAPI specification.To automatically generate pages for all endpoints in your OpenAPI specification, add an openapi property to any navigation element.This example generates a page for each endpoint specified in openapi.json and organizes the pages in the “API reference” group.
Generate all endpoint pages
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
To generate pages for only specific endpoints, list the endpoints in the pages property of the navigation element.This example generates pages for only the GET /users and POST /users endpoints. To generate other endpoint pages, add additional endpoints to the pages array.
Generate specific endpoint pages
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
Customize your playground

Customize your API playground by defining the following properties in your docs.json.

​
Playground display

Control how the API playground appears to users with the playground.display property:
  • "interactive": Display the interactive playground (default)
  • "simple": Display a copyable endpoint with no playground
  • "none": Display nothing
  • "auth": Display the interactive playground only to authenticated users
{
  "api": {
    "playground": {
      "display": "interactive",
      "proxy": true
    }
  }
}
The proxy option controls whether to pass API requests through a proxy server. Defaults to true.

​
Example code snippets

Configure the autogenerated API examples with the examples property: 
{
  "api": {
    "examples": {
      "languages": ["curl", "python", "javascript"],
      "defaults": "required",
      "prefill": true,
      "autogenerate": true
    }
  }
}
Available options:
  • languages: Array of programming languages to show in code examples. Languages display in the order specified.
  • defaults: Whether to show optional parameters ("all") or only required ones ("required"). Defaults to "all".
  • prefill: Whether to prefill the API playground with data from schema examples. Defaults to false.
  • autogenerate: Whether to generate code samples from API specifications. Defaults to true.
Supported languages include: cURL, Python, JavaScript, Node.js, PHP, Go, Java, Ruby, PowerShell, Swift, C#, .NET, TypeScript, C, C++, Kotlin, Rust, and Dart.

​
Example configuration

This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. Only required parameters are shown in the code snippets, and the playground prefills the request body with example values. 
{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required",
     "prefill": true
   }
 }
}

​
Auth-based playground display

Use the auth display mode to show the interactive playground only to authenticated users. This is useful when you want to let users view your API documentation publicly while restricting playground access to logged-in users. When display is set to auth:
  • Authenticated users see the interactive playground
  • Unauthenticated users see no playground (equivalent to none)
You can also combine auth with the groups property in page frontmatter to restrict playground access to specific user groups.
Page with group-restricted playground
---
title: "Create user"
openapi: POST /users
playground: auth
groups: ["admin", "developer"]
public: true
---
In this example:
  • The page is publicly visible (anyone can view the documentation)
  • Only authenticated users in the admin or developer groups see the interactive playground
  • Users not in those groups see no playground
The auth display mode requires authentication to be configured for your documentation.

​
Custom endpoint pages

When you need more control over your API documentation, use the x-mint extension in your OpenAPI specification or create individual MDX pages for your endpoints. Both options allow you to:
  • Customize page metadata
  • Add additional content like examples
  • Control playground behavior per page
The x-mint extension is recommended so that all of your API documentation is automatically generated from your OpenAPI specification and maintained in one file.
Individual MDX pages are recommended for small APIs or when you want to experiment with changes on a per-page basis.

​
Further reading

OpenAPI setup

Learn how to create and configure your OpenAPI document

MDX setup

Create manual API reference pages with MDX files

AsyncAPI setup

Document WebSocket APIs with AsyncAPI schemas

Build docs developers (and LLMs) love

Get started for freeTalk to us