Skip to main content
Add an openapi field to any navigation element in your docs.json, such as a tab, anchor, or group, to generate endpoint pages from a specification. The openapi field accepts a path in your docs repository or the URL of a hosted specification. You can add endpoints in two ways:
  • Generate a section from a whole specification. Every endpoint gets a page, grouped by tag. Use this for most API references.
  • List specific endpoints. Only the endpoints you list get pages, in the order you list them, alongside your other pages.

Generate a section from a specification

Add an openapi field to a navigation element with no pages. Every endpoint in the specification gets a page in that element.
docs.json
Mintlify groups generated pages by tag. If an operation has more than one tag, it goes in the group for its first tag. Operations without tags go in a group named API Reference. For how pages get their titles and URLs, see Endpoint URLs and titles.

Rename tag groups

By default, a group’s label is its tag name. To show a different label, add x-group to the tag. The URL still uses the tag name.
If a tag has no x-group, Mintlify uses its x-displayName extension as the label, so specifications that already use x-displayName need no changes. If a tag has both, x-group wins.

Nest groups with tag hierarchies

In OpenAPI 3.2 documents, tags can declare parent, kind, and summary fields. Mintlify uses them to build nested groups. OpenAPI 3.0 and 3.1 documents keep one flat group per tag.
  • parent: Nests the tag’s group inside the parent tag’s group.
  • summary: Sets the group label. If a tag also has x-group or x-displayName, the extension wins, with x-group first.
  • kind: Controls how Mintlify uses the tag.
    • nav or no kind: Creates a navigation group.
    • badge: Shows the tag’s summary, or its name if there is no summary, as a pill next to the endpoint in the sidebar. Badge tags don’t create groups.
    • Any other value, such as audience: Creates neither a group nor a pill.
In this example, the List plants endpoint appears under Store > Plants in the sidebar with a Beta pill. If an operation has several tags, Mintlify places it using the first tag with kind: nav. If there is none, Mintlify uses the first declared tag with no kind, and then the first tag that isn’t declared in tags. To set a different pill for one endpoint, use tag in x-mint.metadata, which takes precedence over badge tags. Validation fails if two tags share a name, if a parent references a tag that doesn’t exist, or if parent references form a cycle.

List specific endpoints

To choose which endpoints get pages and where they go, set a default openapi on a navigation element and list endpoints in its pages as METHOD /path. You can mix endpoints with other pages.
docs.json
If you list any endpoint from a specification, only the endpoints you list get pages, including those in child elements. Mintlify doesn’t add the rest. Child navigation elements inherit their parent’s specification unless they set their own openapi:
docs.json
To list an endpoint without a default specification, put the specification’s path before the method:
docs.json
Mintlify treats any pages entry that doesn’t match an operation as a file path. HTTP methods must be uppercase.

Use multiple specifications

To generate pages from more than one specification, put each specification on its own navigation element, and give each one its own directory. If you set openapi to an array, Mintlify generates pages only from the first specification in the array.
docs.json
directory sets the folder in the URL of each generated page. If two specifications share a directory and produce the same page URL, one page silently replaces the other. See Endpoint URLs and titles.

Organize a large specification

Mintlify doesn’t read the x-tagGroups extension. For a specification with many tags, pick one approach:
  • One specification per section. Split the specification into one file per product area, or use overlays to remove the operations that don’t belong in each section, then give each its own section.
  • Tag hierarchies. Upgrade to OpenAPI 3.2 and nest tags under parent tags.
  • List endpoints. List each endpoint in your docs.json in the groups you want. This gives you full control, but you must add new endpoints to docs.json yourself.

Hide or exclude endpoints

Add x-hidden or x-excluded to an operation or webhook to keep it out of your generated navigation:
  • x-hidden: true: The endpoint gets a page, but the page doesn’t appear in the navigation. Anyone with the URL can open it. Use this for endpoints you link to from other pages or share with specific users.
  • x-excluded: true: The endpoint doesn’t get a page. Use this for internal endpoints, or endpoints that aren’t ready to document.
x-excluded only removes the page. If visitors can access your specification file, excluded endpoints are still in it. To show endpoints only to specific user groups, add x-mint.groups to the operation. See OpenAPI content filtering.