mintlify · mintlify · Jan 20, 2026 · Jan 20, 2026 · Jan 20, 2026 · Jan 20, 2026
diff --git a/docs.json b/docs.json
@@ -73,6 +73,7 @@
                       "editor/pages",
                       "editor/media",
                       "editor/navigation",
+                      "editor/api-specs",
                       "editor/configurations",
                       "editor/live-preview",
                       "editor/collaborate",
@@ -421,6 +422,7 @@
                       "fr/editor/pages",
                       "fr/editor/media",
                       "fr/editor/navigation",
+                      "fr/editor/api-specs",
                       "fr/editor/configurations",
                       "fr/editor/live-preview",
                       "fr/editor/collaborate",
@@ -767,6 +769,7 @@
                       "es/editor/pages",
                       "es/editor/media",
                       "es/editor/navigation",
+                      "es/editor/api-specs",
                       "es/editor/configurations",
                       "es/editor/live-preview",
                       "es/editor/collaborate",
@@ -1113,6 +1116,7 @@
                       "zh/editor/pages",
                       "zh/editor/media",
                       "zh/editor/navigation",
+                      "zh/editor/api-specs",
                       "zh/editor/configurations",
                       "zh/editor/live-preview",
                       "zh/editor/collaborate",

diff --git a/editor/api-specs.mdx b/editor/api-specs.mdx
@@ -0,0 +1,143 @@
+---
+title: "API specifications"
+description: "Import, organize, and manage OpenAPI and AsyncAPI specification files in the web editor."
+keywords: ["editor", "api", "openapi", "asyncapi", "specifications"]
+---
+
+Manage your API specification files directly in the web editor. Import OpenAPI and AsyncAPI specifications, organize them in folders, and link them to your navigation.
+
+<Frame>
+  <img
+    src="/images/editor/api-specs-light.png"
+    alt="API Specs view in the editor sidebar in light mode."
+    className="block dark:hidden"
+  />
+  <img
+    src="/images/editor/api-specs-dark.png"
+    alt="API Specs view in the editor sidebar in dark mode."
+    className="hidden dark:block"
+  />
+</Frame>
+
+## Access API specs view
+
+Open the API Specs view from the editor sidebar:
+
+1. Click **Configurations** in the left sidebar
+2. Select **API Specifications** from the configurations menu
+
+The API Specs view displays all OpenAPI and AsyncAPI specification files in your documentation repository.
+
+## Import specification files
+
+Add OpenAPI or AsyncAPI specification files to your documentation:
+
+1. In the API Specs view, click the **Add** button
+2. Select **Import specification**
+3. Choose one or more JSON or YAML files from your computer
+4. The editor validates each file and imports valid OpenAPI or AsyncAPI specifications
+
+The editor automatically detects the specification type (OpenAPI or AsyncAPI) and displays appropriate icons and metadata.
+
+### Supported formats
+
+- **OpenAPI**: JSON or YAML files with `openapi` field (versions 3.0+)
+- **AsyncAPI**: JSON or YAML files with `asyncapi` field (versions 2.0+)
+
+## Organize specs in folders
+
+Create folders to organize your API specifications:
+
+1. Click the **Add** button in the API Specs view
+2. Select **New folder**
+3. Enter a folder name
+4. Press Enter to create the folder
+
+### Move specs with drag-and-drop
+
+Reorganize your specifications by dragging them:
+
+- Drag a file or folder to reorder it
+- Drop a file onto a folder to move it inside
+- Drop a file in the root area at the bottom to move it to the top level
+
+## Configure navigation items
+
+Link API specifications to your navigation items using the configure sheet:
+
+1. Select a page or navigation item
+2. Click the settings icon to open the configure sheet
+3. Scroll to the **OpenAPI** or **AsyncAPI** field
+4. Choose between **File** or **URL** mode:
+   - **File**: Select a specification file from your repository
+   - **URL**: Enter a URL to an external specification file
+
+### File mode
+
+Select a specification file from your repository:
+
+1. Click the **File** button
+2. Choose a file from the dropdown menu
+3. Click the arrow icon to preview the specification in the API Specs view
+
+### URL mode
+
+Link to an external specification file:
+
+1. Click the **URL** button
+2. Enter the full URL to your specification file (e.g., `https://api.example.com/openapi.json`)
+3. The URL must start with `http://` or `https://`
+
+<Note>
+You can only set either OpenAPI or AsyncAPI for a navigation item, not both. The fields disable each other when one is set.
+</Note>
+
+## Preview API spec files
+
+View the contents of your specification files:
+
+1. Click a specification file in the API Specs view
+2. The file opens in read-only preview mode
+3. Review the JSON or YAML content
+
+The preview displays syntax highlighting and formatting for easy reading.
+
+## Manage specs
+
+Configure and manage individual specification files:
+
+1. Click the settings icon on a file or folder
+2. The configure sheet displays metadata:
+   - **Spec type**: OpenAPI or AsyncAPI with version number
+   - **Tags**: Number of tags defined in the specification
+   - **Paths/Channels**: Number of API endpoints or channels
+   - **File size**: Size of the specification file
+   - **File path**: Full path in your repository
+
+### Rename files and folders
+
+Change the name of a file or folder:
+
+1. Open the configure sheet for the item
+2. Edit the name in the **File name** or **Folder name** field
+3. Click **Save changes**
+
+### Delete files and folders
+
+Remove specification files or folders:
+
+1. Open the configure sheet for the item
+2. Click **Delete file** or **Delete folder** at the bottom
+3. Confirm the deletion
+
+Deleting a folder removes all files and subfolders inside it.
+
+## Copy file paths
+
+Copy the path of a specification file to use in configuration:
+
+1. Right-click a file in the API Specs view
+2. Select **Copy path** from the menu
+3. The file path is copied to your clipboard
+
+Use the copied path when configuring OpenAPI or AsyncAPI fields in your navigation items.
diff --git a/editor/configurations.mdx b/editor/configurations.mdx
@@ -24,8 +24,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
@@ -35,10 +35,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.
@@ -47,7 +47,7 @@

 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.

