mintlify · ethanpalm · Jan 5, 2026 · Jan 5, 2026 · Jan 5, 2026 · Jan 5, 2026
diff --git a/api-playground/asyncapi-setup.mdx b/api-playground/asyncapi-setup.mdx
@@ -53,8 +53,26 @@
 }
 ```
 
+```json Multiple files
+"navigation": {
+  "tabs": [
+    {
+      "tab": "API Reference",
+      "asyncapi": [
+        "/path/to/events.json",
+        "/path/to/webhooks.json"
+      ]
+    }
+  ]
+}
+```
+
 </CodeGroup>
 
+<Note>
+  When you specify multiple AsyncAPI files, each file generates its own set of channel pages.
+</Note>
+
 ### Examples with groups
 
 ```json
@@ -77,7 +95,7 @@
 ```

 <Note>
  The `directory` field is optional. If not specified, the files will be placed in the **api-reference** folder of the docs repo.
 </Note>

 ## Channel page

diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
@@ -8,17 +8,46 @@
 
 ## Add an OpenAPI specification file
 
-To document your endpoints with OpenAPI, you need a valid OpenAPI specification in either JSON or YAML format that follows the [OpenAPI specification 3.0+](https://swagger.io/specification/).
+To document your endpoints with OpenAPI, you need one or more valid OpenAPI specifications in either JSON or YAML format that follow the [OpenAPI specification 3.0+](https://swagger.io/specification/).
 
-You can reference multiple OpenAPI specifications to create pages for your API. Either organize sections for each specification in your navigation or reference specific endpoints from different specifications.
+Add OpenAPI specifications to your documentation repository or host them online where you can access the specifications by URL.
+
+Reference any number of OpenAPI specifications in the navigation element of your `docs.json` to create pages for your API endpoints. Each specification file generates its own set of endpoints.
+
+<CodeGroup>
+  ```json Single specification
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "API Reference",
+        "openapi": "openapi.json"
+      }
+    ]
+  }
+  ```
+
+  ```json Multiple specifications
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "API Reference",
+        "openapi": [
+          "openapi/v1.json",
+          "openapi/v2.json"
+        ]
+      }
+    ]
+  }
+  ```
+</CodeGroup>
 
 <Note>
   Mintlify supports `$ref` for **internal references only** within a single OpenAPI document. External references are not supported.
 </Note>

 ### Describe your API

 We recommend the following resources to learn about and construct your OpenAPI specification.

 - [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/v3_0/basic-structure/) to learn the OpenAPI syntax.
 - [The OpenAPI specification Markdown sources](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) to reference details of the latest OpenAPI specification.
@@ -92,7 +121,7 @@
 Common authentication types include:

 - [API Keys](https://swagger.io/docs/specification/authentication/api-keys/): For header, query, or cookie-based keys.
 - [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/): For JWT or OAuth tokens.
 - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/): For username and password.

 If different endpoints within your API require different methods of authentication, you can [override the `security` field](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for a given operation.
@@ -101,7 +130,7 @@

 ## Customize your endpoint pages

 Customize your endpoint pages by adding the `x-mint` extension to your OpenAPI specification. The `x-mint` extension provides additional control over how your API documentation is generated and displayed.

 ### Metadata

@@ -156,7 +185,7 @@
 }
 ```

 ### Href

 Change the URL of the endpoint page in your docs using `x-mint: href`. When `x-mint: href` is present, the navigation entry links directly to the specified URL instead of generating an API page.

@@ -187,11 +216,11 @@

 Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.

 The `openapi` field accepts either a file path in your docs repo or a URL to a hosted OpenAPI document.

 Generated endpoint pages have these default metadata values:

 - `title`: The operation's `summary` field, if present. If there is no `summary`, the title is generated from the HTTP method and endpoint.
 - `description`: The operation's `description` field, if present.
 - `version`: The `version` value from the parent anchor or tab, if present.
 - `deprecated`: The operation's `deprecated` field. If `true`, a deprecated label appears next to the endpoint title in the side navigation and on the endpoint page.
@@ -207,7 +236,7 @@

 ### Dedicated API sections

 Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. All endpoints in the specification are included.

 ```json {5}
 "navigation": {
@@ -249,7 +278,7 @@
 ```

 <Note>
  The `directory` field is optional and specifies where generated API pages are stored in your docs repo. If not specified, defaults to the `api-reference` directory of your repo.
 </Note>

 ### Selective endpoints
