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.
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.
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.
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.
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.
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.
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.
