diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index 51499c89a..57fc94a56 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -443,7 +443,7 @@ Add content before the auto-generated API documentation using `x-mint: content`.
 
 ### 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}
 {
@@ -671,6 +671,28 @@ To organize multiple OpenAPI specifications in separate sections of your documen
   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.
diff --git a/mint-instructions/api-docs.mdx b/mint-instructions/api-docs.mdx
index 9a042b394..5780cc392 100644
--- a/mint-instructions/api-docs.mdx
+++ b/mint-instructions/api-docs.mdx
@@ -29,7 +29,7 @@ Use this topic when a user wants API reference pages, an interactive playground,
 - 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`.
 
@@ -45,13 +45,13 @@ Whole spec as a tab (path or URL):
 }
 ```
 
-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",