> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mintlify/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API Playground
> Let developers test API endpoints directly in your documentation with interactive playgrounds.
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.
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
Validate your OpenAPI specification file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint) command `mint openapi-check `.
```bash {3} theme={null}
/your-project
|- docs.json
|- openapi.json
```
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.
```json Generate all endpoint pages theme={null}
"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.
```json Generate specific endpoint pages theme={null}
"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
```json theme={null}
{
"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:
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```mdx Page with group-restricted playground theme={null}
---
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](/deploy/authentication-setup) 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
Learn how to create and configure your OpenAPI document
Create manual API reference pages with MDX files
Document WebSocket APIs with AsyncAPI schemas