Skip to main content
Mintlify builds the URL and title of each generated endpoint page from your OpenAPI specification. If you edit a summary or a tag, the page’s URL changes, and existing links to it break.

How URLs are built

A generated page’s URL has three parts:
For example, an operation tagged users with the summary Get user gets the URL /api-reference/users/get-user.
  • Directory: The directory you set on the openapi field in your docs.json, in lowercase. Defaults to api-reference.
  • Tag: The name of the operation’s tag. Labels from x-group, x-displayName, or a 3.2 tag summary don’t change the URL. If an operation has no tags, the URL has no tag part. For which tag Mintlify uses when an operation has several, see Nest groups with tag hierarchies. Parent tags in OpenAPI 3.2 don’t add parts to the URL.
  • Slug: The operation’s summary, converted for use in a URL. If the operation has no summary, Mintlify uses the HTTP method and path. For example, GET /users/{id}/posts becomes get-users-posts.
To convert a summary or tag name, Mintlify replaces spaces with hyphens, removes {, }, (, ), ,, ., ', and /, and lowercases the result. Other characters, such as ?, &, :, and non-ASCII letters, stay in the URL. To get predictable URLs, use summaries and tag names made of letters, numbers, and spaces, or use operation IDs.

Duplicate URLs

If two endpoints in the same group produce the same URL, Mintlify adds -1, -2, and so on to the later ones. In some cases, one page replaces the other instead, with no error:
  • Two specifications that share a directory, or the same specification used in two places in your navigation.
  • An endpoint with x-hidden that produces the same URL as another endpoint.
Give every endpoint a unique summary within its tag, and give every specification its own directory.

Use operation IDs

Set slug to operationId to build the slug from each operation’s operationId instead of its summary. Then you can edit summaries without changing URLs.
docs.json
Mintlify converts the ID to kebab case, so getActions becomes get-actions and create_action becomes create-action. Mintlify drops any character that isn’t an ASCII letter or number. Operations without an operationId use the summary. The directory and tag parts don’t change.
Changing slug on an existing site changes the URL of every generated endpoint page. Add redirects from the previous URLs so existing links keep working.

Set a URL for one endpoint

Add x-mint.href to an operation to set its whole URL. The URL replaces the directory, tag, and slug.
Mintlify lowercases the URL and drops anything after the last . in the final segment, so /reference/v1.2 becomes /reference/v1. Don’t use dots in the final segment.

How titles are set

A generated page’s title is the operation’s summary. If there’s no summary, Mintlify builds the title from the URL slug. To set a different title or sidebar label, use x-mint.metadata:
Mintlify builds webhook page titles from the URL slug, so the title loses the summary’s capitalization and punctuation. For example, the summary New PR Opened gives the title New pr opened. Set x-mint.metadata.title to keep the summary’s formatting.

Localized API references

If you use the same specification in more than one language, every language links to the same pages unless each one has its own directory. To generate separate pages for each language, such as from a translated specification, set a different directory for each language. Translated summaries produce different slugs, so a page’s URL differs between languages unless you use operation IDs.

Keep URLs stable

To avoid breaking links when your specification changes:
  • Set slug to operationId, and keep operation IDs stable.
  • Keep tag names stable. Use x-group to change a group’s label without changing URLs.
  • Use x-mint.href for endpoints whose URL must never change.
  • When a URL does change, add a redirect from the old URL.