api.playground object in your docs.json.
Set the base URL
Add aservers 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.
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 thesecuritySchemes 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.- API keys: For header, query, or cookie-based keys.
- Bearer: For JWT or OAuth tokens.
- Basic: For a username and password.
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 adescription to the security scheme. The description supports Markdown and applies to every endpoint that uses the scheme.
Prefill credentials
Add thex-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.
Show required scopes
If an operation’ssecurity 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.
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
scopesmap in the OAuth 2.0 scheme’sflows. - In OpenAPI 3.1, role lists on
apiKeyandhttprequirements, 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
Setapi.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
playground in the page’s frontmatter, or in x-mint.metadata for a generated page.
Show the playground only to signed-in readers
Use theauth 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.
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. Setapi.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
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, setapi.examples.prefill to true in your docs.json.
docs.json
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.