@@ -57,8 +57,8 @@

 Add navigation elements to the top of your site.

 - **Navbar button**: Add a primary call-to-action button in your header. Set the button type, label, and destination URL.
 - **Navbar links**: Add additional navigation links in your header. Each link includes text and a URL.

 ## Configure footer

@@ -74,7 +74,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.

@@ -82,8 +82,21 @@

 Customize the search experience.
 
 - **Search placeholder**: The text that appears in the search box before users type. Default is "Search or ask...".
 
+## Configure API specifications
+
+Link OpenAPI and AsyncAPI specification files to navigation items.
+
+- **OpenAPI**: Select a specification file from your repository or enter a URL to an external OpenAPI file. Choose between file and URL modes using the toggle buttons.
+- **AsyncAPI**: Select a specification file from your repository or enter a URL to an external AsyncAPI file. Choose between file and URL modes using the toggle buttons.
+
+<Note>
+You can only set either OpenAPI or AsyncAPI for a navigation item, not both. Setting one disables the other field.
+</Note>
+
+When using file mode, click the arrow icon next to a selected file to preview it in the API Specs view. Use the trash icon to clear the field.
+
 ## Add analytics and integrations
 
 Connect analytics and third-party tools to your documentation.
@@ -91,13 +104,13 @@
 Track visitor behavior with:
 - **Amplitude, Mixpanel, Heap**: Product analytics platforms
 - **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
diff --git a/editor/index.mdx b/editor/index.mdx
@@ -17,7 +17,7 @@
  alt="Decorative image in dark mode"
 />

 Create and edit documentation directly in your browser with the web editor. Work on content visually to see real-time previews or in Markdown; manage your site structure with drag-and-drop components; and publish changes using Git workflows.

 ## Key features

@@ -42,6 +42,10 @@
   Upload and use images in your documentation.
 </Card>
 
+<Card title="Manage API specs" icon="file-json" horizontal href="/editor/api-specs">
+  Import and organize OpenAPI and AsyncAPI specifications.
+</Card>
+
 ## Publish and collaborate
 
 <Card title="Publish changes" icon="rocket" horizontal href="/editor/publish">