Document the openapi slug option for operationId-based page URLs

api-playground/openapi-setup.mdx

@@ -78,7 +78,7 @@
 - [The Mint CLI](https://www.npmjs.com/package/mint) to validate your OpenAPI document with the command: `mint validate`.
 
 <Note>
   Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1 and v3.2. For more information on the differences between v3.0 and v3.1, see [Migrating from OpenAPI 3.0 to 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) in the OpenAPI blog. OpenAPI 3.2 is backward compatible with 3.1, so no migration is needed: a 3.1 document works as 3.2 once you update its `openapi` version. See [Upgrading from OpenAPI 3.1 to 3.2](https://learn.openapis.org/upgrading/v3.1-to-v3.2.html) for what 3.2 adds.
 </Note>
 
 ### Specify the base URL for your API
@@ -260,15 +260,15 @@
 
 ## Transform your spec with overlays
 
 Use [OpenAPI Overlays](https://spec.openapis.org/overlay/v1.1.0.html) to modify an OpenAPI specification without editing its source file. Overlays are separate JSON or YAML files that describe an ordered list of changes, which is useful when a specification is generated by another tool or maintained by another team. Common uses include renaming paths, replacing server URLs, and removing internal endpoints.
 
 Overlays apply after a specification is parsed and before it is validated, so generated endpoint pages, navigation, `openapi` frontmatter references, and `mint validate` all use the transformed document. Overlay Specification versions 1.0 and 1.1 are supported.
 
 ### Create an overlay document
 
 An overlay document has an `overlay` version, an `info` object with a `title` and `version`, and an `actions` array. Each action selects nodes with a `target` [RFC 9535 JSONPath](https://www.rfc-editor.org/rfc/rfc9535) expression and applies one modifier:
 
 - `update`: Merges a value into each targeted node. Objects merge recursively, arrays append the value, and primitives are replaced.
 - `remove`: Deletes each targeted node when set to `true`.
 - `copy`: Copies the node selected by another JSONPath expression into each targeted node. Requires Overlay 1.1.
 
@@ -312,11 +312,11 @@
 
 ### Auto-discover overlays
 
 Any JSON or YAML file in your repository with a top-level `overlay` key is treated as an overlay document. If its `extends` field resolves to one of your specifications, the overlay applies to that specification automatically. Auto-discovered overlays apply in alphabetical order of their file paths. Overlays without an `extends` field never apply automatically.
 
 An explicit `overlays` list replaces auto-discovery for that specification. Set `"overlays": []` to disable all overlays for a specification, including auto-discovered ones.
 
 Explicit and auto-discovered overlays fail differently. If an explicit overlay fails to load or apply, the specification fails validation and the deployment reports a spec error. If an auto-discovered overlay fails, it is skipped and the specification publishes without it.
 
 ### Rename a path
 
@@ -357,7 +357,7 @@
 Enabling `download-spec` also publishes an [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) API catalog at `/.well-known/api-catalog`. The catalog links to each OpenAPI spec in your `docs.json` so AI agents can discover your API without crawling your docs. Without `download-spec`, `/.well-known/api-catalog` returns a 404. On projects behind `auth` or `userAuth`, only authenticated readers can access the catalog.
 
 <Warning>
   The downloaded OpenAPI spec is unfiltered and does not respect [authentication groups](/deploy/authentication-setup). Any authenticated reader who can open the contextual menu receives the full spec, including endpoints and schemas that would otherwise be hidden from their group. Do not enable `download-spec` on an authenticated site if your OpenAPI spec contains endpoints or fields you consider sensitive.
 </Warning>
 
 ## Customize your endpoint pages
@@ -443,7 +443,7 @@
 
 ### href
 
-Set the URL of the autogenerated endpoint page using `x-mint: href`. When `x-mint: href` is present, the generated API page uses the specified URL instead of the default autogenerated URL.
+Set the URL of the autogenerated endpoint page using `x-mint: href`. When `x-mint: href` is present, the generated API page uses the specified URL instead of the default autogenerated URL. To change only the last URL segment for every endpoint in a spec, set [`slug`](#derive-page-slugs-from-operation-ids) in your `docs.json` instead.
 
 ```json {6-8, 14-16}
 {
@@ -470,7 +470,7 @@
 
 ### Collapse playground fields
 
 Collapse object-type fields in the API playground by default using `x-mint: playground` with `expand: false` on any operation. Request sections like Authorization, Headers, Query, Path, and Body always stay expanded, and so does the top-level body object. Object fields nested within them start collapsed, so readers expand only the fields they want to interact with. If `expand` is not set, object fields are expanded by default.
 
 ```json {6-10}
 {
@@ -592,7 +592,7 @@
       tags: [beta, plants]
 ```
 
 In this example, the **List plants** endpoint appears under **Store** > **Plants** in the sidebar with a **Beta** pill. The page URL follows the `plants` tag, not `beta`, even though `beta` is listed first.
 
 When 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](#metadata). It takes precedence over badge tags.
 
@@ -671,6 +671,28 @@
   The `directory` field is optional and specifies where Mintlify stores generated API pages in your docs repo. If not specified, it defaults to the `api-reference` directory of your repo.
 </Note>
 
+#### Derive page slugs from operation IDs
+
+By default, the last segment of each generated page URL is the operation's `summary` in kebab case. For example, an operation with the summary `Get all actions` becomes `/api-reference/actions/get-all-actions`.
+
+Set `slug` to `operationId` to use the operation's `operationId` instead. Mintlify converts the ID to kebab case, so `getActions` becomes `get-actions` and `create_action` becomes `create-action`. Operations without an `operationId` fall back to the `summary`. The `directory` and the tag folder don't change.
+
+```json {5}
+{
+  "group": "Actions API",
+  "openapi": {
+    "source": "/path/to/openapi.json",
+    "slug": "operationId"
+  }
+}
+```
+
+`slug` accepts `summary` (default) or `operationId`. To set the entire path for a single endpoint, use [`x-mint: href`](#href) in your OpenAPI spec instead.
+
+<Warning>
+  Changing `slug` on an existing site changes the URL of every generated endpoint page. Add [redirects](/organize/settings-reference#redirects) from the previous URLs so existing links keep working.
+</Warning>
+
 ### Selective endpoints
 
 When you want more control over where endpoints appear in your documentation, you can reference specific endpoints in your navigation. This approach lets you generate pages for API endpoints alongside other content. You can also use this approach to mix endpoints from different OpenAPI specifications.

mint-instructions/api-docs.mdx

@@ -1,6 +1,6 @@
 ---
 title: "API reference docs"
 name: mintlify-api-docs
 description: "Adds an API reference from an OpenAPI spec (file or URL), configures the API playground, and covers AsyncAPI, GraphQL, and common OpenAPI errors. Use when setting up API documentation."
 when: "Setting up API documentation: OpenAPI, AsyncAPI, GraphQL, playground"
 related: false
@@ -14,24 +14,24 @@
 3. In the spec, set `servers` (base URL) and `components.securitySchemes` + `security`. The playground reads base URL and auth fields from the spec. With no `servers`, the playground falls back to simple mode. Scopes in an operation's `security` requirement appear on the endpoint page automatically.
 4. Add `openapi` to a navigation element (tab, group, or anchor) in `docs.json`:
    - No `pages`: Mintlify generates a page for every endpoint.
    - With `pages` listing `"METHOD /path"` entries: only those endpoints get pages. Once you list any endpoint from a spec, no others are added.
 5. Optional: tune the playground under `api` in `docs.json` (see Examples).
 6. Run the Verify commands.
 
 ## Rules
 
 - Methods in navigation entries and frontmatter must be uppercase and the path must exactly match the spec (`/users/{id}`, not `/user/{id}`). Trailing slashes are tolerated.
 - Child navigation elements inherit the parent's `openapi` unless they set their own.
 - `$ref` works only for internal references inside one document. No external refs.
 - Mintlify uploads every OpenAPI file in the repo, even unreferenced ones. With more than one spec, always include the file path in frontmatter (`openapi: "v1/openapi.json GET /users"`), or delete stale spec files. Otherwise the first alphabetical match wins.
 - Per-page `openapi` frontmatter must be one string for one endpoint. A list or non-string fails the deploy.
 - Do not have both an MDX file and a navigation entry for the same operation (for example `get-users.mdx` and `"GET /users"`).
 - Navigation entries that do not match an operation are treated as file paths.
 - Hide an endpoint from navigation with `x-hidden: true` on the operation (page still exists); remove it entirely with `x-excluded: true`.
 - Customize generated pages from the spec with `x-mint` on an operation: `metadata` (title, sidebarTitle, description, playground, groups...), `content` (MDX before the reference), `href` (custom URL).
-- Generated pages land in `api-reference/` unless you set `directory` in the object form of `openapi`.
+- Generated pages land in `api-reference/` unless you set `directory` in the object form of `openapi`. The last URL segment comes from the operation `summary`; set `slug: "operationId"` to use the kebab-cased `operationId` instead (falls back to `summary`).
 - Localhost spec URLs need `mint dev --local-schema` / `mint validate --local-schema`. Production requires HTTPS.
 - Never invent a validation command. `mint openapi-check` is deprecated; use `mint validate`.
 
 ## Examples
 
@@ -45,13 +45,13 @@
 }
 ```
 
-Multiple specs, one per group, with a custom directory:
+Multiple specs, one per group, with a custom directory and page slugs derived from `operationId` instead of `summary`:
 
 ```json
 "groups": [
   {
     "group": "Users API",
-    "openapi": { "source": "openapi/users.json", "directory": "users-api-reference" }
+    "openapi": { "source": "openapi/users.json", "directory": "users-api-reference", "slug": "operationId" }
   },
   {
     "group": "Admin API",
@@ -72,7 +72,7 @@
 
 Endpoint from a specific spec with no default set: `"openapi/v2.json GET /orders"` in any `pages` array.
 
 Per-page MDX bound to one operation (page gets the generated params and responses):
 
 ```mdx
 ---
@@ -100,13 +100,13 @@
 ```
 
 - `playground.display`: `interactive` (default), `simple`, `none`, `auth` (only signed-in readers; requires docs authentication).
 - `playground.proxy` defaults to `true`. Set `false` to send requests from the browser (your API then needs CORS); `credentials: true` only works with `proxy: false`.
 - `examples.defaults`: `required` or `all` (default). `prefill` defaults to `false`.
 - `api.optional`: `collapsed` (default), `expanded`, `static`.
 
 AsyncAPI (WebSocket channels, AsyncAPI 3.0): use `"asyncapi": "asyncapi.json"` on a navigation element, same string/array/`{source, directory}` shapes. Single channel page: `asyncapi: "asyncapi.json channelName"` frontmatter.
 
 GraphQL (SDL file or HTTPS URL): `"graphql": "schema.graphql"` on a tab or group only. Curate with `"QUERY products"`, `"MUTATION cart.createCart"`, `"TYPE Cart"` in a group's `pages` (uppercase kinds).
 
 Manual MDX API pages (no spec): set `api.mdx.server` and `api.mdx.auth` (`method`: `bearer`, `basic`, `key`, `cobo`; `name` for key), then use `api: "POST /v1/users"` frontmatter plus `<ParamField>`, `<ResponseField>`, `<RequestExample>`, `<ResponseExample>`.
 
@@ -117,7 +117,7 @@
 - `Failed to fetch OpenAPI file for anchor or tab`: the build could not download the spec URL (private host, auth, bad TLS, 5xx). Commit the spec to the repo or serve it from a stable public HTTPS URL.
 - Nav entries not generating pages: the element (or a parent) lacks `openapi`, or the spec has errors.
 - Some operations missing: `x-hidden`, invalid operations, or you listed specific endpoints so only those appear.
 - Playground requests fail behind a reverse proxy: allow `POST` to `/_mintlify/api/request`, or set `api.playground.proxy: false` and enable CORS.
 
 ## Verify
 
@@ -136,4 +136,4 @@
 - https://www.mintlify.com/docs/api-playground/openapi-setup
 - https://www.mintlify.com/docs/organize/settings-api
 - https://www.mintlify.com/docs/api-playground/troubleshooting
 - https://www.mintlify.com/docs/api-playground/mdx-setup