Skip to main content
The API playground sends real requests to your API from your endpoint pages. To work, it needs a base URL and, if your API requires it, an authentication method. Both come from your OpenAPI specification. Display and network settings come from the api.playground object in your docs.json.

Set the base URL

Add a servers field to your OpenAPI specification with your API’s base URL. The playground appends each endpoint’s path, such as /users/{id}, to this URL.
If you list more than one server, readers pick one from a dropdown. If you don’t list a server, the playground can’t send requests and shows the endpoint in simple mode. If your API serves some endpoints from a different URL, override the servers field for a path or operation. For more about the servers field, see API server and base path in the OpenAPI documentation.

Add authentication

Define how readers authenticate with the securitySchemes and security fields in your OpenAPI specification. The playground adds an input for each scheme so readers can enter credentials before they send a request.
1

Define your authentication method.

Add a securitySchemes field. This example defines bearer authentication.
2

Apply authentication to your endpoints.

Add a security field to require the scheme.
Common authentication types include:
  • API keys: For header, query, or cookie-based keys.
  • Bearer: For JWT or OAuth tokens.
  • Basic: For a username and password.
If different endpoints require different authentication methods, override the security field for an operation. For more information, see Authentication in the OpenAPI documentation.

Describe the authorization field

The playground generates a description for the authorization field based on the security scheme type. To replace it with your own text, such as where readers find their key, add a description to the security scheme. The description supports Markdown and applies to every endpoint that uses the scheme.

Prefill credentials

Add the x-default extension to a security scheme to prefill its input in the playground, for example with a placeholder or a test credential. x-default works on apiKey and http bearer schemes.
Anyone who can open your endpoint pages can see an x-default value. Never use a production credential.

Show required scopes

If an operation’s security field lists scopes, the endpoint page shows them in a Scopes section after the authorization section. The playground also lists them under the selected authorization option’s input.
The Scopes section lists the scopes from every option in the security field, so readers see them whichever authorization option they select. In this example, users:read appears even though apiToken is the first option.
  • Scope descriptions come from the scopes map in the OAuth 2.0 scheme’s flows.
  • In OpenAPI 3.1, role lists on apiKey and http requirements, such as { "apiKey": ["admin"] }, appear in the same section.
  • If more than one scheme requires scopes, a label next to each scope shows its scheme name.

Choose a display mode

Set api.playground.display in your docs.json to control what appears on every endpoint page:
  • interactive (default): The full playground.
  • simple: A copyable endpoint with no playground.
  • none: No playground.
  • auth: The full playground for signed-in readers, and nothing for everyone else. See Show the playground only to signed-in readers.
docs.json
To change the mode for one endpoint, set playground in the page’s frontmatter, or in x-mint.metadata for a generated page.

Show the playground only to signed-in readers

Use the auth display mode to keep your API reference public while letting only signed-in readers send requests. The auth mode requires authentication on your site. To limit the playground to specific user groups, add groups to the page frontmatter. If the page has no groups, every signed-in reader sees the playground.
In this example, anyone can read the page, but only signed-in readers in the admin or developer groups see the playground. For generated pages, set the same fields in x-mint.metadata:

Send requests through the proxy

By default, the playground sends requests through Mintlify’s proxy, so your API doesn’t need to accept cross-origin requests from your docs domain. Set api.playground.proxy to false to send requests directly from the reader’s browser to your API. Do this if your API requires headers that the proxy can’t forward, or if requests must come from the reader’s browser, for example for cookie-based authentication. Your API must then allow cross-origin requests from your docs domain with CORS. To send cookies, authorization headers, and TLS client certificates with direct requests, also set credentials to true.
docs.json
If you serve your docs through a reverse proxy on a custom domain, the reverse proxy must allow POST requests to the /_mintlify/api/request path. With Mintlify’s proxy on, the playground sends each request as a POST to that path. If your reverse proxy can’t allow POST requests, set proxy to false.

Prefill example values

To fill request fields with the example values from your OpenAPI specification, set api.examples.prefill to true in your docs.json.
docs.json
To prefill a field with a value that differs from its schema default, add x-default to the property. x-default on a property only takes effect when prefill is true. x-default on a security scheme always takes effect. For the full list of playground settings, see API settings.