@@ -288,7 +317,7 @@

 #### OpenAPI spec inheritance

 OpenAPI specifications are inherited down the navigation hierarchy. Child navigation elements inherit their parent's OpenAPI specification unless they define their own.

 ```json {3, 7-8, 11, 13-14}
 {
@@ -313,7 +342,7 @@

 #### Individual endpoints

 Reference specific endpoints without setting a default OpenAPI specification by including the file path. You can reference endpoints from multiple OpenAPI specifications in the same documentation section.

 ```json {5-6}
 "navigation": {
@@ -365,7 +394,7 @@

 </CodeGroup>

 The method and path must exactly match your OpenAPI spec. If you have multiple OpenAPI specifications, include the file path in your reference. External OpenAPI URLs can be referenced in `docs.json`.

 #### Autogenerate endpoint pages

@@ -376,7 +405,7 @@
 ```

 <Tip>
  Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files will populate in the working directory.
 </Tip>

 ### Document data models
@@ -419,7 +448,7 @@

 ## Webhooks

 Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. Webhooks are supported in OpenAPI 3.1+ documents.

 Add a `webhooks` field to your OpenAPI document alongside the `paths` field.


diff --git a/editor/configurations.mdx b/editor/configurations.mdx
@@ -16,8 +16,8 @@
 Set your site's identity and how it appears to visitors.

 - **Docs title**: The name of your documentation. Appears in browser tabs and search results.
 - **Description**: Brief summary of your documentation. Used for SEO and site metadata.
 - **Favicon**: Small icon that appears in browser tabs. Upload ICO, PNG, GIF, or JPG files.
 - **Theme**: Choose a [theme](/customize/themes) for your documentation's overall appearance.

 ## Customize colors and appearance
@@ -27,10 +27,10 @@
 - **Primary color**: The main accent color used throughout your site for links, buttons, and highlights.
 - **Light mode color**: Accent color variation for light mode. How themes apply this varies by theme.
 - **Dark mode color**: Accent color variation for dark mode. How themes apply this varies by theme.
 - **Logo**: Your brand logo. Upload SVG, PNG, or JPG files. You can set different logos for light and dark modes.
 - **Logo link**: Where users go when they click your logo. Typically your homepage or marketing site.
 - **Background colors**: Set custom background colors for light and dark modes separately.
 - **Background image**: Add a background image to your site. Upload PNG, GIF, or JPG files.
 - **Background decoration**: Apply visual styles to your background image.
 - **Theme toggle**: Show or hide the light/dark mode switcher for users.
 - **Default theme**: Set whether your site loads in light or dark mode by default.
@@ -39,11 +39,11 @@

 Replace default fonts with your brand's typography.

 - **Default font**: The base font family and weight for all text. Provide a source URL and format (WOFF or WOFF2).
 - **Heading font**: Font family and weight specifically for headings (h1, h2, etc.). Set separately from body text.
 - **Body font**: Font family and weight for body text and paragraphs.

 For each font, specify the family name, weight, source URL (like Google Fonts), and format.

 ## Configure header

@@ -56,7 +56,7 @@

 Add links and social media handles to your site footer.

 - **Social links**: Add your profiles on platforms like GitHub, X (Twitter), LinkedIn, Discord, YouTube, Slack, and more.
 - **Footer columns**: Organize footer links into columns with custom headings and link groups.

 ## Enhance content
@@ -66,7 +66,7 @@
 - **Thumbnail background**: Set a custom background image for page thumbnails and social previews.
 - **Thumbnail appearance**: Control how thumbnails display.
 - **Thumbnail font**: Set a custom font for text in thumbnails.
 - **Page eyebrow**: Add small labels above page titles.
 - **Code block theme**: Choose the syntax highlighting theme for code blocks.
 - **LaTeX support**: Enable mathematical notation rendering with LaTeX.

@@ -74,7 +74,7 @@

 Customize the search experience.

 - **Search placeholder**: The text that appears in the search box before users type. Default is "Search or ask...".

 ## Add analytics and integrations

@@ -85,20 +85,20 @@
 - **Google Analytics, Google Tag Manager**: Web analytics
 - **PostHog, Plausible, Fathom**: Privacy-focused analytics
 - **Segment, Hightouch**: Customer data platforms
 - **Hotjar, LogRocket**: Session replay and heatmaps
 - **Microsoft Clarity**: User behavior analytics
 - **Intercom**: Customer messaging
 - **Clearbit, Koala**: Visitor identification

 Additional integrations:
 - **Telemetry**: Enable or disable usage telemetry
 - **Cookies**: Set custom cookie key and value pairs

 ## Configure API documentation
 
 Set up interactive API references.
 
-- **OpenAPI specs**: Link to your OpenAPI/Swagger specification files.
+- **OpenAPI specs**: Link to your OpenAPI specification files.
 - **AsyncAPI specs**: Link to your AsyncAPI specification files for asynchronous APIs.
 - **Playground display**: Control how the API playground appears.
 - **Proxy server**: Configure a proxy server for API requests from the playground.
diff --git a/organize/settings.mdx b/organize/settings.mdx
@@ -50,7 +50,7 @@
 </ResponseField>

 <ResponseField name="colors" type="object" required>
  The colors used in your documentation. Colors are applied differently across themes. If you only provide a primary color, it will be used for all color elements.

  <Expandable title="Colors">
    <ResponseField name="primary" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$" required>
@@ -115,7 +115,7 @@
      Background image for your thumbnails. Can be a relative path or absolute URL.
    </ResponseField>
    <ResponseField name="fonts" type="object">
      Font configuration for thumbnails. Only Google Fonts family names are supported.

      <Expandable title="Fonts">
        <ResponseField name="family" type="string" required>
@@ -550,7 +550,7 @@

  <Expandable title="Interaction">
    <ResponseField name="drilldown" type="boolean">
      Control automatic navigation behavior when selecting navigation groups. Set to `true` to force navigation to the first page when a navigation group is expanded. Set to `false` to prevent navigation and only expand or collapse the group. Leave unset to use the theme's default behavior.
    </ResponseField>
  </Expandable>
 </ResponseField>
@@ -560,7 +560,7 @@

  <Expandable title="Metadata">
    <ResponseField name="timestamp" type="boolean">
      Enable the last modified date on all pages. When enabled, all pages will display the date the content was last modified. Defaults to `false`.
    </ResponseField>
  </Expandable>
 </ResponseField>
@@ -613,7 +613,7 @@

  <Expandable title="Banner">
    <ResponseField name="content" type="string" required>
      The text content displayed in the banner. Supports basic MDX formatting including links, bold, and italic text. Custom components are not supported. For example:

      ```json
      {
@@ -638,7 +638,7 @@
      Destination path to redirect to. Example: `/new-page`
    </ResponseField>
    <ResponseField name="permanent" type="boolean">
      Whether to use a permanent redirect (301). Defaults to `true`.
    </ResponseField>
  </Expandable>
 </ResponseField>
@@ -694,16 +694,16 @@
  </Expandable>
 </ResponseField>

 ### API Configurations

 <ResponseField name="api" type="object">
   API documentation and interactive playground settings.
 
-  <Expandable title="Api">
+  <Expandable title="api">
     <ResponseField name="openapi" type="string or array or object">
       OpenAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.
 
-      <Expandable title="Openapi">
+      <Expandable title="openapi">
         <ResponseField name="source" type="string">
           URL or path to your OpenAPI specification file.
 
@@ -715,11 +715,32 @@
           Do not include a leading slash.
         </ResponseField>
       </Expandable>
+
+      <CodeGroup>
+      ```json Single file
+      "openapi": "openapi.json"
+      ```
+
+      ```json Multiple files
+      "openapi": [
+        "openapi/v1.json",
+        "openapi/v2.json",
+        "https://api.example.com/openapi.yaml"
+      ]
+      ```
+
+      ```json Directory
+      "openapi": {
+        "source": "openapi.json",
+        "directory": "api-docs"
+      }
+      ```
+      </CodeGroup>
     </ResponseField>
     <ResponseField name="asyncapi" type="string or array or object">
       AsyncAPI specification files for generating API documentation. Can be a single URL/path or an array of URLs/paths.
 
-      <Expandable title="Asyncapi">
+      <Expandable title="asyncapi">
         <ResponseField name="source" type="string">
           URL or path to your AsyncAPI specification file.
 
@@ -731,6 +752,28 @@
           Do not include a leading slash.
         </ResponseField>
       </Expandable>
+
+      <CodeGroup>
+      ```json Single file
+      "asyncapi": "asyncapi.json"
+      ```
+
+      ```json Multiple files
+      "asyncapi": [
+        "asyncapi/events.yaml",
+        "asyncapi/webhooks.yaml",
+        "https://api.example.com/asyncapi.json"
+      ]
+      ```
+
+      ```json Directory
+      "asyncapi": {
+        "source": "asyncapi.json",
+        "directory": "websockets"
+      }
+      ```
+      </CodeGroup>
+
     </ResponseField>
     <ResponseField name="params" type="object">
       Display settings for API parameters.
@@ -804,10 +847,10 @@
  </Expandable>
 </ResponseField>

 ### SEO and search

 <ResponseField name="seo" type="object">
  SEO indexing configurations.

  <Expandable title="Seo">
    <ResponseField name="metatags" type="object">