Skip to content
Mintlify
Mintlify
Global settings

API settings

Configure OpenAPI and AsyncAPI specs, the interactive API playground, SDK code examples, and authentication settings in your docs.json file.

Use the api field in docs.json to configure what API specifications generate API pages, the interactive API playground for testing endpoints, and how to generate and display code examples.

Settings

api

Type: object

Define all API-related settings under the api key.

api.openapistring or array or object

OpenAPI specification files for generating API reference pages. Accepts a single path or URL, an array of paths and URLs, or an object specifying a source and directory.

Show api.openapi object
sourcestring

URL or path to your OpenAPI specification file. Minimum length: 1.

directorystring

Directory to search for OpenAPI files. Do not include a leading slash.

"openapi": "openapi.json"
api.asyncapistring or array or object

AsyncAPI specification files for generating event-driven API reference pages. Accepts a single path or URL, an array of paths and URLs, or an object specifying a source and directory.

Show api.asyncapi object
sourcestring

URL or path to your AsyncAPI specification file. Minimum length: 1.

directorystring

Directory to search for AsyncAPI files. Do not include a leading slash.

"asyncapi": "asyncapi.json"
api.playgroundobject

Interactive API playground settings.

Show api.playground
display"interactive" | "simple" | "none" | "auth"

The display mode for the playground. Defaults to interactive.

  • interactive — Full interactive playground with request builder
  • simple — Simplified view without the request builder
  • none — Hide the playground entirely
  • auth — Show the playground only to authenticated users
proxyboolean

Whether to route API requests through a proxy server. Defaults to true.

credentialsboolean

Whether to include cookies and authentication headers for cross-origin requests when proxy is false. Defaults to false. Has no effect when proxy is true.

api.paramsobject

Display settings for API parameters.

Show api.params
expanded"all" | "closed"

Whether to expand all parameters by default. Defaults to closed.

postarray of string

OpenAPI spec field keys to surface as post pills next to every parameter name in API reference pages and the playground. For each key you list, Mintlify reads the value from the schema and renders it as a pill:

  • String values render as the verbatim string.
  • true renders the key name as the pill label. false, null, and empty strings render nothing.
  • Number values render the stringified number.
  • Arrays of strings or numbers render one pill per element.
  • Objects and other values are skipped.

Use this to expose custom OpenAPI fields—such as x-internal, nullable, or vendor extensions—as visual annotations on each parameter without per-property configuration.

api.url"full"

Display mode for the base URL in the endpoint header. Set to full to always show the complete base URL on every endpoint page. By default, the base URL is only shown when there are multiple base URLs to select from.

api.examplesobject

Settings for autogenerated API code examples.

Show api.examples
languagesarray of string

Languages for autogenerated code snippets. See supported languages for the full list of available languages and aliases.

defaults"required" | "all"

Whether to include optional parameters in generated examples. Defaults to all.

prefillboolean

Whether to prefill the playground with example values from your OpenAPI specification. Defaults to false.

autogenerateboolean

Whether to generate code samples for endpoints from your API specification. Defaults to true. When set to false, only manually written code samples (from x-codeSamples in OpenAPI or <RequestExample> components in MDX) appear in the playground.

api.mdxobject

Settings for API pages built from MDX files rather than OpenAPI specs.

Show api.mdx
authobject

Authentication configuration for MDX-based API requests.

Show auth
method"bearer" | "basic" | "key" | "cobo"

Authentication method for API requests.

namestring

Authentication parameter name for API requests.

serverstring or array

Base URL prepended to relative paths in page-level api frontmatter fields. Not used when the frontmatter contains a full URL.

Example

docs.json
{
  "api": {
    "openapi": ["openapi/v1.json", "openapi/v2.json"],
    "playground": {
      "display": "interactive"
    },
    "params": {
      "expanded": "all",
      "post": ["nullable", "x-internal"]
    },
    "url": "full",
    "examples": {
      "languages": ["curl", "python", "javascript", "go"],
      "defaults": "required",
      "prefill": true,
      "autogenerate": true
    }
  }
}
Ctrl+I

On this page

SettingsapiExample