docs: OpenAPI Overlay support

api-playground/openapi-setup.mdx

@@ -187,6 +187,82 @@
 
 Use `x-default` on other schema properties in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition. Unlike security schemes, prefill for non-security-scheme properties only takes effect when you set [`api.examples.prefill`](/organize/settings-api) to `true` in your [`docs.json`](/api-playground/overview#example-configuration).
 
+## Apply OpenAPI Overlays
+
+Use [OpenAPI Overlays](https://spec.openapis.org/overlay/v1.1.0.html) to modify your OpenAPI specifications without editing the source files. Overlays are separate JSON or YAML documents that describe an ordered list of changes to apply to a specification before Mintlify validates it and generates your documentation. Overlays are useful when your specifications are generated by other tools and you need to adjust them for your public documentation, for example to rewrite paths, replace server URLs, or remove internal fields.
+
+Mintlify supports the full Overlay Specification 1.1.0, including the `update`, `remove`, and `copy` actions. The `target` of each action is a [RFC 9535 JSONPath](https://www.rfc-editor.org/rfc/rfc9535) expression.
+
+An overlay document requires an `overlay` version, an `info` object, and at least one action:
+
+```yaml publish-paths.overlay.yaml
+overlay: 1.1.0
+info:
+  title: Publish credit paths
+  version: 1.0.0
+extends: ../specs/credit.yaml
+actions:
+  - target: $.paths
+    update: { "/credit/accounts": {} }
+  - target: $.paths["/credit/accounts"]
+    copy: $.paths["/accounts"]
+  - target: $.paths["/accounts"]
+    remove: true
+  - target: $.servers[0].url
+    update: https://api.example.com/v3
+```
+
+This example renames the internal `/accounts` path to the public `/credit/accounts` path using the `update`, `copy`, and `remove` sequence, then replaces the server URL.
+
+### Reference overlays in docs.json
+
+Reference overlay files explicitly with the `overlays` property anywhere you reference an OpenAPI specification. Overlays apply in the order they are listed. Overlay files can be relative paths in your repository or `https` URLs.
+
+```json
+"navigation": {
+  "tabs": [
+    {
+      "tab": "API Reference",
+      "openapi": {
+        "source": "specs/credit.yaml",
+        "overlays": ["overlays/publish-paths.overlay.yaml"]
+      }
+    }
+  ]
+}
+```
+
+Arrays of specifications can mix plain strings and objects with overlays:
+
+```json
+"openapi": [
+  "specs/simple.yaml",
+  {
+    "source": "specs/credit.yaml",
+    "overlays": ["overlays/publish-paths.overlay.yaml"]
+  }
+]
+```
+
+### Auto-discover overlays with extends
+
+Any JSON or YAML file in your repository with a top-level `overlay` field is treated as an overlay document. If the overlay's `extends` field resolves to a specification in your repository (as a path relative to the overlay file) or matches the exact URL of a hosted specification, the overlay applies to that specification automatically, without any `docs.json` changes.
+
+Overlays without an `extends` field, or with an `extends` value that doesn't resolve to a known specification, are never applied.
+
+### Precedence and ordering
+
+- An explicit `overlays` list in `docs.json` takes precedence and suppresses auto-discovered overlays for that specification.
+- An empty list (`"overlays": []`) disables all overlays for that specification, including auto-discovered ones.
+- When multiple auto-discovered overlays extend the same specification, they apply in alphabetical order of their file paths.
+- Referencing the same specification with different `overlays` lists in different places is an error. Use the same list everywhere the specification is referenced.
+
+<Note>
+  Overlays apply before validation and page generation, so everything downstream sees the transformed document: the API playground, generated endpoint pages, and `openapi` frontmatter matching. Reference post-overlay paths in your MDX frontmatter. For example, if an overlay renames `/accounts` to `/credit/accounts`, use `openapi: "POST /credit/accounts"`.
+</Note>
+
+Run `mint validate` to check your specifications with overlays applied. Overlay errors report the overlay file, the failing action, and its target expression.
+
 ## Let visitors download your spec
 
 Opt into a "Download API spec" entry in the [page context menu](/organize/settings-structure#contextual) by adding `"download-spec"` to `contextual.options` in your `docs.json`:
@@ -200,7 +276,7 @@
 When enabled, clicking the option downloads your OpenAPI spec directly. Deployments with multiple specs receive them bundled as `api-specs.zip`. On deployments behind `auth` or `userAuth`, only authenticated readers can download the spec.
 
 <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
@@ -313,7 +389,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}
 {

organize/settings-api.mdx

@@ -15,7 +15,7 @@ Use the `api` field in `docs.json` to configure what API specifications generate
 Define all API-related settings under the `api` key.
 
 <ResponseField name="api.openapi" type="string or array or object">
-  OpenAPI specification files for generating API reference pages. Accepts a single path or URL, an array of paths and URLs, or an object specifying a source and directory.
+  OpenAPI specification files for generating API reference pages. Accepts a single path or URL, an array of paths, URLs, and objects, or an object specifying a source, directory, and overlays.
 
   <Expandable title="api.openapi object">
     <ResponseField name="source" type="string">
@@ -24,6 +24,9 @@ Define all API-related settings under the `api` key.
     <ResponseField name="directory" type="string">
       Directory to search for OpenAPI files. Do not include a leading slash.
     </ResponseField>
+    <ResponseField name="overlays" type="array of string">
+      Paths or URLs of [OpenAPI Overlay](/api-playground/openapi-setup#apply-openapi-overlays) documents to apply to the source specification, in order. An empty array disables all overlays for this specification, including auto-discovered ones.
+    </ResponseField>
   </Expandable>
 
   <CodeGroup>
@@ -47,6 +50,13 @@ Define all API-related settings under the `api` key.
   }
   ```
 
+  ```json Overlays
+  "openapi": {
+    "source": "openapi.json",
+    "overlays": ["overlays/publish-paths.overlay.yaml"]
+  }
+  ```
+
   </CodeGroup>
 </ResponseField>
 

organize/settings-reference.mdx

@@ -757,9 +757,9 @@
 
 #### `api.openapi`
 
-OpenAPI specification files.
+OpenAPI specification files. Objects accept `source` (string), `directory` (string), and `overlays` (array of string) for [OpenAPI Overlay](/api-playground/openapi-setup#apply-openapi-overlays) documents applied to the source specification in order.
 
-**Type:** string | array of string | object with `source` (string) and `directory` (string)
+**Type:** string | array of string or object | object with `source` (string), `directory` (string), and `overlays` (array of string)
 
 #### `api.asyncapi`