Skip to main content
Generated endpoint pages take their title, description, parameters, and responses from your OpenAPI specification. To change what a page shows, either:
  • Add the x-mint extension to the operation in your specification. Your pages stay generated, and the changes live with your specification.
  • Create an MDX page for the endpoint. Use this for a few pages that need custom layouts, or to try out changes on one page.
To change a page’s URL, see Endpoint URLs and titles.

Override page metadata

Add x-mint.metadata to an operation to override the page’s frontmatter. You can use any field that’s valid in MDX frontmatter except openapi.
Use x-mint.metadata to set per-endpoint playground display, access groups, or a sidebar tag pill.

Add content to a page

Add Markdown and MDX content before the generated API documentation with x-mint.content. The content supports all Mintlify components.

Collapse playground fields

To start nested object fields collapsed in the playground, set x-mint.playground.expand to false on an operation. The Authorization, Headers, Query, Path, and Body sections and the top-level body object stay expanded, so readers expand only the nested fields they need. By default, object fields are expanded.
To control how optional fields display across all endpoints, use api.optional in your docs.json.

Add parameter pills

Label parameters with custom pills using x-mint.pre and x-mint.post on any schema. Pills in pre appear before the parameter name, and pills in post appear after it, next to built-in pills like required, read-only, and write-only. Each string in the array becomes its own pill.
To show a field from your specification as a pill on every parameter that has it, list the field’s key in api.params.post in your docs.json:
docs.json
With this configuration, a property like { "type": "string", "nullable": true, "x-internal": "admin" } shows nullable and admin pills next to its name. Post pills appear in this order: built-in pills, then api.params.post pills, then per-property x-mint.post pills.

Create MDX pages for endpoints

Create an MDX page for an endpoint when you want full control over a page but still want generated parameters and responses. Set the openapi frontmatter field to the operation the page documents.
The openapi value must be a single string that references one endpoint. If you set it to a list of endpoints or another non-string value, the deployment fails. The method and path must exactly match your OpenAPI specification. Add the page to your navigation like any other page. Don’t also list the same operation, such as "GET /users", in your navigation.
Always include the specification’s file path when you have more than one OpenAPI specification in your repository.Mintlify uploads every OpenAPI specification in your docs repository, even if docs.json doesn’t reference it. If an MDX page uses openapi: "METHOD /path" without a file path, Mintlify searches every uploaded specification for a matching operation. If more than one specification contains the same method and path, the first match in alphabetical filename order wins.To avoid the wrong match, include the file path in the frontmatter, generate the pages from docs.json instead, or delete specifications you no longer need.
To create MDX files for every endpoint in a specification, use the Mintlify scraper. Add -o to choose the output folder. Without it, files go in the current directory.
To move existing MDX endpoint pages back to generated pages, see Migrate MDX API pages to OpenAPI.

Create pages for data models

Create a page for a schema in your specification’s components.schemas with the openapi-schema frontmatter field.
If schemas in more than one specification share a name, include the file path: