How URLs are built
A generated page’s URL has three parts:users with the summary Get user gets the URL /api-reference/users/get-user.
- Directory: The
directoryyou set on theopenapifield in yourdocs.json, in lowercase. Defaults toapi-reference. - Tag: The
nameof the operation’s tag. Labels fromx-group,x-displayName, or a 3.2 tagsummarydon’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}/postsbecomesget-users-posts.
{, }, (, ), ,, ., ', 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-hiddenthat produces the same URL as another endpoint.
directory.
Use operation IDs
Setslug 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
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.
Set a URL for one endpoint
Addx-mint.href to an operation to set its whole URL. The URL replaces the directory, tag, and slug.
. 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’ssummary. 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:
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 owndirectory. 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
slugtooperationId, and keep operation IDs stable. - Keep tag names stable. Use
x-groupto change a group’s label without changing URLs. - Use
x-mint.hreffor endpoints whose URL must never change. - When a URL does change, add a redirect from the old URL.