# Table of Contents - [Introduction - Mintlify](#introduction-mintlify) - [Introduction - Mintlify](#introduction-mintlify) - [Generate Assistant Message - Mintlify](#generate-assistant-message-mintlify) - [Get Update Status - Mintlify](#get-update-status-mintlify) - [Trigger Update - Mintlify](#trigger-update-mintlify) - [Editor permissions - Mintlify](#editor-permissions-mintlify) - [Product updates - Mintlify](#product-updates-mintlify) - [Roles - Mintlify](#roles-mintlify) - [AWS Route 53 and Cloudfront - Mintlify](#aws-route-53-and-cloudfront-mintlify) - [Single sign-on (SSO) - Mintlify](#single-sign-on-sso-mintlify) - [Playground - Mintlify](#playground-mintlify) - [AsyncAPI setup - Mintlify](#asyncapi-setup-mintlify) - [Vercel - Mintlify](#vercel-mintlify) - [Authentication - Mintlify](#authentication-mintlify) - [Adding SDK examples - Mintlify](#adding-sdk-examples-mintlify) - [Playground - Mintlify](#playground-mintlify) - [Cloudflare - Mintlify](#cloudflare-mintlify) - [Managing page visibility - Mintlify](#managing-page-visibility-mintlify) - [Multiple responses - Mintlify](#multiple-responses-mintlify) - [Complex data types - Mintlify](#complex-data-types-mintlify) - [Troubleshooting - Mintlify](#troubleshooting-mintlify) - [Partial authentication setup - Mintlify](#partial-authentication-setup-mintlify) - [OpenAPI setup - Mintlify](#openapi-setup-mintlify) - [Overview - Mintlify](#overview-mintlify) - [MDX setup - Mintlify](#mdx-setup-mintlify) - [Personalization setup - Mintlify](#personalization-setup-mintlify) - [Sending data - Mintlify](#sending-data-mintlify) - [Cards - Mintlify](#cards-mintlify) - [Code groups - Mintlify](#code-groups-mintlify) - [Callouts - Mintlify](#callouts-mintlify) - [Columns - Mintlify](#columns-mintlify) - [Panel - Mintlify](#panel-mintlify) - [Expandables - Mintlify](#expandables-mintlify) - [Frames - Mintlify](#frames-mintlify) - [Authentication setup - Mintlify](#authentication-setup-mintlify) - [Contact support - Mintlify](#contact-support-mintlify) - [Mermaid - Mintlify](#mermaid-mintlify) - [Tooltips - Mintlify](#tooltips-mintlify) - [AI assistant - Mintlify](#ai-assistant-mintlify) - [Tabs - Mintlify](#tabs-mintlify) - [Examples - Mintlify](#examples-mintlify) - [Introduction - Mintlify](#introduction-mintlify) - [AI ingestion - Mintlify](#ai-ingestion-mintlify) - [Update - Mintlify](#update-mintlify) - [Icons - Mintlify](#icons-mintlify) - [Accordions - Mintlify](#accordions-mintlify) - [Claude Code - Mintlify](#claude-code-mintlify) - [Steps - Mintlify](#steps-mintlify) - [Windsurf - Mintlify](#windsurf-mintlify) - [Migrations - Mintlify](#migrations-mintlify) - [Deployments - Mintlify](#deployments-mintlify) - [Monorepo setup - Mintlify](#monorepo-setup-mintlify) - [CLI installation - Mintlify](#cli-installation-mintlify) - [Changelogs - Mintlify](#changelogs-mintlify) - [Osano - Mintlify](#osano-mintlify) - [Privacy integrations - Mintlify](#privacy-integrations-mintlify) - [Stainless - Mintlify](#stainless-mintlify) - [Hidden pages - Mintlify](#hidden-pages-mintlify) - [Speakeasy - Mintlify](#speakeasy-mintlify) - [Preview deployments - Mintlify](#preview-deployments-mintlify) - [Analytics - Mintlify](#analytics-mintlify) - [Fields - Mintlify](#fields-mintlify) - [GitLab - Mintlify](#gitlab-mintlify) - [Intercom - Mintlify](#intercom-mintlify) - [GitHub - Mintlify](#github-mintlify) - [Web editor - Mintlify](#web-editor-mintlify) - [Front - Mintlify](#front-mintlify) - [Support integrations - Mintlify](#support-integrations-mintlify) - [Custom domain - Mintlify](#custom-domain-mintlify) - [Images and embeds - Mintlify](#images-and-embeds-mintlify) - [Redirects and broken links - Mintlify](#redirects-and-broken-links-mintlify) - [Custom scripts - Mintlify](#custom-scripts-mintlify) - [Model Context Protocol - Mintlify](#model-context-protocol-mintlify) - [Amplitude - Mintlify](#amplitude-mintlify) - [Reusable snippets - Mintlify](#reusable-snippets-mintlify) - [Fathom - Mintlify](#fathom-mintlify) - [Headers and text - Mintlify](#headers-and-text-mintlify) - [Google Tag Manager - Mintlify](#google-tag-manager-mintlify) - [Clearbit - Mintlify](#clearbit-mintlify) - [Code - Mintlify](#code-mintlify) - [Mixpanel - Mintlify](#mixpanel-mintlify) - [Koala - Mintlify](#koala-mintlify) - [Navigation - Mintlify](#navigation-mintlify) - [Pages - Mintlify](#pages-mintlify) - [Heap - Mintlify](#heap-mintlify) - [PostHog - Mintlify](#posthog-mintlify) - [Segment - Mintlify](#segment-mintlify) - [Lists and tables - Mintlify](#lists-and-tables-mintlify) - [LogRocket - Mintlify](#logrocket-mintlify) - [Google Analytics 4 - Mintlify](#google-analytics-4-mintlify) - [CI checks - Mintlify](#ci-checks-mintlify) - [Plausible - Mintlify](#plausible-mintlify) - [HotJar - Mintlify](#hotjar-mintlify) - [Pirsch - Mintlify](#pirsch-mintlify) - [SEO - Mintlify](#seo-mintlify) - [Cursor - Mintlify](#cursor-mintlify) - [Themes - Mintlify](#themes-mintlify) - [Quickstart - Mintlify](#quickstart-mintlify) - [React - Mintlify](#react-mintlify) - [Analytics integrations - Mintlify](#analytics-integrations-mintlify) - [Global settings - Mintlify](#global-settings-mintlify) - [Unknown](#unknown) - [](#-cdata-v1-0-1-released-) - [Unknown](#unknown) - [Hidden page example - Mintlify](#hidden-page-example-mintlify) --- # Introduction - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Getting started Introduction Documentation ================= Meet the next generation of documentation. AI-native, beautiful out-of-the-box, and built for developers. [### Quickstart\ \ Deploy your first docs site in minutes with our step-by-step guide](https://mintlify.com/docs/quickstart) [### CLI installation\ \ Install the CLI to preview and develop your docs locally](https://mintlify.com/docs/installation) [### Web editor\ \ Make quick updates and manage content with our browser-based editor](https://mintlify.com/docs/editor) [### Components\ \ Build rich, interactive documentation with our ready-to-use components](https://mintlify.com/docs/components) Assistant Responses are generated using AI and may contain mistakes. --- # Introduction - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation API Reference Introduction [​](https://mintlify.com/docs/api-reference/introduction#authentication) Authentication ------------------------------------------------------------------------------------------ You can generate an API key through [the dashboard](https://dashboard.mintlify.com/settings/organization/api-keys) . The API key is associated with an entire organization and can be used across multiple deployments. [​](https://mintlify.com/docs/api-reference/introduction#admin-api-key) Admin API key ---------------------------------------------------------------------------------------- The Admin API key is used for the majority of the API. It is used to trigger updates via the [Update endpoint](https://mintlify.com/docs/api-reference/update/trigger) . [​](https://mintlify.com/docs/api-reference/introduction#assistant-api-key) Assistant API key ------------------------------------------------------------------------------------------------ The assistant API allows you to embed the AI assistant, trained on your docs and continually kept up to date, into any application of your choosing. Responses include citations so you can point your users to the right destinations for more information. The assistant API **token** is a public token that can be referenced in your frontend code. The API **key** is a server-side token that should be kept secret. Calls using the assistant API token can incur costs: either using your AI chat credits or incurring overages. Was this page helpful? YesNo [Trigger UpdateTrigger an update after updating your OpenAPI document by calling this endpoint in a CI check\ \ Next](https://mintlify.com/docs/api-reference/update/trigger) On this page * [Authentication](https://mintlify.com/docs/api-reference/introduction#authentication) * [Admin API key](https://mintlify.com/docs/api-reference/introduction#admin-api-key) * [Assistant API key](https://mintlify.com/docs/api-reference/introduction#assistant-api-key) Assistant Responses are generated using AI and may contain mistakes. --- # Generate Assistant Message - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Assistant Generate Assistant Message POST / assistant / {domain} / message Try it Generate Assistant Message cURL Copy Ask AI curl --request POST \ --url https://api-dsc.mintlify.com/v1/assistant/{domain}/message \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "fp": "", "threadId": null, "messages": [\ {\ "id": "foobar",\ "role": "user",\ "content": "how do i get started",\ "parts": [\ {\ "type": "text",\ "text": "How do I get started"\ }\ ]\ }\ ], "retrievalPageSize": 5, "filter": null }' 200 Copy Ask AI {} [​](https://mintlify.com/docs/api-reference/chat/create-assistant-message#rate-limits) Rate limits ----------------------------------------------------------------------------------------------------- The assistant API has the following limits: * 10,000 uses per key per month * 10,000 requests per Mintlify organization per hour * 10,000 requests per IP per day #### Authorizations [​](https://mintlify.com/docs/api-reference/chat/create-assistant-message#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://mintlify.com/docs/api-reference/chat/create-assistant-message#parameter-domain) domain string required The domain identifier that can be found in the top left corner of the Mintlify dashboard #### Body application/json #### Response 200 - application/json Message generated successfully Response object that streams formatted data stream parts with the specified status, headers, and content. This matches what is expected from the AI SDK as documented at [ai-sdk.dev/docs/ai-sdk-ui/streaming-data](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data) . Instead of writing your own parser, it is recommended to use the [useChat hook from ai-sdk as documented here](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) . Was this page helpful? YesNo [Previous\ \ Get Update StatusGet the status of an update from the status ID](https://mintlify.com/docs/api-reference/update/status) Generate Assistant Message cURL Copy Ask AI curl --request POST \ --url https://api-dsc.mintlify.com/v1/assistant/{domain}/message \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "fp": "", "threadId": null, "messages": [\ {\ "id": "foobar",\ "role": "user",\ "content": "how do i get started",\ "parts": [\ {\ "type": "text",\ "text": "How do I get started"\ }\ ]\ }\ ], "retrievalPageSize": 5, "filter": null }' 200 Copy Ask AI {} Assistant Responses are generated using AI and may contain mistakes. --- # Get Update Status - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Admin Get Update Status GET / project / update-status / {statusId} Try it Get Update Status cURL Copy Ask AI curl --request GET \ --url https://api.mintlify.com/v1/project/update-status/{statusId} \ --header 'Authorization: Bearer ' 200 Copy Ask AI { "_id": "", "projectId": "", "createdAt": "", "endedAt": "", "status": "queued", "summary": "", "logs": [\ ""\ ], "subdomain": "", "screenshot": "", "screenshotLight": "", "screenshotDark": "", "author": "", "commit": { "sha": "", "ref": "", "message": "", "filesChanged": { "added": [\ ""\ ], "modified": [\ ""\ ], "removed": [\ ""\ ] } }, "source": "internal" } #### Authorizations [​](https://mintlify.com/docs/api-reference/update/status#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://mintlify.com/docs/api-reference/update/status#parameter-status-id) statusId string required The status ID of a triggered update. #### Response 200 - application/json A successful response The response is of type `object`. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-reference/update/trigger) [Generate Assistant MessageGenerates a response message from the assistant for the specified domain. For best results, use the \[useChat hook from ai-sdk\](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) to send requests and handle responses. You can set \`fp\`, \`threadId\`, and \`filter\` in the \`body\` field of the options parameter passed to the hook.\ \ Next](https://mintlify.com/docs/api-reference/chat/create-assistant-message) Get Update Status cURL Copy Ask AI curl --request GET \ --url https://api.mintlify.com/v1/project/update-status/{statusId} \ --header 'Authorization: Bearer ' 200 Copy Ask AI { "_id": "", "projectId": "", "createdAt": "", "endedAt": "", "status": "queued", "summary": "", "logs": [\ ""\ ], "subdomain": "", "screenshot": "", "screenshotLight": "", "screenshotDark": "", "author": "", "commit": { "sha": "", "ref": "", "message": "", "filesChanged": { "added": [\ ""\ ], "modified": [\ ""\ ], "removed": [\ ""\ ] } }, "source": "internal" } Assistant Responses are generated using AI and may contain mistakes. --- # Trigger Update - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Admin Trigger Update POST / project / update / {projectId} Try it Trigger Update cURL Copy Ask AI curl --request POST \ --url https://api.mintlify.com/v1/project/update/{projectId} \ --header 'Authorization: Bearer ' 202 Copy Ask AI { "statusId": "" } #### Authorizations [​](https://mintlify.com/docs/api-reference/update/trigger#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://mintlify.com/docs/api-reference/update/trigger#parameter-project-id) projectId string required The ID of the project to trigger an update on. Can be retrieved from your dashboard. #### Response 202 - application/json A successful response The response is of type `object`. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-reference/introduction) [Get Update StatusGet the status of an update from the status ID\ \ Next](https://mintlify.com/docs/api-reference/update/status) Trigger Update cURL Copy Ask AI curl --request POST \ --url https://api.mintlify.com/v1/project/update/{projectId} \ --header 'Authorization: Bearer ' 202 Copy Ask AI { "statusId": "" } Assistant Responses are generated using AI and may contain mistakes. --- # Editor permissions - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Dashboard Access Editor permissions An editor has access to your dashboard and web editor. Anyone can contribute to your documentation by working locally and pushing changes to your repository, but there are key differences in how changes get deployed: * **Editor changes**: When an editor publishes through the web editor or merges a pull request into your docs repository, changes deploy to your live site automatically. * **Non-editor changes**: When a non-editor merges a pull request into your repository, you must manually trigger a deployment from your dashboard for those changes to appear on your live site. [​](https://mintlify.com/docs/advanced/dashboard/permissions#add-editors) Add editors ---------------------------------------------------------------------------------------- By default, the team member who created your Mintlify organization has editor access. Add additional editors in the [Members](https://dashboard.mintlify.com/settings/organization/members) page of your dashboard. Editor seats are billed based on usage, and you can have as many editors as you need. See our [pricing page](https://mintlify.com/pricing) for more details. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/advanced/dashboard/sso) [RolesControl access to your dashboard with roles.\ \ Next](https://mintlify.com/docs/advanced/dashboard/roles) On this page * [Add editors](https://mintlify.com/docs/advanced/dashboard/permissions#add-editors) Assistant Responses are generated using AI and may contain mistakes. --- # Product updates - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Changelog Product updates [​](https://mintlify.com/docs/changelog#june-2025) June 2025 [​](https://mintlify.com/docs/changelog#ai-assistant-updates) AI assistant updates ------------------------------------------------------------------------------------- * Improved accuracy through agentic RAG with tool calling * Provides navigable links to referenced pages so that users can go directly to the source of answers * Copy shortcut for code examples generated by assistant * “Ask AI” shortcut on code blocks in documentation to generate explanations from the assistant Learn more in the [assistant docs](https://mintlify.com/docs/guides/assistant) . [​](https://mintlify.com/docs/changelog#subscribable-changelogs) Subscribable changelogs ------------------------------------------------------------------------------------------- * Automatically generate an RSS feed from changelog pages * Integrate RSS-enabled updates with Slack, email, and other tools Learn more in our new [Changelog guide](https://mintlify.com/docs/guides/changelogs) [​](https://mintlify.com/docs/changelog#may-2025) May 2025 [​](https://mintlify.com/docs/changelog#api-playground-stability-updates) API playground stability updates ------------------------------------------------------------------------------------------------------------- * Search to find an endpoint * Indicate a deprecated endpoint with a tag * Hide auto-generated API pages from navigation * Upload multipart or form data files Learn more at [API playground docs.](https://mintlify.com/docs/api-playground) [​](https://mintlify.com/docs/changelog#mint-update) `mint update` --------------------------------------------------------------------- Can now use `mint update` to update your CLI. [​](https://mintlify.com/docs/changelog#april-2025) April 2025 [​](https://mintlify.com/docs/changelog#web-editor-3-0) Web Editor 3.0 ------------------------------------------------------------------------- Overhauled usability in the WYSIWYG editor. **Major improvements** * Search for file names using ⌘ + P shortcut * Pages load 10x faster * Faster load times when searching for a branch * Page options tab to configure layout, title, & metadata for SEO * Floating toolbar when you highlight text **Additional fixes** * Fixed top margin for changelog components * Improved reliability of right click behavior * After clicking publish, you’ll stay on the same page instead of being brought to an empty state * Standardized colors in file icons * Improved reliability after selecting new branches several times in a row * Removed Diff mode * More consistency when creating a new folder from the dropdown * Fixed block quotes creating more block quotes when trying to deselect [​](https://mintlify.com/docs/changelog#ai-translations-in-beta) AI Translations in beta ------------------------------------------------------------------------------------------- Translate all of your documentation with AI. [Learn more.](https://mintlify.com/docs/navigation#localization) [​](https://mintlify.com/docs/changelog#export-docs-to-pdf-in-beta) Export docs to PDF in beta ------------------------------------------------------------------------------------------------- Export all of your documentation, a subdirectory, or a singe page as a PDF. [​](https://mintlify.com/docs/changelog#react-hook-support) React hook support --------------------------------------------------------------------------------- Bring interactivity to your docs. All standard React hooks are automatically available in your MDX files. [Learn more.](https://mintlify.com/docs/react-components) [​](https://mintlify.com/docs/changelog#march-2025) March 2025 [​](https://mintlify.com/docs/changelog#mcp-server-generator) MCP server generator ------------------------------------------------------------------------------------- Generate MCP servers so that AI applications can interact with your docs or APIs. Written content is automatically generated as an MCP server, and you can generate an MCP server from your OpenAPI spec with one click. Check out [docs on getting started with MCP.](https://mintlify.com/docs/mcp) [​](https://mintlify.com/docs/changelog#improvements) Improvements --------------------------------------------------------------------- * Tag changelog updates so end users can filter updates * Sonnet-3.7 supported for AI Chat. Configure your preferred model through the dashboard * Change your deployment name directly in dashboard settings [​](https://mintlify.com/docs/changelog#bug-fixes) Bug fixes --------------------------------------------------------------- * OG images fixed * Fixed icon style inconsistency for anchors without container * Improved styling nits for dashboard border for mobile-tablet-desktop responsiveness * Show code examples even when in simple mode for API playground * Support “command + k” shortcut for search in web editor * Codeblocks within callouts expand to fill the width of the callout area [​](https://mintlify.com/docs/changelog#february-2025) February 2025 [​](https://mintlify.com/docs/changelog#new-configuration-schema-docs-json) New configuration schema `docs.json` ------------------------------------------------------------------------------------------------------------------- We’ve introduced a new `docs.json` schema as a replacement for `mint.json`, to support better multi-level versioning, easier visual comprehension, and more consistent terminology. For more information on what’s changed, [check out our blog](https://mintlify.com/blog/refactoring-mint-json-into-docs-json) . Upgrade from `mint.json` to `docs.json` with the following steps: 1. Make sure your CLI is the latest version Copy Ask AI npm i mint@latest -g 1. In your docs repository, run Copy Ask AI mint upgrade 1. Delete your old `mint.json` file and push your changes [​](https://mintlify.com/docs/changelog#ci-checks) CI Checks --------------------------------------------------------------- Automatically lint your docs to find broken links, discover spelling and grammar issues, or enforce writing styles with your own Vale config. Learn more in our [docs](https://mintlify.com/docs/settings/ci) . [​](https://mintlify.com/docs/changelog#md-support-for-llms) .md support for LLMs ------------------------------------------------------------------------------------ All documentation pages are now automatically available as plain Markdown files—just append `.md` to the URL. This makes it easier for LLMs to ingest individual pages from your documentation. [​](https://mintlify.com/docs/changelog#more-themes) More Themes ------------------------------------------------------------------- New [pre-built themes](https://mintlify.com/docs/themes) to modify the look & feel of your docs. Configure via your [docs.json file](https://mintlify.com/docs/settings) . Now available: * Maple * Palm * Willow [​](https://mintlify.com/docs/changelog#other-improvements) Other improvements --------------------------------------------------------------------------------- * [Guide to Technical Writing:](https://mintlify.com/guides/introduction) Best practices for writing technical documentation, including audience research, content types, and writing tips. * [Dropdown component](https://mintlify.com/docs/navigation#dropdowns) : Organize navigation with a dropdown, in addition to tabs and anchors. * [AI syntax fixer](https://x.com/ricardonunez_io/status/1892334887644123192) : The web editor will catch if there’s a parsing error and use AI to suggest fixes. [​](https://mintlify.com/docs/changelog#january-2025) January 2025 [​](https://mintlify.com/docs/changelog#ai-assistant-improvements) AI Assistant Improvements ----------------------------------------------------------------------------------------------- * New UI with dedicated chat page & pre-filled prompts * Stability improvements, e.g. bug fixes of editing the wrong file or no files at all * More robust knowledge for adding & editing components * Improved `docs.json` file editing [​](https://mintlify.com/docs/changelog#partial-authentication) Partial Authentication ----------------------------------------------------------------------------------------- Customize access to any page or section of content depending on user permissions. Supports connecting with your own authentication system. [​](https://mintlify.com/docs/changelog#revamped-api-playground) Revamped API Playground ------------------------------------------------------------------------------------------- We’ve overhauled the design and performance of the [API Playground](https://mintlify.com/docs/api-playground) . Updates include: * Easier detail expansion for an overview of a field * More intuitive nested design, e.g. adding or deleting items * Faster response times [​](https://mintlify.com/docs/changelog#quality-improvements) Quality Improvements ------------------------------------------------------------------------------------- * Support for requiring authentication to access preview deployments [​](https://mintlify.com/docs/changelog#december-2024) December 2024 [​](https://mintlify.com/docs/changelog#authentication) Authentication ------------------------------------------------------------------------- Make docs private by setting up authentication via JWT, OAuth, or a universal password. With this privacy, you can create an internal knowledge base or prevent competitors from seeing your docs. [​](https://mintlify.com/docs/changelog#november-2024) November 2024 [​](https://mintlify.com/docs/changelog#ai-writer) AI Writer --------------------------------------------------------------- You can now ask AI to make changes to your docs, with the context of all existing documentation. Type in a prompt and the writer will propose changes by generating a pull request. [​](https://mintlify.com/docs/changelog#gitlab-integration-upgrade) GitLab Integration Upgrade ------------------------------------------------------------------------------------------------- We’ve improved our support for syncing with GitLab, such as enabling automated updates and preview deployments. Check out our [docs on GitLab](https://mintlify.com/docs/settings/gitlab) to get started. [​](https://mintlify.com/docs/changelog#web-editor) Web Editor ----------------------------------------------------------------- We’ve revamped our web editor so that you can now update docs with a fully WYSIWYG experience, while syncing with markdown. Check out our [docs on getting started with Web Editor](https://mintlify.com/docs/editor) . [​](https://mintlify.com/docs/changelog#%2Fllms-txt-support) /llms.txt support --------------------------------------------------------------------------------- All docs instances are now automatically hosted at /llms.txt and /llms-full.txt so that LLMs can easily ingest your documentation. For more information, read the [docs on the new llms.txt standard.](https://llmstxt.org/) [​](https://mintlify.com/docs/changelog#localization) Localization --------------------------------------------------------------------- You can now localize your docs which operates similarly to versioning. Add a `locale` to a version and fixed content in Mintlify like “Was this page helpful?” will also match the locale. ### [​](https://mintlify.com/docs/changelog#quality-improvements-2) Quality Improvements * Return chat & search results based on the current version that the user is reading * Authenticate users with OAuth, in addition to JWT or Shared Session tokens. [​](https://mintlify.com/docs/changelog#october-2024) October 2024 [​](https://mintlify.com/docs/changelog#changelogs) Changelogs ----------------------------------------------------------------- Launched a new [Update component](https://mintlify.com/docs/components/update) to make it easier to display and report updates (like this one) to your users. [​](https://mintlify.com/docs/changelog#code-line-highlighting) Code Line Highlighting ----------------------------------------------------------------------------------------- You can now highlight lines of code in your docs to emphasize and bring attention to important parts by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas. Line Highlighting Example Copy Ask AI const greeting = "Hello, World!"; function sayHello() { console.log(greeting); } sayHello(); Copy Ask AI ```javascript Line Highlighting Example {1,3-5} const greeting = "Hello, World!"; function sayHello() { console.log(greeting); } sayHello(); ``` [​](https://mintlify.com/docs/changelog#light-mode-code-blocks) Light mode code blocks ----------------------------------------------------------------------------------------- Code blocks now have a light mode variant which can be enabled by adding the following to your `docs.json`: Copy Ask AI "codeBlock": { "mode": "auto" } [​](https://mintlify.com/docs/changelog#advanced-footer) Advanced Footer --------------------------------------------------------------------------- You can now add more links to the standard footer. This upgrade provides more consistency between landing pages and docs, or greater customization if you want to spotlight specific pages like socials or status logs. [​](https://mintlify.com/docs/changelog#filter-search-based-on-the-current-user) Filter search based on the current user --------------------------------------------------------------------------------------------------------------------------- When personalization is enabled, search results are now filtered based on the current logged in user so that they only see the relevant content. [​](https://mintlify.com/docs/changelog#custom-prompts-for-ai-chat) Custom Prompts for AI Chat ------------------------------------------------------------------------------------------------- You can now customize the prompts for the AI chat. Please reach out to [support](https://mintlify.com/cdn-cgi/l/email-protection#03707673736c7177436e6a6d776f6a657a2d606c6e) if you’d like to customize the prompts. [​](https://mintlify.com/docs/changelog#dashboard-improvements) Dashboard Improvements ----------------------------------------------------------------------------------------- * Added ability to change custom domain to be /docs directly through dashboard settings. * Consolidated the login and signup pages to decrease friction and confusion. * Implemented the discovery login flow so that users that are members of multiple organizations can now switch between them. * Added login with Google OAuth * Added ability to add new deployment through dashboard settings. [​](https://mintlify.com/docs/changelog#bug-fixes-2) Bug Fixes ----------------------------------------------------------------- * Can now use leading slashes in navigation. * Can now edit CSS & JS files in the web editor. * Fixed `suggestEdit` not showing up even when enabled. * Fixed keyboard navigation for Search and Chat such that you can now use the up and down arrow keys to navigate the results. * Don’t allow search engines to crawl user-auth protected pages. * Revalidate the cache when an org is deleted. * We now use the Scalar OpenAPI parser to parse OpenAPI definitions which improves the performance, fixes parsing issues, and surfaces better error messages. * Top-level descriptions are now supported in API reference pages autogenerated from OpenAPI definitions. * Add in-line-style support for icons * Fixed the pop-in of custom CSS in docs. * Properly show in-line code styling in conjunction with links. * Maintain scroll position when you click the back button in a browser. [​](https://mintlify.com/docs/changelog#september-2024) September 2024 [​](https://mintlify.com/docs/changelog#custom-fonts) Custom Fonts --------------------------------------------------------------------- Personalize the font of your docs to your own font hosted on a CDN or by choosing from Google fonts to match your docs with your brand. [​](https://mintlify.com/docs/changelog#images-in-card-components) Images in Card components ----------------------------------------------------------------------------------------------- Add an `img` property to a card to display an image on the top of the card. Learn more about it [here](https://mintlify.com/docs/components/cards#image-card) . [​](https://mintlify.com/docs/changelog#update-speed-performances) Update Speed Performances ----------------------------------------------------------------------------------------------- For large projects (~3,000 files), the download step for docs updates is now ~440x faster - a 99.8% time reduction. Across the board, file downloads during updates are now ~5.5x faster - an 81.8% time reduction. [​](https://mintlify.com/docs/changelog#seo-improvements) SEO improvements ----------------------------------------------------------------------------- We’ve fixed both the mobile and desktop layout of our docs so that they are more SEO-friendly - including adding proper aria tags to navbar and toggle elements. [​](https://mintlify.com/docs/changelog#dashboard-improvements-2) Dashboard Improvements ------------------------------------------------------------------------------------------- * App router migration in the dashboard. * Search analytics are now available in the dashboard. * Delete an org functionality has been added to the dashboard. * Shipped GitLab connection UI. * Fix incorrect analytics data. * Add-on’s can now be directly purchased through the dashboard. [​](https://mintlify.com/docs/changelog#bug-fixes-3) Bug Fixes ----------------------------------------------------------------- * Fixed a bug where the top bar would not stretch to the width of the screen when it’s in custom mode and the sidebar layout is `sidenav`. * Fix relative positioning of the AI widget. [​](https://mintlify.com/docs/changelog#more) More ----------------------------------------------------- * **Troubleshooting for API pages**: API pages could be complicated so we listed common issues to help you sort them out quickly — [Read the docs](https://mintlify.com/docs/api-playground/troubleshooting) [​](https://mintlify.com/docs/changelog#august-2024) August 2024 [​](https://mintlify.com/docs/changelog#openapi-reference-pages) OpenAPI Reference Pages ------------------------------------------------------------------------------------------- * Endpoints defined by OpenAPI that are complex and recursive are now 98% smaller. * We now show [additionalProperties](https://swagger.io/docs/specification/data-models/dictionaries/) in OpenAPI pages. [​](https://mintlify.com/docs/changelog#file-uploads-in-api-playground) File Uploads in API Playground --------------------------------------------------------------------------------------------------------- By default, API playground requests are proxied by Mintlify. Now you can use `disableProxy` to disable this behavior and support request types like file uploads. * [Learn more about API configurations](https://mintlify.com/docs/settings#api-configurations) [​](https://mintlify.com/docs/changelog#mobile-seo-improvements) Mobile SEO improvements ------------------------------------------------------------------------------------------- We’ve fixed the mobile layout of our docs so that they are more SEO-friendly - including adding proper aria tags to elements. [​](https://mintlify.com/docs/changelog#support-form) Support Form --------------------------------------------------------------------- We added a more detailed support form to the Mintlify dashboard. You can now submit a form to get in touch with us. [​](https://mintlify.com/docs/changelog#bug-fixes-4) Bug Fixes ----------------------------------------------------------------- * Fixed a bug for the Segment integration functionality. * We now raise more granular error messages for GitHub permissions when interacting with the editor. * Fixed bugs where the navigation would not properly expand when a direct link was used. [​](https://mintlify.com/docs/changelog#july-2024) July 2024 [​](https://mintlify.com/docs/changelog#ai-widget) AI Widget --------------------------------------------------------------- For `Pro` users, we introduced Mintlify Widget, an extension of your docs to answer your users’ questions when and where they asked. You can add this AI-powered chatbot to any web page: your landing page, inside your product, or on your existing documentation pages. * [Read the blog announcement](https://mintlify.com/blog/widget) [​](https://mintlify.com/docs/changelog#pro-plan) Pro Plan ------------------------------------------------------------- We also updated our pricing plans for better customizability and scale. * [Read the blog announcement](https://mintlify.com/blog/pro-plan) [​](https://mintlify.com/docs/changelog#api-playground-code-example-sync) API Playground Code Example Sync ------------------------------------------------------------------------------------------------------------- When you browse API docs, the selected code example now syncs across your pages. [​](https://mintlify.com/docs/changelog#insights) Insights ------------------------------------------------------------- Currently in beta, this feature summarizes common user questions and patterns into easy-to-digest reports with AI-powered suggestions on how to improve your product. [​](https://mintlify.com/docs/changelog#june-2024) June 2024 [​](https://mintlify.com/docs/changelog#launch-week-highlights) Launch Week Highlights ----------------------------------------------------------------------------------------- * Themes: Customize your styling with pre-configured themes. Just add the theme Quill, Prism, or Venus to your `docs.json` file and it’ll update your docs styling. * Search V2: directly query OpenAPI endpoint descriptions and titles to reach API Reference pages, remove hidden pages from search, and enjoy our updated search bar UI. * Web Editor branching: create branches in our web editor without an IDE. * User Personalization: authenticate users with Shared Session or JWT so that you can show them customized content, such as pre-filling API keys or showing specific content for customers. * OpenAPI Automation Upgrades: to auto-populate API Playground pages, you can add an `openapi` field to an object in tabs or anchors arrays in the `docs.json`. [​](https://mintlify.com/docs/changelog#may-2024) May 2024 [​](https://mintlify.com/docs/changelog#okta-sso) Okta SSO ------------------------------------------------------------- We now support sign-on via Okta SAML and OIDC. [​](https://mintlify.com/docs/changelog#mintlify-rest-api) Mintlify REST API ------------------------------------------------------------------------------- Programmatically rigger updates to your documentation. [​](https://mintlify.com/docs/changelog#april-2024) April 2024 [​](https://mintlify.com/docs/changelog#custom-mode) Custom mode ------------------------------------------------------------------- Add a configuration to the metadata to remove all elements except for the top bar. Example use cases: * Create a custom global landing page setup with custom components * Add full-screen videos or image galleries * Embed custom iFrame demo elements to add intractability to your docs Check out our [Custom Mode docs](https://mintlify.com/docs/pages#custom-mode) . [​](https://mintlify.com/docs/changelog#march-2024) March 2024 [​](https://mintlify.com/docs/changelog#mintlify-mdx-for-vscode) Mintlify MDX for VSCode ------------------------------------------------------------------------------------------- Call snippets of our pre-built components and callouts without leaving VSCode. [Install the extension here](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets) . [​](https://mintlify.com/docs/changelog#february-2024) February 2024 [​](https://mintlify.com/docs/changelog#quality-improvements-3) Quality Improvements --------------------------------------------------------------------------------------- * Dashboard upgrades: view update logs to see what’s changed and status of an update, toggle between Mintlify projects to manage deployments * Versioning with tabs fully supported * Wildcard redirects now supported * CLI Error Detection: we now show the position of invalid frontmatter when there are parsing issues during local development [​](https://mintlify.com/docs/changelog#january-2024) January 2024 [​](https://mintlify.com/docs/changelog#launch-week-highlights-2) Launch Week Highlights ------------------------------------------------------------------------------------------- * Preview Deployments: When you create a pull request, we’ll generate a unique link that shows a live preview of what your docs look like in prod. You can share this link with teammates. * Snippets V2: We now support fully reusable components and variables for snippets. * Open-source MDX Engine: We’ve exposed two APIs—getCompiledMdx and MDXComponent—so you can access Mintlify markdown and code syntax highlighting. [Contributions to the project](https://github.com/mintlify/mdx) are welcome. * AI Chat Insights: Segment chat history by date and increase AI Chat quota from the dashboard, and see how often a specific query appears. Was this page helpful? YesNo On this page * [June 2025](https://mintlify.com/docs/changelog#june-2025) * [May 2025](https://mintlify.com/docs/changelog#may-2025) * [April 2025](https://mintlify.com/docs/changelog#april-2025) * [March 2025](https://mintlify.com/docs/changelog#march-2025) * [February 2025](https://mintlify.com/docs/changelog#february-2025) * [January 2025](https://mintlify.com/docs/changelog#january-2025) * [December 2024](https://mintlify.com/docs/changelog#december-2024) * [November 2024](https://mintlify.com/docs/changelog#november-2024) * [October 2024](https://mintlify.com/docs/changelog#october-2024) * [September 2024](https://mintlify.com/docs/changelog#september-2024) * [August 2024](https://mintlify.com/docs/changelog#august-2024) * [July 2024](https://mintlify.com/docs/changelog#july-2024) * [June 2024](https://mintlify.com/docs/changelog#june-2024) * [May 2024](https://mintlify.com/docs/changelog#may-2024) * [April 2024](https://mintlify.com/docs/changelog#april-2024) * [March 2024](https://mintlify.com/docs/changelog#march-2024) * [February 2024](https://mintlify.com/docs/changelog#february-2024) * [January 2024](https://mintlify.com/docs/changelog#january-2024) Assistant Responses are generated using AI and may contain mistakes. --- # Roles - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Dashboard Access Roles RBAC functionality is available on [Enterprise plan](https://mintlify.com/pricing?ref=rbac) . Mintlify provides two dashboard access levels: Editor and Admin. The following describes actions that are limited to the Admin role: | | Editor | Admin | | --- | --- | --- | | Update user roles | ❌ | ✅ | | Delete users | ❌ | ✅ | | Invite admin users | ❌ | ✅ | | Manage & update billing | ❌ | ✅ | | Update custom domain | ❌ | ✅ | | Update Git source | ❌ | ✅ | | Delete org | ❌ | ✅ | Other actions on the dashboard are available to both roles. You can invite as many admins as you want, but we recommend limiting admin access to users who need it. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/advanced/dashboard/permissions) [DeploymentsTroubleshoot your deployments\ \ Next](https://mintlify.com/docs/guides/deployments) Assistant Responses are generated using AI and may contain mistakes. --- # AWS Route 53 and Cloudfront - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Custom Subdirectory AWS Route 53 and Cloudfront [​](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#create-cloudfront-distribution) Create Cloudfront Distribution ----------------------------------------------------------------------------------------------------------------------------------- Navigate to [Cloudfront](https://aws.amazon.com/cloudfront) inside the AWS console and click on `Create distribution` For the Origin domain, input `[SUBDOMAIN].mintlify.dev` where `[SUBDOMAIN]` is the project’s unique subdomain. Click on `Use: [SUBDOMAIN].mintlify.dev` For **Cache key and origin requests**, select `Caching Optimized`. And for **Web Application Firewall (WAF)**, enable security protections The remaining settings should be default. Click `Create distribution`. [​](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#add-default-origin) Add Default Origin ----------------------------------------------------------------------------------------------------------- After creating the distribution, navigate to the `Origins` tab. We want to find a staging URL that mirrors where the main domain (example.com). This is highly variant depending on how your landing page is hosted. For instance, if your landing page is hosted on Webflow, you can use the Webflow’s staging URL. It would look like `.webflow.io`. If you use Vercel, you use the `.vercel.app` domain available for every project. If you’re unsure on how to get a staging URL for your landing page, [contact support](https://mintlify.com/docs/contact-support) and we’d be happy to help Once you have the staging URL, ours for instance is [mintlify-landing-page.vercel.app](https://mintlify-landing-page.vercel.app/) , create a new Origin and add it as the **Origin domain**. By this point, you should have two Origins - one with `[SUBDOMAIN].mintlify.app` and another with with staging URL. [​](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#set-behaviors) Set Behaviors ------------------------------------------------------------------------------------------------- Behaviors in Cloudfront enables control over the subpath logic. At a high level, we’re looking to create the following logic. * **If a user lands on /docs**, go to `[SUBDOMAIN].mintlify.dev` * **If a user lands on any other page**, go the current landing page We’re going to create three behaviors by clicking on the `Create behavior` button. ### [​](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#%2Fdocs%2F) `/docs/*` The first behavior should have a **Path pattern** of `/docs/*` with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`) For **Cache policy**, select `CachingOptimized` and create behavior. ### [​](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#%2Fdocs) `/docs` The second behavior should be the same as the first one but with a **Path pattern** of `/docs` and **Origin and origin groups** pointing to the same `.mintlify.dev` URL. ### [​](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#default) `Default (*)` Lastly, we’re going to edit the `Default (*)` behavior. We’re going to change the default behavior’s **Origin and origin groups** to the staging URL (in our case `mintlify-landing-page.vercel.app`). Click on `Save changes`. [​](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#preview-distribution) Preview Distribution --------------------------------------------------------------------------------------------------------------- You can now test if your distribution is set up properly by going to the `General` tab and visiting the **Distribution domain name** URL. All pages should be directing to your main landing page, but if you append `/docs` to the URL, you should see it going to the Mintlify documentation instance. [​](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#connecting-it-with-route53) Connecting it with Route53 --------------------------------------------------------------------------------------------------------------------------- Now, we’re going to bring the functionality of the Cloudfront distribution into your primary domain. For this section, you can also refer to AWS’s official guide on [Configuring Amazon Route 53 to route traffic to a CloudFront distribution](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-cloudfront-distribution.html#routing-to-cloudfront-distribution-config) Navigate to [Route53](https://aws.amazon.com/route53) inside the AWS console, and click into the `Hosted zone` for your primary domain. Click on `Create record` Toggle `Alias` and then **Route traffic to** the `Alias to CloudFront distribution` option. Click `Create records`. You may need to remove the existing A record if one currently exists. And voila! Your documentation will be served at `/docs` for your primary domain. After configuring your DNS, custom subdomains are usually available within a few minutes. DNS propagation can sometimes take 1-4 hours, and in rare cases up to 48 hours. If your subdomain is not immediately available, please wait before troubleshooting. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/advanced/subpath/cloudflare) [VercelHost documentation at a /docs subpath using Vercel\ \ Next](https://mintlify.com/docs/advanced/subpath/vercel) On this page * [Create Cloudfront Distribution](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#create-cloudfront-distribution) * [Add Default Origin](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#add-default-origin) * [Set Behaviors](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#set-behaviors) * [/docs/\*](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#%2Fdocs%2F) * [/docs](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#%2Fdocs) * [Default (\*)](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#default) * [Preview Distribution](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#preview-distribution) * [Connecting it with Route53](https://mintlify.com/docs/advanced/subpath/route53-cloudfront#connecting-it-with-route53) Assistant Responses are generated using AI and may contain mistakes. --- # Single sign-on (SSO) - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Dashboard Access Single sign-on (SSO) SSO functionality is available on [Enterprise plan](https://mintlify.com/pricing?ref=sso) . Use single sign-on to your dashboard via SAML and OIDC. If you use Okta, Google Workspace, or Microsoft Entra, we have provider-specific documentation for setting up SSO. If you use another provider, please [contact us](https://mintlify.com/cdn-cgi/l/email-protection#95e6e0e5e5fae7e1d5f8fcfbe1f9fcf3ecbbf6faf8) . [​](https://mintlify.com/docs/advanced/dashboard/sso#okta) Okta ------------------------------------------------------------------ * SAML * OIDC 1 Create an application Under `Applications`, click to create a new app integration using SAML 2.0. 2 Configure integration Enter the following: * Single sign-on URL (provided by Mintlify) * Audience URI (provided by Mintlify) * Name ID Format: `EmailAddress` * Attribute Statements: | Name | Name format | Value | | --- | --- | --- | | `firstName` | Basic | `user.firstName` | | `lastName` | Basic | `user.lastName` | 3 Send us your IdP information Once the application is set up, navigate to the sign-on tab and send us the metadata URL. We’ll enable the connection from our side using this information. 1 Create an application Under `Applications`, click to create a new app integration using SAML 2.0. 2 Configure integration Enter the following: * Single sign-on URL (provided by Mintlify) * Audience URI (provided by Mintlify) * Name ID Format: `EmailAddress` * Attribute Statements: | Name | Name format | Value | | --- | --- | --- | | `firstName` | Basic | `user.firstName` | | `lastName` | Basic | `user.lastName` | 3 Send us your IdP information Once the application is set up, navigate to the sign-on tab and send us the metadata URL. We’ll enable the connection from our side using this information. 1 Create an application Under `Applications`, click to create a new app integration using OIDC. You should choose the `Web Application` application type. 2 Configure integration Select the authorization code grant type and enter the Redirect URI provided by Mintlify. 3 Send us your IdP information Once the application is set up, navigate to the General tab and locate the client ID & client secret. Please securely provide us with these, along with your Okta instance URL (e.g. `.okta.com`). You can send these via a service like 1Password or SendSafely. [​](https://mintlify.com/docs/advanced/dashboard/sso#google-workspace) Google Workspace ------------------------------------------------------------------------------------------ * SAML 1 Create an application Under `Web and mobile apps`, select `Add custom SAML app` from the `Add app` dropdown. 2 Send us your IdP information Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team. 3 Configure integration On the Service provider details page, enter the following: * ACS URL (provided by Mintlify) * Entity ID (provided by Mintlify) * Name ID format: `EMAIL` * Name ID: `Basic Information > Primary email` On the next page, enter the following attribute statements: | Google Directory Attribute | App Attribute | | --- | --- | | `First name` | `firstName` | | `Last name` | `lastName` | Once this step is complete and users are assigned to the application, let our team know and we’ll enable SSO for your account! 1 Create an application Under `Web and mobile apps`, select `Add custom SAML app` from the `Add app` dropdown. 2 Send us your IdP information Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team. 3 Configure integration On the Service provider details page, enter the following: * ACS URL (provided by Mintlify) * Entity ID (provided by Mintlify) * Name ID format: `EMAIL` * Name ID: `Basic Information > Primary email` On the next page, enter the following attribute statements: | Google Directory Attribute | App Attribute | | --- | --- | | `First name` | `firstName` | | `Last name` | `lastName` | Once this step is complete and users are assigned to the application, let our team know and we’ll enable SSO for your account! [​](https://mintlify.com/docs/advanced/dashboard/sso#microsoft-entra) Microsoft Entra ---------------------------------------------------------------------------------------- * SAML 1 Create an application 1. Under “Enterprise applications”, select **New application**. 2. Select **Create your own application** and choose “Integrate any other application you don’t find in the gallery (Non-gallery).” 2 Configure SAML Navigate to the Single Sign-On setup page and select **SAML**. Under “Basic SAML Configuration,” enter the following: * Identifier (Entity ID): The Audience URI provided by Mintlify. * Reply URL (Assertion Consumer Service URL): The ACS URL provided by Mintlify. Leave the other values blank and select **Save**. 3 Configure Attributes & Claims Edit the Attributes & Claims section: 1. Select **Unique User Identifier (Name ID)** under “Required Claim.” 2. Change the Source attribute to use `user.primaryauthoritativeemail`. 3. Under Additional claims, create the following claims: | Name | Value | | --- | --- | | `firstName` | `user.givenname` | | `lastName` | `user.surname` | 4 Send Mintlify your IdP information Once the application is set up, navigate to the “SAML Certificates” section and send us the App Federation Metadata URL. We’ll enable the connection from our side using this information. 5 Assign Users Navigate to “Users and groups” in your Entra application and add the users who should have access to your dashboard. 1 Create an application 1. Under “Enterprise applications”, select **New application**. 2. Select **Create your own application** and choose “Integrate any other application you don’t find in the gallery (Non-gallery).” 2 Configure SAML Navigate to the Single Sign-On setup page and select **SAML**. Under “Basic SAML Configuration,” enter the following: * Identifier (Entity ID): The Audience URI provided by Mintlify. * Reply URL (Assertion Consumer Service URL): The ACS URL provided by Mintlify. Leave the other values blank and select **Save**. 3 Configure Attributes & Claims Edit the Attributes & Claims section: 1. Select **Unique User Identifier (Name ID)** under “Required Claim.” 2. Change the Source attribute to use `user.primaryauthoritativeemail`. 3. Under Additional claims, create the following claims: | Name | Value | | --- | --- | | `firstName` | `user.givenname` | | `lastName` | `user.surname` | 4 Send Mintlify your IdP information Once the application is set up, navigate to the “SAML Certificates” section and send us the App Federation Metadata URL. We’ll enable the connection from our side using this information. 5 Assign Users Navigate to “Users and groups” in your Entra application and add the users who should have access to your dashboard. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/advanced/subpath/vercel) [Editor permissionsAllow more members of your team to update your docs\ \ Next](https://mintlify.com/docs/advanced/dashboard/permissions) On this page * [Okta](https://mintlify.com/docs/advanced/dashboard/sso#okta) * [Google Workspace](https://mintlify.com/docs/advanced/dashboard/sso#google-workspace) * [Microsoft Entra](https://mintlify.com/docs/advanced/dashboard/sso#microsoft-entra) Assistant Responses are generated using AI and may contain mistakes. --- # Playground - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation AsyncAPI Playground WSS wss://echo-websocket.hoppscotch.iowss://echo.websocket.org Connect Messages Test message { "text": "", "subtext": "", "from": ""} Test message { "text": "", "subtext": "", "from": ""} Timestamp "22:02:27 GMT+0000 (Coordinated Universal Time)" Send Test message type:object show 3 properties Test message sent to the echo server Receive Test message type:object show 3 properties Test message sent to the echo server Timestamp type:string Timestamp message sent from echo hoppscotch server Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-playground/asyncapi/setup) [MDX setupGenerate docs pages for your API endpoints using \`MDX\`\ \ Next](https://mintlify.com/docs/api-playground/mdx/configuration) Messages Test message { "text": "", "subtext": "", "from": ""} Test message { "text": "", "subtext": "", "from": ""} Timestamp "22:02:27 GMT+0000 (Coordinated Universal Time)" Assistant Responses are generated using AI and may contain mistakes. --- # AsyncAPI setup - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation AsyncAPI AsyncAPI setup [​](https://mintlify.com/docs/api-playground/asyncapi/setup#add-an-asyncapi-specification-file) Add an AsyncAPI specification file ------------------------------------------------------------------------------------------------------------------------------------- To begin to create pages for your websockets, make sure you have a valid AsyncAPI schema document in either JSON or YAML format that follows the [AsyncAPI specification](https://www.asyncapi.com/docs/reference/specification/v3.0.0) . Your schema must follow the AsyncAPI specification 3.0+. To make sure your AsyncAPI schema is valid, you can paste it into the [AsyncAPI Studio](https://studio.asyncapi.com/) [​](https://mintlify.com/docs/api-playground/asyncapi/setup#auto-populate-websockets-pages) Auto-populate websockets pages ----------------------------------------------------------------------------------------------------------------------------- You can add an `asyncapi` field to any tab or group in the navigation of your `docs.json`. This field can contain either the path to an AsyncAPI schema document in your docs repo, the URL of a hosted AsyncAPI schema document, or an array of links to AsyncAPI schema documents. Mintlify will automatically generate a page for each AsyncAPI websocket channel. **Examples with Tabs:** Local File Remote URL Copy Ask AI "navigation": { "tabs": [\ {\ "tab": "API Reference",\ "asyncapi": "/path/to/asyncapi.json"\ }\ ] } **Examples with Groups:** Copy Ask AI "navigation": { "tabs": [\ {\ "tab": "AsyncAPI",\ "groups": [\ {\ "group": "Websockets",\ "asyncapi": {\ "source": "/path/to/asyncapi.json",\ "directory": "api-reference"\ }\ }\ ]\ }\ ] } The directory field is optional. If not specified, the files will be placed in the **api-reference** folder of the docs repo. [​](https://mintlify.com/docs/api-playground/asyncapi/setup#channel-page) Channel page ----------------------------------------------------------------------------------------- If you want more control over how you order your channels or if you want to just reference a single channel, you can create an MDX file with the `asyncapi` field in the frontmatter. Copy Ask AI --- title: "Websocket Channel" asyncapi: "/path/to/asyncapi.json channelName" --- Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-playground/customization/multiple-responses) [PlaygroundEnable users to interact with your websockets\ \ Next](https://mintlify.com/docs/api-playground/asyncapi/playground) On this page * [Add an AsyncAPI specification file](https://mintlify.com/docs/api-playground/asyncapi/setup#add-an-asyncapi-specification-file) * [Auto-populate websockets pages](https://mintlify.com/docs/api-playground/asyncapi/setup#auto-populate-websockets-pages) * [Channel page](https://mintlify.com/docs/api-playground/asyncapi/setup#channel-page) Assistant Responses are generated using AI and may contain mistakes. --- # Vercel - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Custom Subdirectory Vercel [​](https://mintlify.com/docs/advanced/subpath/vercel#vercel-json-configuration) vercel.json Configuration ------------------------------------------------------------------------------------------------------------- To host your documentation at a custom subpath using Vercel, you need to add the following configuration to your `vercel.json` file. Copy Ask AI { "rewrites": [\ {\ "source": "/docs",\ "destination": "https://[subdomain].mintlify.dev/docs"\ },\ {\ "source": "/docs/:match*",\ "destination": "https://[subdomain].mintlify.dev/docs/:match*"\ }\ ] } For more information, you can also refer to Vercel’s offical guide on rewrites: [Project Configuration: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) Was this page helpful? YesNo [Previous](https://mintlify.com/docs/advanced/subpath/route53-cloudfront) [Single sign-on (SSO)Customize how your team can login to your admin dashboard\ \ Next](https://mintlify.com/docs/advanced/dashboard/sso) On this page * [vercel.json Configuration](https://mintlify.com/docs/advanced/subpath/vercel#vercel-json-configuration) Assistant Responses are generated using AI and may contain mistakes. --- # Authentication - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation MDX Authentication [​](https://mintlify.com/docs/api-playground/mdx/authentication#enabling-authentication) Enabling authentication ------------------------------------------------------------------------------------------------------------------- You can add an authentication method to your `docs.json` to enable it globally on every page or you can set it on a per-page basis. A page’s authentication method will override a global method if both are set. ### [​](https://mintlify.com/docs/api-playground/mdx/authentication#bearer-token) Bearer token docs.json Page Metadata Copy Ask AI "api": { "mdx": { "auth": { "method": "bearer" } } } ### [​](https://mintlify.com/docs/api-playground/mdx/authentication#basic-authentication) Basic authentication docs.json Page Metadata Copy Ask AI "api": { "mdx": { "auth": { "method": "basic" } } } ### [​](https://mintlify.com/docs/api-playground/mdx/authentication#api-key) API key docs.json Page Metadata Copy Ask AI "api": { "mdx": { "auth": { "method": "key", "name": "x-api-key" } } } ### [​](https://mintlify.com/docs/api-playground/mdx/authentication#none) None The “none” authentication method is useful to disable authentication on a specific endpoint after setting a default in docs.json. Page Metadata Copy Ask AI --- title: "Your page title" authMethod: "none" --- Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-playground/mdx/configuration) [TroubleshootingCommon issues with API References\ \ Next](https://mintlify.com/docs/api-playground/troubleshooting) On this page * [Enabling authentication](https://mintlify.com/docs/api-playground/mdx/authentication#enabling-authentication) * [Bearer token](https://mintlify.com/docs/api-playground/mdx/authentication#bearer-token) * [Basic authentication](https://mintlify.com/docs/api-playground/mdx/authentication#basic-authentication) * [API key](https://mintlify.com/docs/api-playground/mdx/authentication#api-key) * [None](https://mintlify.com/docs/api-playground/mdx/authentication#none) Assistant Responses are generated using AI and may contain mistakes. --- # Adding SDK examples - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Customization Adding SDK examples If your users interact with your API using an SDK rather than directly through a network request, you can use the `x-codeSamples` extension to add code samples to your OpenAPI document and display them in your OpenAPI pages. This property can be added to any request method and has the following schema. [​](https://mintlify.com/docs/api-playground/customization/adding-sdk-examples#param-lang) lang string required The language of the code sample. [​](https://mintlify.com/docs/api-playground/customization/adding-sdk-examples#param-label) label string The label for the sample. This is useful when providing multiple examples for a single endpoint. [​](https://mintlify.com/docs/api-playground/customization/adding-sdk-examples#param-source) source string required The source code of the sample. Here is an example of code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK. Copy Ask AI paths: /plants: get: # ... x-codeSamples: - lang: bash label: List all unwatered plants source: | planter list -u - lang: javascript label: List all unwatered plants source: | const planter = require('planter'); planter.list({ unwatered: true }); - lang: bash label: List all potted plants source: | planter list -p - lang: javascript label: List all potted plants source: | const planter = require('planter'); planter.list({ potted: true }); Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-playground/customization/complex-data-types) [Managing page visibilityControl which endpoints from your OpenAPI specification appear in your documentation navigation\ \ Next](https://mintlify.com/docs/api-playground/customization/managing-page-visibility) Assistant Responses are generated using AI and may contain mistakes. --- # Playground - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation API pages Playground [​](https://mintlify.com/docs/api-playground/overview#overview) Overview --------------------------------------------------------------------------- The API playground is an interactive environment that lets users test and explore your API endpoints. Developers can craft API requests, submit them, and view responses without leaving your documentation. The playground is automatically generated from your OpenAPI specification or AsyncAPI schema so any updates to your API are automatically reflected in the playground. You can also manually create API reference pages after defining a base URL and authentication method in your `docs.json`. We recommend generating your API playground from an OpenAPI specification. See [OpenAPI Setup](https://mintlify.com/docs/api-playground/openapi-setup) for more information on creating your OpenAPI document. [​](https://mintlify.com/docs/api-playground/overview#getting-started) Getting started ----------------------------------------------------------------------------------------- 1 Add your OpenAPI specification file. Make sure that your OpenAPI specification file is valid using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint) . Copy Ask AI /your-project |- docs.json |- openapi.json 2 Configure \`docs.json\`. Update your `docs.json` to reference your OpenAPI specification. You can add an `openapi` property to any navigation element to auto-populate your docs with a page for each endpoint specified in your OpenAPI document. In this example, Mintlify will generate a page for each endpoint specified in `openapi.json` and organize them under the “API reference” group in your navigation. Copy Ask AI { "navigation": [\ {\ "group": "API reference",\ "openapi": "openapi.json"\ }\ ] } [​](https://mintlify.com/docs/api-playground/overview#customizing-your-playground) Customizing your playground ----------------------------------------------------------------------------------------------------------------- You can customize your API playground by defining the following properties in your `docs.json`. [​](https://mintlify.com/docs/api-playground/overview#param-playground) playground object Configurations for the API playground. Hide playground [​](https://mintlify.com/docs/api-playground/overview#param-display) display "interactive" | "simple" | "none" The display mode of the API playground. * `"interactive"`: Display the interactive playground. * `"simple"`: Display a copyable endpoint with no playground. * `"none"`: Display nothing. Defaults to `interactive`. [​](https://mintlify.com/docs/api-playground/overview#param-proxy) proxy boolean Whether to pass API requests through a proxy server. Defaults to `true`. [​](https://mintlify.com/docs/api-playground/overview#param-examples) examples object Configurations for the autogenerated API examples. Hide examples [​](https://mintlify.com/docs/api-playground/overview#param-languages) languages array of string Example languages for the autogenerated API snippets. Languages display in the order specified. [​](https://mintlify.com/docs/api-playground/overview#param-defaults) defaults "required" | "all" Whether to show optional parameters in API examples. Defaults to `all`. ### [​](https://mintlify.com/docs/api-playground/overview#example-configuration) Example configuration Copy Ask AI { "api": { "playground": { "display": "interactive" }, "examples": { "languages": ["curl", "python", "javascript"], "defaults": "required" } } } This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. Only required parameters are shown in the code snippets. ### [​](https://mintlify.com/docs/api-playground/overview#custom-mdx-pages) Custom `MDX` pages When you need more control over your API documentation, create individual `MDX` pages for your endpoints. This allows you to: * Customize page metadata * Add additional content like examples * Hide specific operations * Reorder pages in your navigation * Control playground behavior per page See [MDX Setup](https://mintlify.com/docs/api-playground/mdx/configuration) for more information on creating individual pages for your API endpoints. [​](https://mintlify.com/docs/api-playground/overview#further-reading) Further reading ----------------------------------------------------------------------------------------- * [AsyncAPI Setup](https://mintlify.com/docs/api-playground/asyncapi/setup) for more information on creating your AsyncAPI schema to generate WebSocket reference pages. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/update) [OpenAPI setupReference OpenAPI endpoints in your docs pages\ \ Next](https://mintlify.com/docs/api-playground/openapi-setup) On this page * [Overview](https://mintlify.com/docs/api-playground/overview#overview) * [Getting started](https://mintlify.com/docs/api-playground/overview#getting-started) * [Customizing your playground](https://mintlify.com/docs/api-playground/overview#customizing-your-playground) * [Example configuration](https://mintlify.com/docs/api-playground/overview#example-configuration) * [Custom MDX pages](https://mintlify.com/docs/api-playground/overview#custom-mdx-pages) * [Further reading](https://mintlify.com/docs/api-playground/overview#further-reading) Assistant Responses are generated using AI and may contain mistakes. --- # Cloudflare - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Custom Subdirectory Cloudflare To host your documentation at a `/docs` subpath using Cloudflare, you will need to create and configure a Cloudflare Worker. Before you begin, you need a Cloudflare account and a domain name (can be managed on or off Cloudflare). [​](https://mintlify.com/docs/advanced/subpath/cloudflare#set-up-a-cloudflare-worker) Set up a Cloudflare Worker ------------------------------------------------------------------------------------------------------------------- Create a Cloudflare Worker by following the [Cloudflare Workers getting started guide](https://developers.cloudflare.com/workers/get-started/dashboard/) , if you have not already. If your DNS provider is Cloudflare, do not use proxying for the CNAME record. ### [​](https://mintlify.com/docs/advanced/subpath/cloudflare#configure-routing) Configure routing In your Cloudflare dashboard, select **Edit Code** and add the following script into your Worker’s code. See the [Cloudflare documentation](https://developers.cloudflare.com/workers-ai/get-started/dashboard/#development) for more information on editing a Worker. Replace `[SUBDOMAIN]` with your unique subdomain and `[YOUR_DOMAIN]` with your website’s base URL. Copy Ask AI addEventListener("fetch", (event) => { event.respondWith(handleRequest(event.request)); }); async function handleRequest(request) { try { const urlObject = new URL(request.url); // If the request is to the docs subdirectory if (/^\/docs/.test(urlObject.pathname)) { // Then Proxy to Mintlify const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; const CUSTOM_URL = "[YOUR_DOMAIN]"; let url = new URL(request.url); url.hostname = DOCS_URL; let proxyRequest = new Request(url, request); proxyRequest.headers.set("Host", DOCS_URL); proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL); proxyRequest.headers.set("X-Forwarded-Proto", "https"); return await fetch(proxyRequest); } } catch (error) { // if no action found, play the regular request return await fetch(request); } } Select **Deploy** and wait for the changes to propagate. After configuring your DNS, custom subdomains are usually available within a few minutes. DNS propagation can sometimes take 1-4 hours, and in rare cases up to 48 hours. If your subdomain is not immediately available, please wait before troubleshooting. ### [​](https://mintlify.com/docs/advanced/subpath/cloudflare#test-your-worker) Test your Worker After your code deploys, test your Worker to ensure it routes to your Mintlify docs. 1. Test using the Worker’s preview URL: `your-worker.your-subdomain.workers.dev/docs` 2. Verify the Worker routes to your Mintlify docs and your website. ### [​](https://mintlify.com/docs/advanced/subpath/cloudflare#add-custom-domain) Add custom domain 1. In your [Cloudflare dashboard](https://dash.cloudflare.com/) , navigate to your Worker. 2. Go to **Settings > Domains & Routes > Add > Custom Domain**. 3. Add your domain. We recommend you add your domain both with and without `www.` prepended. See [Add a custom domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/#add-a-custom-domain) in the Cloudflare documentation for more information. ### [​](https://mintlify.com/docs/advanced/subpath/cloudflare#resolve-dns-conflicts) Resolve DNS conflicts If your domain already points to another service, you must remove the existing DNS record. Your Cloudflare Worker must be configured to control all traffic for your domain. 1. Delete the existing DNS record for your domain. See [Delete DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#delete-dns-records) in the Cloudflare documentation for more information. 2. Return to your Worker and add your custom domain. [​](https://mintlify.com/docs/advanced/subpath/cloudflare#webflow-custom-routing) Webflow custom routing ----------------------------------------------------------------------------------------------------------- If you use Webflow to host your main site and want to serve Mintlify docs at `/docs` on the same domain, you’ll need to configure custom routing through Cloudflare Workers to proxy all non-docs traffic to your main site. Make sure your main site is set up on a landing page before deploying this Worker, or visitors to your main site will see errors. 1. In Webflow, set up a landing page for your main site like `landing.yoursite.com`. This will be the page that visitors see when they visit your site. 2. Deploy your main site to the landing page. This ensures that your main site remains accessible while you configure the Worker. 3. To avoid conflicts, update any absolute URLs in your main site to be relative. 4. In Cloudflare, select **Edit Code** and add the following script into your Worker’s code. Replace `[SUBDOMAIN]` with your unique subdomain, `[YOUR_DOMAIN]` with your website’s base URL, and `[LANDING_DOMAIN]` with your landing page URL. Copy Ask AI addEventListener("fetch", (event) => { event.respondWith(handleRequest(event.request)); }); async function handleRequest(request) { try { const urlObject = new URL(request.url); // If the request is to the docs subdirectory if (/^\/docs/.test(urlObject.pathname)) { // Proxy to Mintlify const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; const CUSTOM_URL = "[YOUR_DOMAIN]"; let url = new URL(request.url); url.hostname = DOCS_URL; let proxyRequest = new Request(url, request); proxyRequest.headers.set("Host", DOCS_URL); proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL); proxyRequest.headers.set("X-Forwarded-Proto", "https"); return await fetch(proxyRequest); } // Route everything else to main site const MAIN_SITE_URL = "[LANDING_DOMAIN]"; if (MAIN_SITE_URL && MAIN_SITE_URL !== "[LANDING_DOMAIN]") { let mainSiteUrl = new URL(request.url); mainSiteUrl.hostname = MAIN_SITE_URL; return await fetch(mainSiteUrl, { method: request.method, headers: request.headers, body: request.body }); } } catch (error) { // If no action found, serve the regular request return await fetch(request); } } 5. Select **Deploy** and wait for the changes to propagate. After configuring your DNS, custom subdomains are usually available within a few minutes. DNS propagation can sometimes take 1-4 hours, and in rare cases up to 48 hours. If your subdomain is not immediately available, please wait before troubleshooting. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/guides/monorepo) [AWSHost documentation at a /docs subdirectory using AWS services\ \ Next](https://mintlify.com/docs/advanced/subpath/route53-cloudfront) On this page * [Set up a Cloudflare Worker](https://mintlify.com/docs/advanced/subpath/cloudflare#set-up-a-cloudflare-worker) * [Configure routing](https://mintlify.com/docs/advanced/subpath/cloudflare#configure-routing) * [Test your Worker](https://mintlify.com/docs/advanced/subpath/cloudflare#test-your-worker) * [Add custom domain](https://mintlify.com/docs/advanced/subpath/cloudflare#add-custom-domain) * [Resolve DNS conflicts](https://mintlify.com/docs/advanced/subpath/cloudflare#resolve-dns-conflicts) * [Webflow custom routing](https://mintlify.com/docs/advanced/subpath/cloudflare#webflow-custom-routing) Assistant Responses are generated using AI and may contain mistakes. --- # Managing page visibility - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Customization Managing page visibility You can control which OpenAPI operations get published as documentation pages and their visibility in navigation. This is useful for internal-only endpoints, deprecated operations, beta features, or endpoints that should be accessible via direct URL but not discoverable through site navigation. If your pages are autogenerated from an OpenAPI document, you can manage page visibility with the `x-hidden` and `x-excluded` extensions. [​](https://mintlify.com/docs/api-playground/customization/managing-page-visibility#x-hidden) `x-hidden` ----------------------------------------------------------------------------------------------------------- The `x-hidden` extension creates a page for an endpoint, but hides it from navigation. The page is only accessible by navigating directly to its URL. Common use cases for `x-hidden` are: * Endpoints you want to document, but not promote. * Pages that you will link to from other content. * Endpoints for specific users. [​](https://mintlify.com/docs/api-playground/customization/managing-page-visibility#x-excluded) `x-excluded` --------------------------------------------------------------------------------------------------------------- The `x-excluded` extension completely excludes an endpoint from your documentation. Common use cases for `x-excluded` are: * Internal-only endpoints. * Deprecated endpoints that you don’t want to document. * Beta features that are not ready for public documentation. [​](https://mintlify.com/docs/api-playground/customization/managing-page-visibility#implementation) Implementation --------------------------------------------------------------------------------------------------------------------- Add the `x-hidden` or `x-excluded` extension under the HTTP method in your OpenAPI specification. Here are examples of how to use each property in an OpenAPI schema document for an endpoint and a webhook path. Copy Ask AI "paths": { "/plants": { "get": { "description": "Returns all plants from the store", "parameters": { /*...*/ }, "responses": { /*...*/ } } }, "/hidden_plants": { "get": { "x-hidden": true, "description": "Returns all somewhat secret plants from the store", "parameters": { /*...*/ }, "responses": { /*...*/ } } }, "/secret_plants": { "get": { "x-excluded": true, "description": "Returns all top secret plants from the store (do not publish this endpoint!)", "parameters": { /*...*/ }, "responses": { /*...*/ } } } }, Copy Ask AI "webhooks": { "/plants_hook": { "post": { "description": "Webhook for information about a new plant added to the store", } }, "/hidden_plants_hook": { "post": { "x-hidden": true, "description": "Webhook for somewhat secret information about a new plant added to the store" } }, "/secret_plants_hook": { "post": { "x-excluded": true, "description": "Webhook for top secret information about a new plant added to the store (do not publish this endpoint!)" } } } Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-playground/customization/adding-sdk-examples) [Multiple responsesShow response variations for the same endpoint\ \ Next](https://mintlify.com/docs/api-playground/customization/multiple-responses) On this page * [x-hidden](https://mintlify.com/docs/api-playground/customization/managing-page-visibility#x-hidden) * [x-excluded](https://mintlify.com/docs/api-playground/customization/managing-page-visibility#x-excluded) * [Implementation](https://mintlify.com/docs/api-playground/customization/managing-page-visibility#implementation) Assistant Responses are generated using AI and may contain mistakes. --- # Multiple responses - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Customization Multiple responses If your API returns different responses based on input parameters, user context, or other conditions of the request, you can document multiple response examples with the `examples` property. This property can be added to any response and has the following schema. Copy Ask AI responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/YourResponseSchema" examples: us: summary: Response for United States value: countryCode: "US" currencyCode: "USD" taxRate: 0.0825 gb: summary: Response for United Kingdom value: countryCode: "GB" currencyCode: "GBP" taxRate: 0.20 Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-playground/customization/managing-page-visibility) [AsyncAPI setupCreate websocket reference pages with AsyncAPI\ \ Next](https://mintlify.com/docs/api-playground/asyncapi/setup) Assistant Responses are generated using AI and may contain mistakes. --- # Complex data types - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Customization Complex data types When your API accepts multiple data formats, has conditional fields, or uses inheritance patterns, OpenAPI’s schema composition keywords help you document these flexible structures. Using `oneOf`, `anyOf`, and `allOf`, you can describe APIs that handle different input types or combine multiple schemas into comprehensive data models. [​](https://mintlify.com/docs/api-playground/customization/complex-data-types#oneof%2C-anyof%2C-allof-keywords) `oneOf`, `anyOf`, `allOf` keywords ----------------------------------------------------------------------------------------------------------------------------------------------------- For complex data types, OpenAPI provides keywords for combining schemas: * `allOf`: Combines multiple schemas (like merging objects or extending a base schema). Functions like an `and` operator. * `anyOf`: Accepts data matching any of the provided schemas. Functions like an `or` operator. * `oneOf`: Accepts data matching exactly one of the provided schemas. Functions like an `exclusive-or` operator. Mintlify treats `oneOf` and `anyOf` identically since the practical difference rarely affects using the API. For detailed specifications of these keywords see the [OpenAPI documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/) . The `not` keyword is currently unsupported. ### [​](https://mintlify.com/docs/api-playground/customization/complex-data-types#combining-schemas-with-allof) Combining schemas with `allOf` When you use `allOf`, Mintlify performs some preprocessing on your OpenAPI document to display complex combinations in a readable way. For example, when you combine two object schemas with `allOf`, Mintlify combines the properties of both into a single object. This becomes especially useful when leveraging OpenAPI’s reusable [components](https://swagger.io/docs/specification/components/) . Copy Ask AI org_with_users: allOf: - $ref: '#/components/schemas/Org' - type: object properties: users: type: array description: An array containing all users in the organization # ... components: schemas: Org: type: object properties: id: type: string description: The ID of the organization [​](https://mintlify.com/docs/api-playground/customization/complex-data-types#param-org-with-users) org\_with\_users object Show child attributes [​](https://mintlify.com/docs/api-playground/customization/complex-data-types#param-id) id string The ID of the organization [​](https://mintlify.com/docs/api-playground/customization/complex-data-types#param-users) users object\[\] An array containing all users in the organization ### [​](https://mintlify.com/docs/api-playground/customization/complex-data-types#providing-options-with-oneof-and-anyof) Providing options with `oneOf` and `anyOf` When you use `oneOf` or `anyOf`, the options are displayed in a tabbed container. Specify a `title` field in each subschema to give your options names. For example, here’s how you might display two different types of delivery addresses: Copy Ask AI delivery_address: oneOf: - title: StreetAddress type: object properties: address_line_1: type: string description: The street address of the recipient # ... - title: POBox type: object properties: box_number: type: string description: The number of the PO Box # ... [​](https://mintlify.com/docs/api-playground/customization/complex-data-types#param-delivery-address) delivery\_address object * StreetAddress * POBox [​](https://mintlify.com/docs/api-playground/customization/complex-data-types#param-address-line-1) address\_line\_1 string The street address of the residence [​](https://mintlify.com/docs/api-playground/customization/complex-data-types#param-address-line-1) address\_line\_1 string The street address of the residence [​](https://mintlify.com/docs/api-playground/customization/complex-data-types#param-box-number) box\_number string The number of the PO Box Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-playground/openapi-setup) [Adding SDK examplesDisplay language-specific code samples alongside your API endpoints to show developers how to use your SDKs\ \ Next](https://mintlify.com/docs/api-playground/customization/adding-sdk-examples) On this page * [oneOf, anyOf, allOf keywords](https://mintlify.com/docs/api-playground/customization/complex-data-types#oneof%2C-anyof%2C-allof-keywords) * [Combining schemas with allOf](https://mintlify.com/docs/api-playground/customization/complex-data-types#combining-schemas-with-allof) * [Providing options with oneOf and anyOf](https://mintlify.com/docs/api-playground/customization/complex-data-types#providing-options-with-oneof-and-anyof) Assistant Responses are generated using AI and may contain mistakes. --- # Troubleshooting - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation API pages Troubleshooting If your API pages aren’t displaying correctly, check these common configuration issues: All of my OpenAPI pages are completely blank In this scenario, it’s likely that either Mintlify cannot find your OpenAPI document, or your OpenAPI document is invalid. Running `mint dev` locally should reveal some of these issues. To verify your OpenAPI document will pass validation: 1. Visit [this validator](https://editor.swagger.io/) 2. Switch to the “Validate text” tab 3. Paste in your OpenAPI document 4. Click “Validate it!” If the text box that appears below has a green border, your document has passed validation. This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document passes validation here, there’s a great chance the problem is elsewhere. Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification, you could encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) (under Edit > Convert to OpenAPI 3): One of my OpenAPI pages is completely blank This is usually caused by a misspelled `openapi` field in the page metadata. Make sure the HTTP method and path match the HTTP method and path in the OpenAPI document exactly. Here’s an example of how things might go wrong: get-user.mdx Copy Ask AI --- openapi: "GET /users/{id}/" --- openapi.yaml Copy Ask AI paths: "/users/{id}": get: ... Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI document does not. Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document in the `openapi` field, ensure the filename is correct. For example, if you have two OpenAPI documents `openapi/v1.json` and `openapi/v2.json`, your metadata might look like this: api-reference/v1/users/get-user.mdx Copy Ask AI --- openapi: "v1 GET /users/{id}" --- Requests from the API Playground don't work If you have a custom domain configured, this could be an issue with your reverse proxy. By default, requests made via the API Playground start with a `POST` request to the `/api/request` path on the docs site. If your reverse proxy is configured to only allow `GET` requests, then all of these requests will fail. To fix this, configure your reverse proxy to allow `POST` requests to the `/api/request` path. Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure Mintlify to send requests directly to your backend with the `api.playground.proxy` setting in the `docs.json`, as described in the [settings documentation](https://mintlify.com/docs/settings#param-proxy) . When using this configuration, you will need to configure CORS on your server since requests will come directly from users’ browsers rather than through your proxy. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-playground/mdx/authentication) [OverviewControl who sees your documentation and customize their experience\ \ Next](https://mintlify.com/docs/authentication-personalization/overview) Assistant Responses are generated using AI and may contain mistakes. --- # Partial authentication setup - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Authentication and personalization Partial authentication setup Partial authentication lets you protect private documentation while keeping other pages publicly viewable. Users can browse public content freely and authenticate only when accessing protected pages. Partial authentication shares all the same features as authentication, but with the ability to allow unauthenticated users to view certain pages. [​](https://mintlify.com/docs/authentication-personalization/partial-authentication-setup#setup) Setup --------------------------------------------------------------------------------------------------------- Follow the [Authentication Setup](https://mintlify.com/docs/authentication-personalization/authentication-setup) guide and select **Partial Authentication** when configuring your chosen handshake method. [​](https://mintlify.com/docs/authentication-personalization/partial-authentication-setup#making-pages-public) Making pages public ------------------------------------------------------------------------------------------------------------------------------------- By default, all pages are protected. Add the `public` property to the page’s frontmatter to make it viewable without authentication: Copy Ask AI --- title: "My Page" public: true --- Was this page helpful? YesNo [Previous](https://mintlify.com/docs/authentication-personalization/authentication-setup) [Personalization setupLet users log in for customized documentation experiences\ \ Next](https://mintlify.com/docs/authentication-personalization/personalization-setup) On this page * [Setup](https://mintlify.com/docs/authentication-personalization/partial-authentication-setup#setup) * [Making pages public](https://mintlify.com/docs/authentication-personalization/partial-authentication-setup#making-pages-public) Assistant Responses are generated using AI and may contain mistakes. --- # OpenAPI setup - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation API pages OpenAPI setup OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0+ documents to generate interactive API documentation and keep it up to date. [​](https://mintlify.com/docs/api-playground/openapi-setup#add-an-openapi-specification-file) Add an OpenAPI specification file ---------------------------------------------------------------------------------------------------------------------------------- To document your endpoints with OpenAPI, you need a valid OpenAPI document in either JSON or YAML format that follows the [OpenAPI specification 3.0+](https://swagger.io/specification/) . ### [​](https://mintlify.com/docs/api-playground/openapi-setup#describing-your-api) Describing your API We recommend the following resources to learn about and construct your OpenAPI documents. * [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. * [Swagger Editor](https://editor.swagger.io/) to edit, validate, and debug your OpenAPI document. * [The Mint CLI](https://www.npmjs.com/package/mint) to validate your OpenAPI document with the command: `mint openapi-check `. Swagger’s OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1. 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. ### [​](https://mintlify.com/docs/api-playground/openapi-setup#specifying-the-url-for-your-api) Specifying the URL for your API To enable Mintlify features like the API playground, add a `servers` field to your OpenAPI document with your API’s base URL. Copy Ask AI { "servers": [\ {\ "url": "https://api.example.com/v1"\ }\ ] } In an OpenAPI document, different API endpoints are specified by their paths, like `/users/{id}` or simply `/`. The base URL defines where these paths should be appended. For more information on how to configure the `servers` field, see [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) in the OpenAPI documentation. The API playground uses these server URLs to determine where to send requests. If you specify multiple servers, a dropdown will allow users to toggle between servers. If you do not specify a server, the API playground will use simple mode since it cannot send requests without a base URL. If your API has endpoints that exist at different URLs, you can [override the server field](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) for a given path or operation. ### [​](https://mintlify.com/docs/api-playground/openapi-setup#specifying-authentication) Specifying authentication To enable authentication in your API documentation and playground, configure the `securitySchemes` and `security` fields in your OpenAPI document. The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document. 1 Define your authentication method. Add a `securitySchemes` field to define how users authenticate. This example shows a configuration for bearer authentication. Copy Ask AI { "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } } 2 Apply authentication to your endpoints. Add a `security` field to require authentication. Copy Ask AI { "security": [\ {\ "bearerAuth": []\ }\ ] } 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. For more information on defining and applying authentication, see [Authentication](https://swagger.io/docs/specification/authentication/) in the OpenAPI documentation. [​](https://mintlify.com/docs/api-playground/openapi-setup#auto-populate-api-pages) Auto-populate API pages -------------------------------------------------------------------------------------------------------------- You can add an `openapi` field to any navigation element in your `docs.json` to auto-populate your docs with a page for each specified endpoint. The `openapi` field can contain the path to an OpenAPI document in your docs repo or the URL of a hosted OpenAPI document. The metadata for the generated pages will have the following default values: * `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint. * `description`: The `description` field from the OpenAPI operation, if present. * `version`: The `version` value from the anchor or tab, if present. * `deprecated`: The `deprecated` field from the OpenAPI operation, if present. If `true`, a deprecated label will appear next to the endpoint title in the side navigation and on the endpoint page. If you have some endpoints in your OpenAPI schema that you want to exclude from your auto-populated API pages, add the [x-hidden](https://mintlify.com/docs/api-playground/customization/managing-page-visibility#x-hidden) property to the endpoint. ### [​](https://mintlify.com/docs/api-playground/openapi-setup#example-with-navigation-tabs) Example with navigation tabs Copy Ask AI "navigation": { "tabs": [\ {\ "tab": "API Reference",\ "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"\ }\ ] } ### [​](https://mintlify.com/docs/api-playground/openapi-setup#example-with-navigation-groups) Example with navigation groups Copy Ask AI "navigation": { "tabs": [\ {\ "tab": "API Reference",\ "groups": [\ {\ "group": "Endpoints",\ "openapi": {\ "source": "/path/to/openapi-1.json",\ "directory": "api-reference"\ }\ }\ ]\ }\ ] } The directory field is optional. If not specified, the files will be placed in the `api-reference` directory of the docs repo. [​](https://mintlify.com/docs/api-playground/openapi-setup#create-mdx-files-for-api-pages) Create `MDX` files for API pages ------------------------------------------------------------------------------------------------------------------------------ If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you can create `MDX` pages for each operation. See an [example MDX OpenAPI page from MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) and how it appears in their [live documentation](https://docs.mindsdb.com/rest/databases/create-databases) . ### [​](https://mintlify.com/docs/api-playground/openapi-setup#manually-specify-files) Manually specify files Create an `MDX` page for each endpoint and specify which OpenAPI operation to display using the `openapi` field in the frontmatter. When you reference an OpenAPI operation this way, the name, description, parameters, responses, and API playground are automatically generated from your OpenAPI document. If you have multiple OpenAPI files, include the file path in your reference to ensure Mintlify finds the correct OpenAPI document. If you have only one OpenAPI file, Mintlify will detect it automatically. If you want to reference an external OpenAPI file, add the file’s URL to your `docs.json`. Example Format Copy Ask AI --- title: "Get users" description: "Returns all plants from the system that the user has access to" openapi: "/path/to/openapi-1.json GET /users" deprecated: true version: "1.0" --- The method and path must exactly match the definition in your OpenAPI specification. If the endpoint doesn’t exist in the OpenAPI file, the page will be empty. ### [​](https://mintlify.com/docs/api-playground/openapi-setup#autogenerate-mdx-files) Autogenerate `MDX` files Use our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) to autogenerate `MDX` pages for large OpenAPI documents. Your OpenAPI document must be valid or the files will not autogenerate. The scraper generates: * An `MDX` page for each operation in the `paths` field of your OpenAPI document. * If your OpenAPI document is version 3.1+, an `MDX` page for each operation in the `webhooks` field of your OpenAPI document. * An array of navigation entries that you can add to your `docs.json`. 1 Generate \`MDX\` files. Copy Ask AI npx @mintlify/scraping@latest openapi-file 2 Specify an output folder. Copy Ask AI npx @mintlify/scraping@latest openapi-file -o api-reference 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. ### [​](https://mintlify.com/docs/api-playground/openapi-setup#create-mdx-files-for-openapi-schemas) Create `MDX` files for OpenAPI schemas You can create individual pages for any OpenAPI schema defined in an OpenAPI document’s `components.schema` field: Example Format Copy Ask AI --- openapi-schema: OrderItem --- [​](https://mintlify.com/docs/api-playground/openapi-setup#webhooks) Webhooks -------------------------------------------------------------------------------- Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. Webhooks are supported in OpenAPI 3.1+ documents. ### [​](https://mintlify.com/docs/api-playground/openapi-setup#define-webhooks-in-your-openapi-specification) Define webhooks in your OpenAPI specification Add a `webhooks` field to your OpenAPI document alongside the `paths` field. For more information on defining webhooks, see [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks) in the OpenAPI documentation. ### [​](https://mintlify.com/docs/api-playground/openapi-setup#reference-webhooks-in-mdx-files) Reference webhooks in MDX files When creating MDX pages for webhooks, use `webhook` instead of HTTP methods like `GET` or `POST`: Copy Ask AI --- title: "Example webhook" description: "Triggered when an event occurs" openapi: "path/to/openapi-file webhook example-webhook-name" --- The webhook name must exactly match the key defined in your OpenAPI specification’s `webhooks` field. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-playground/overview) [Complex data typesDescribe APIs with flexible schemas, optional properties, and multiple data formats using \`oneOf\`, \`anyOf\`, and \`allOf\` keywords\ \ Next](https://mintlify.com/docs/api-playground/customization/complex-data-types) On this page * [Add an OpenAPI specification file](https://mintlify.com/docs/api-playground/openapi-setup#add-an-openapi-specification-file) * [Describing your API](https://mintlify.com/docs/api-playground/openapi-setup#describing-your-api) * [Specifying the URL for your API](https://mintlify.com/docs/api-playground/openapi-setup#specifying-the-url-for-your-api) * [Specifying authentication](https://mintlify.com/docs/api-playground/openapi-setup#specifying-authentication) * [Auto-populate API pages](https://mintlify.com/docs/api-playground/openapi-setup#auto-populate-api-pages) * [Example with navigation tabs](https://mintlify.com/docs/api-playground/openapi-setup#example-with-navigation-tabs) * [Example with navigation groups](https://mintlify.com/docs/api-playground/openapi-setup#example-with-navigation-groups) * [Create MDX files for API pages](https://mintlify.com/docs/api-playground/openapi-setup#create-mdx-files-for-api-pages) * [Manually specify files](https://mintlify.com/docs/api-playground/openapi-setup#manually-specify-files) * [Autogenerate MDX files](https://mintlify.com/docs/api-playground/openapi-setup#autogenerate-mdx-files) * [Create MDX files for OpenAPI schemas](https://mintlify.com/docs/api-playground/openapi-setup#create-mdx-files-for-openapi-schemas) * [Webhooks](https://mintlify.com/docs/api-playground/openapi-setup#webhooks) * [Define webhooks in your OpenAPI specification](https://mintlify.com/docs/api-playground/openapi-setup#define-webhooks-in-your-openapi-specification) * [Reference webhooks in MDX files](https://mintlify.com/docs/api-playground/openapi-setup#reference-webhooks-in-mdx-files) Assistant Responses are generated using AI and may contain mistakes. --- # Overview - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Authentication and personalization Overview Authentication methods are available on the [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication) . There are three approaches to manage access and customize your documentation based on user information. * **Authentication**: Complete privacy protection for all content with full content customization. * **Partial authentication**: Page-by-page access control with full content customization. * **Personalization**: Content customization with **no security guarantees**. All content remains publicly accessible. **Choose authentication** if you need complete security and privacy for all your documentation, including pages, images, search results, and AI assistant features. **Choose partial authentication** if you want some pages to be public and others private. **Choose personalization** if you want to customize content based on user information and your documentation can be publicly accessible. [​](https://mintlify.com/docs/authentication-personalization/overview#handshake-methods) Handshake methods ------------------------------------------------------------------------------------------------------------- Authentication and personalization offer multiple handshake methods for controlling access to your content. ### [​](https://mintlify.com/docs/authentication-personalization/overview#available-for-all-methods) Available for all methods **JSON Web Token (JWT)**: Custom system where you manage user tokens with full control over the login flow. * Pros of JWT: * Reduced risk of API endpoint abuse. * No CORS configuration. * No restrictions on API URLs. * Cons of JWT: * Must be compatible with your existing login flow. * Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately. * When you refresh user data, users must log into your docs again. If your users’ data changes frequently, they must log in frequently or risk having stale data in your docs. **OAuth 2.0**: Third-party login integration like Google, GitHub, or other OAuth providers. * Pros of OAuth 2.0: * Heightened security standard. * No restrictions on API URLs. * Cons of OAuth 2.0: * Requires significant work if setting up an OAuth server for the first time. * Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately. ### [​](https://mintlify.com/docs/authentication-personalization/overview#available-for-authentication-and-partial-authentication) Available for authentication and partial authentication **Mintlify dashboard**: Allow all of your dashboard users to access your docs. * Pros of Mintlify dashboard: * No configuration required. * Enables private preview deployments, restricting access to authenticated users only. * Cons of Mintlify dashboard: * Requires all users of your docs to have an account in your Mintlify dashboard. **Password**: Shared access with a single global password. Used for access control only. Does not allow for personalization. * Pros of password: * Simple setup with no configuration required to add new users, just share the password. * Cons of password: * Lose personalization features since there is no way to differentiate users with the same password. * Must change the password to revoke access. ### [​](https://mintlify.com/docs/authentication-personalization/overview#available-for-personalization) Available for personalization **Shared session**: Use the same session token as your dashboard to personalize content. * Pros of shared session: * Users that are logged into your dashboard are automatically logged into your docs. * User sessions are persistent so you can refresh data without requiring a new login. * Minimal setup. * Cons of shared session: * Your docs will make a request to your backend. * You must have a dashboard that uses session authentication. * CORS configuration is generally required. [​](https://mintlify.com/docs/authentication-personalization/overview#content-customization) Content customization --------------------------------------------------------------------------------------------------------------------- All three methods allow you to customize content with these features. ### [​](https://mintlify.com/docs/authentication-personalization/overview#dynamic-mdx-content) Dynamic `MDX` content Display dynamic content based on user information like name, plan, or organization. The `user` variable contains information sent to your docs from logged in users. See [Sending data](https://mintlify.com/docs/authentication-personalization/sending-data) for more information. **Example**: Hello, ! Copy Ask AI Hello, {user.name ?? 'reader'}! This feature is more powerful when you pair it with custom data about your users. For example, you can give different instructions based on a user’s plan. **Example**: Authentication is an enterprise feature. Copy Ask AI Authentication is an enterprise feature. { user.org === undefined ? <>To access this feature, first create an account at the Mintlify dashboard. : user.org.plan !== 'enterprise' ? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. : <>To request this feature for your enterprise org, contact our team. } The information in `user` is only available for logged in users. For logged out users, the value of `user` will be `{}`. To prevent the page from crashing for logged out users, always use optional chaining on your `user` fields. For example, `{user.org?.plan}`. ### [​](https://mintlify.com/docs/authentication-personalization/overview#api-key-prefilling) API key prefilling Automatically populate API playground fields with user-specific values by returning matching field names in your user data. The field names in your user data must exactly match the names in the API playground for automatic prefilling to work. ### [​](https://mintlify.com/docs/authentication-personalization/overview#page-visibility) Page visibility Restrict which pages are visible to your users by adding `groups` fields to your pages’ frontmatter. By default, every page is visible to every user. Users will only see pages for `groups` that they are in. Copy Ask AI --- title: "Managing your users" description: "Adding and removing users from your organization" groups: ["admin"] --- Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-playground/troubleshooting) [Authentication setupGuarantee privacy of your docs by authenticating users\ \ Next](https://mintlify.com/docs/authentication-personalization/authentication-setup) On this page * [Handshake methods](https://mintlify.com/docs/authentication-personalization/overview#handshake-methods) * [Available for all methods](https://mintlify.com/docs/authentication-personalization/overview#available-for-all-methods) * [Available for authentication and partial authentication](https://mintlify.com/docs/authentication-personalization/overview#available-for-authentication-and-partial-authentication) * [Available for personalization](https://mintlify.com/docs/authentication-personalization/overview#available-for-personalization) * [Content customization](https://mintlify.com/docs/authentication-personalization/overview#content-customization) * [Dynamic MDX content](https://mintlify.com/docs/authentication-personalization/overview#dynamic-mdx-content) * [API key prefilling](https://mintlify.com/docs/authentication-personalization/overview#api-key-prefilling) * [Page visibility](https://mintlify.com/docs/authentication-personalization/overview#page-visibility) Assistant Responses are generated using AI and may contain mistakes. --- # MDX setup - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation MDX MDX setup You can manually define API endpoints in individual `MDX` files rather than using an OpenAPI specification. This method provides flexibility for custom content, but we recommend generating API documentation from an OpenAPI specification file for most API documentation projects as it’s more maintainable and feature-rich. However, MDX can be useful for documenting small APIs, prototyping, or when you want to feature API endpoints alongside other content. To generate pages for API endpoints using `MDX`, configure your API settings in `docs.json`, create individual `MDX` files for each endpoint, and use components like `` to define parameters. From these definitions, Mintlify generates interactive API playgrounds, request examples, and response examples. 1 Configure your API In your `docs.json` file, define your base URL and auth method: Copy Ask AI "api": { "mdx": { "server": "https://mintlify.com/api", // string array for multiple base URLs "auth": { "method": "key", "name": "x-api-key" // options: bearer, basic, key. } } } If you want to hide the API playground, use the `display` field. You do not need to include an auth method if you hide the playground. Copy Ask AI "api": { "playground": { "display": "none" } } Find a full list of API configurations in [Settings](https://mintlify.com/docs/settings#api-configurations) . 2 Create your endpoint pages Each API endpoint page should have a corresponding `MDX` file. At the top of each file, define `title` and `api`: Copy Ask AI --- title: 'Create new user' api: 'POST https://api.mintlify.com/user' --- You can specify path parameters by adding the parameter name to the path, wrapped with `{}`: Copy Ask AI https://api.example.com/v1/endpoint/{userId} If you have a `server` field configured in `docs.json`, you can use relative paths like `/v1/endpoint`. You can override the globally-defined display mode for the API playground for a page by adding `playground` to the frontmatter: Copy Ask AI --- title: 'Create new user' api: 'POST https://api.mintlify.com/user' playground: 'none' --- * `playground: 'interactive'` - Display the interactive playground. * `playground: 'simple'` - Display a copyable endpoint with no playground. * `playground: 'none'` - Hide the playground. 3 Add your endpoints to your docs Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs in [Navigation](https://mintlify.com/docs/navigation) . [​](https://mintlify.com/docs/api-playground/mdx/configuration#enabling-authentication) Enabling authentication ------------------------------------------------------------------------------------------------------------------ You can add an authentication method to your `docs.json` to enable it globally on every page or you can set it on a per-page basis. A page’s authentication method will override a global method if both are set. ### [​](https://mintlify.com/docs/api-playground/mdx/configuration#bearer-token) Bearer token docs.json Page Metadata Copy Ask AI "api": { "mdx": { "auth": { "method": "bearer" } } } ### [​](https://mintlify.com/docs/api-playground/mdx/configuration#basic-authentication) Basic authentication docs.json Page Metadata Copy Ask AI "api": { "mdx": { "auth": { "method": "basic" } } } ### [​](https://mintlify.com/docs/api-playground/mdx/configuration#api-key) API key docs.json Page Metadata Copy Ask AI "api": { "mdx": { "auth": { "method": "key", "name": "x-api-key" } } } ### [​](https://mintlify.com/docs/api-playground/mdx/configuration#none) None The `none` authentication method is useful to disable authentication on a specific endpoint after setting a default in docs.json. Page Metadata Copy Ask AI --- title: "Your page title" authMethod: "none" --- Was this page helpful? YesNo [Previous](https://mintlify.com/docs/api-playground/asyncapi/playground) [AuthenticationYou can set authentication parameters to let users use their real API keys.\ \ Next](https://mintlify.com/docs/api-playground/mdx/authentication) On this page * [Enabling authentication](https://mintlify.com/docs/api-playground/mdx/configuration#enabling-authentication) * [Bearer token](https://mintlify.com/docs/api-playground/mdx/configuration#bearer-token) * [Basic authentication](https://mintlify.com/docs/api-playground/mdx/configuration#basic-authentication) * [API key](https://mintlify.com/docs/api-playground/mdx/configuration#api-key) * [None](https://mintlify.com/docs/api-playground/mdx/configuration#none) Assistant Responses are generated using AI and may contain mistakes. --- # Personalization setup - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Authentication and personalization Personalization setup Personalization lets you customize your documentation based on user information. This guide covers setup for each available handshake method. **Need help choosing?** See the [overview](https://mintlify.com/docs/authentication-personalization/overview) to compare options. [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#configuring-personalization) Configuring personalization ---------------------------------------------------------------------------------------------------------------------------------------------- Select the handshake method that you want to configure. * JWT * OAuth 2.0 * Shared session ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#prerequisites) Prerequisites * A login system that can generate and sign JWTs. * A backend service that can create redirect URLs. ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#implementation) Implementation 1 Generate a private key. 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication) . 2. Select **Personalization**. 3. Select **JWT**. 4. Enter the URL of your existing login flow and select **Save changes**. 5. Select **Generate new key**. 6. Store your key securely where it can be accessed by your backend. 2 Integrate Mintlify personalization into your login flow. Modify your existing login flow to include these steps after user login: * Create a JWT containing the logged in user’s info in the `User` format. See [Sending Data](https://mintlify.com/docs/authentication-personalization/sending-data) for more information. * Sign the JWT with the secret key, using the ES256 algorithm. * Create a redirect URL back to your docs, including the JWT as the hash. ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#example) Example Your documentation is hosted at `docs.foo.com`. You want your docs to be separate from your dashboard (or you don’t have a dashboard) and enable personalization. Generate a JWT secret. Then create a login endpoint at `https://foo.com/docs-login` that initiates a login flow to your documentation. After verifying user credentials: * Generate a JWT with user data in Mintlify’s format. * Sign the JWT and redirect to `https://docs.foo.com#{SIGNED_JWT}`. Copy Ask AI import * as jose from 'jose'; import { Request, Response } from 'express'; const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'ES256'); export async function handleRequest(req: Request, res: Response) { const user = { expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), groups: res.locals.user.groups, content: { firstName: res.locals.user.firstName, lastName: res.locals.user.lastName, }, }; const jwt = await new jose.SignJWT(user) .setProtectedHeader({ alg: 'ES256' }) .setExpirationTime('10 s') .sign(signingKey); return res.redirect(`https://docs.foo.com#${jwt}`); } ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#preserving-page-anchors) Preserving page anchors To redirect users to specific sections after login, use this URL format: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`. **Example**: * Original URL: `https://docs.foo.com/quickstart#step-one` * Redirect URL: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one` ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#prerequisites) Prerequisites * A login system that can generate and sign JWTs. * A backend service that can create redirect URLs. ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#implementation) Implementation 1 Generate a private key. 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication) . 2. Select **Personalization**. 3. Select **JWT**. 4. Enter the URL of your existing login flow and select **Save changes**. 5. Select **Generate new key**. 6. Store your key securely where it can be accessed by your backend. 2 Integrate Mintlify personalization into your login flow. Modify your existing login flow to include these steps after user login: * Create a JWT containing the logged in user’s info in the `User` format. See [Sending Data](https://mintlify.com/docs/authentication-personalization/sending-data) for more information. * Sign the JWT with the secret key, using the ES256 algorithm. * Create a redirect URL back to your docs, including the JWT as the hash. ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#example) Example Your documentation is hosted at `docs.foo.com`. You want your docs to be separate from your dashboard (or you don’t have a dashboard) and enable personalization. Generate a JWT secret. Then create a login endpoint at `https://foo.com/docs-login` that initiates a login flow to your documentation. After verifying user credentials: * Generate a JWT with user data in Mintlify’s format. * Sign the JWT and redirect to `https://docs.foo.com#{SIGNED_JWT}`. Copy Ask AI import * as jose from 'jose'; import { Request, Response } from 'express'; const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'ES256'); export async function handleRequest(req: Request, res: Response) { const user = { expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), groups: res.locals.user.groups, content: { firstName: res.locals.user.firstName, lastName: res.locals.user.lastName, }, }; const jwt = await new jose.SignJWT(user) .setProtectedHeader({ alg: 'ES256' }) .setExpirationTime('10 s') .sign(signingKey); return res.redirect(`https://docs.foo.com#${jwt}`); } ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#preserving-page-anchors) Preserving page anchors To redirect users to specific sections after login, use this URL format: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`. **Example**: * Original URL: `https://docs.foo.com/quickstart#step-one` * Redirect URL: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one` ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#prerequisites-2) Prerequisites * An OAuth server that supports the Auth Code with PKCE Flow. * Ability to create an API endpoint accessible by OAuth access tokens. ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#implementation-2) Implementation 1 Create user info API endpoint. Create an API endpoint that: * Accepts OAuth access tokens for authentication. * Returns user data in the `User` format. See [Sending Data](https://mintlify.com/docs/authentication-personalization/sending-data) for more information. * Defines the scopes for access. 2 Configure your OAuth personalization settings. 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication) . 2. Select **Personalization**. 3. Select **OAuth** and configure these fields: * **Authorization URL**: Your OAuth authorization endpoint. * **Client ID**: Your OAuth 2.0 client identifier. * **Scopes**: Permissions to request. Must match the scopes of the endpoint that you configured in the first step. * **Token URL**: Your OAuth token exchange endpoint. * **Info API URL**: Endpoint to retrieve user data for personalization. Created in the first step. 4. Select **Save changes** 3 Configure your OAuth server. 1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication) . 2. Add this URL as an authorized redirect URL in your OAuth server configuration. ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#example-2) Example Your documentation is hosted at `foo.com/docs` and you have an existing OAuth server that supports the PKCE flow. You want to personalize your docs based on user data. **Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `docs-user-info` scope and responds with the user’s custom data: Copy Ask AI { "content": { "firstName": "Jane", "lastName": "Doe" }, "groups": ["engineering", "admin"] } **Configure your OAuth server details** in your dashboard: * **Authorization URL**: `https://auth.foo.com/authorization` * **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH` * **Scopes**: `['docs-user-info']` * **Token URL**: `https://auth.foo.com/exchange` * **Info API URL**: `https://api.foo.com/docs/user-info` **Configure your OAuth server** to allow redirects to your callback URL. ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#prerequisites-3) Prerequisites * A dashboard or user portal with cookie-based session authentication. * Ability to create an API endpoint at the same origin or subdomain as your dashboard. * If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com`. * If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com`. * Your docs are hosted at the same domain or subdomain as your dashboard. * If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`. * If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`. ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#implementation-3) Implementation 1 Create user info API endpoint. Create an API endpoint that: * Uses your existing session authentication to identify users * Returns user data in the `User` format (see [Sending Data](https://mintlify.com/docs/authentication-personalization/sending-data) ) * If the API domain and the docs domain **do not exactly match**: * Add the docs domain to your API’s `Access-Control-Allow-Origin` header (must not be `*`). * Set your API’s `Access-Control-Allow-Credentials` header to `true`. Only enable CORS headers on this specific endpoint, not your entire dashboard API. 2 Configure your personalization settings 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication) . 2. Select **Personalization**. 3. Select **Shared Session**. 4. Enter your **Info API URL**, which is the endpoint from the first step. 5. Enter your **Login URL**, where users log into your dashboard. 6. Select **Save changes**. ### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#examples) Examples #### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#dashboard-at-subdomain%2C-docs-at-subdomain) Dashboard at subdomain, docs at subdomain You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `docs.foo.com`. **Setup process**: 1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. 2. **Add CORS headers** for this route only: * `Access-Control-Allow-Origin`: `https://docs.foo.com` * `Access-Control-Allow-Credentials`: `true` 3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`. #### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#dashboard-at-subdomain%2C-docs-at-root) Dashboard at subdomain, docs at root You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`. **Setup process**: 1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. 2. **Add CORS headers** for this route only: * `Access-Control-Allow-Origin`: `https://foo.com` * `Access-Control-Allow-Credentials`: `true` 3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`. #### [​](https://mintlify.com/docs/authentication-personalization/personalization-setup#dashboard-at-root%2C-docs-at-root) Dashboard at root, docs at root You have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`. **Setup process**: 1. **Create endpoint** `foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. 2. **Configure API URL** in authentication settings: `https://foo.com/api/docs/user-info` No CORS configuration is needed since the dashboard and docs share the same domain. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/authentication-personalization/partial-authentication-setup) [Sending dataUser data format for personalizing your documentation\ \ Next](https://mintlify.com/docs/authentication-personalization/sending-data) On this page * [Configuring personalization](https://mintlify.com/docs/authentication-personalization/personalization-setup#configuring-personalization) Assistant Responses are generated using AI and may contain mistakes. --- # Sending data - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Authentication and personalization Sending data When implementing authentication or personalization, your system returns user data in a specific format that enables content customization. This data can be sent as either a raw JSON object or within a signed JWT, depending on your handshake method. The shape of the data is the same for both. [​](https://mintlify.com/docs/authentication-personalization/sending-data#user-data-format) User data format --------------------------------------------------------------------------------------------------------------- Copy Ask AI type User = { expiresAt?: number; groups?: string[]; content?: Record; apiPlaygroundInputs?: { header?: Record; query?: Record; cookie?: Record; server?: Record; }; }; [​](https://mintlify.com/docs/authentication-personalization/sending-data#param-expires-at) expiresAt number Session expiration time in **seconds since epoch**. If the user loads a page after this time, their stored data is automatically deleted and they must reauthenticate. **For JWT handshakes:** This differs from the JWT’s `exp` claim, which determines when a JWT is considered invalid. Set the JWT `exp` claim to a short duration (10 seconds or less) for security. Use `expiresAt` for the actual session length (hours to weeks). [​](https://mintlify.com/docs/authentication-personalization/sending-data#param-groups) groups string\[\] A list of groups that the user belongs to. Pages with a matching `groups` field in their metadata will be visible to this user. **Example**: User with `groups: ["admin", "engineering"]` can access pages tagged with either the `admin` or `engineering` groups. [​](https://mintlify.com/docs/authentication-personalization/sending-data#param-content) content object Custom data accessible in your `MDX` content via the `user` variable. Use this for dynamic personalization throughout your documentation. **Example**: Copy Ask AI { "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" } **Usage in `MDX`**: Copy Ask AI Welcome back, {user.firstName}! Your {user.plan} plan includes... With the example `user` data, this would render as: Welcome back, Ronan! Your Enterprise plan includes… [​](https://mintlify.com/docs/authentication-personalization/sending-data#param-api-playground-inputs) apiPlaygroundInputs object User-specific values that will be prefilled in the API playground if supplied. Save users time when testing your APIs with their own data. **Example**: Copy Ask AI { "header": { "X-API-Key": "user_api_key_123" }, "server": { "subdomain": "foo" }, "query": { "org_id": "12345" } } If a user makes requests at a specific subdomain, you can send `{ server: { subdomain: 'foo' } }` as an `apiPlaygroundInputs` field. This value will be prefilled on any API page with the `subdomain` value. The `header`, `query`, and `cookie` fields will only prefill if they are part of your [OpenAPI security scheme](https://swagger.io/docs/specification/authentication/) . If a field is in either the `Authorization` or `Server` sections, it will prefill. Creating a standard header parameter named `Authorization` will not enable this feature. [​](https://mintlify.com/docs/authentication-personalization/sending-data#example-user-data) Example user data ----------------------------------------------------------------------------------------------------------------- Copy Ask AI { "expiresAt": 1735689600, "groups": ["admin", "beta-users"], "content": { "firstName": "Jane", "lastName": "Smith", "company": "TechCorp", "plan": "Enterprise", "region": "us-west" }, "apiPlaygroundInputs": { "header": { "Authorization": "Bearer abc123", "X-Org-ID": "techcorp" }, "server": { "environment": "production", "region": "us-west" } } } Was this page helpful? YesNo [Previous](https://mintlify.com/docs/authentication-personalization/personalization-setup) [MigrationsHow to migrate documentation from your existing provider\ \ Next](https://mintlify.com/docs/guides/migration) On this page * [User data format](https://mintlify.com/docs/authentication-personalization/sending-data#user-data-format) * [Example user data](https://mintlify.com/docs/authentication-personalization/sending-data#example-user-data) Assistant Responses are generated using AI and may contain mistakes. --- # Cards - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Cards Card Example Image Card Example Copy Ask AI This is how you use a card with an icon and a link. Clicking on this card brings you to the Columns page. [Card Title\ ----------\ \ This is how you use a card with an icon and a link. Clicking on this card brings you to the Columns page.](https://mintlify.com/docs/components/columns) Card Example Image Card Example Copy Ask AI This is how you use a card with an icon and a link. Clicking on this card brings you to the Columns page. [​](https://mintlify.com/docs/components/cards#horizontal-card) Horizontal card ---------------------------------------------------------------------------------- Add a `horizontal` property to display cards horizontally. Horizontal Card --------------- Here is an example of a horizontal card [​](https://mintlify.com/docs/components/cards#image-card) Image card ------------------------------------------------------------------------ Add an `img` property to display an image on the top of the card. ![yosemite](https://mintlify-assets.b-cdn.net/yosemite.jpg) Image Card ---------- Here is an example of a card with an image [​](https://mintlify.com/docs/components/cards#link-card) Link card ---------------------------------------------------------------------- You can customize the CTA and whether or not to display the arrow on the card. By default, the arrow will only show for external links. [Link card\ ---------\ \ This is how you use a card with an icon and a link. Clicking on this card brings you to the Columns page.\ \ Click here](https://mintlify.com/docs/components/columns) Card Example Copy Ask AI This is how you use a card with an icon and a link. Clicking on this card brings you to the Columns page. [​](https://mintlify.com/docs/components/cards#grouping-cards) Grouping cards -------------------------------------------------------------------------------- You can group cards in [columns](https://mintlify.com/docs/components/columns) . First Card ---------- This is the first card. Second Card ----------- This is the second card. [​](https://mintlify.com/docs/components/cards#props) Props -------------------------------------------------------------- [​](https://mintlify.com/docs/components/cards#param-title) title string required The title of the card [​](https://mintlify.com/docs/components/cards#param-icon) icon string or svg A [Font Awesome icon](https://fontawesome.com/icons) , [Lucide icon](https://lucide.dev/icons) , or JSX compatible SVG code in `icon={}`. To generate JSX compatible SVG code: 1. Use the [SVGR converter](https://react-svgr.com/playground/) . 2. Copy the code inside the `` tag. 3. Paste the code into your card. Make sure to only copy and paste the code inside the `` tag. 4. You may need to decrease the height and width to make the image fit. [​](https://mintlify.com/docs/components/cards#param-icon-type) iconType string One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` [​](https://mintlify.com/docs/components/cards#param-color) color string The color of the icon as a hex code [​](https://mintlify.com/docs/components/cards#param-href) href string The url that clicking on the card would navigate the user to [​](https://mintlify.com/docs/components/cards#param-horizontal) horizontal boolean Makes the card more compact and horizontal [​](https://mintlify.com/docs/components/cards#param-img) img string The url or local path to an image to display on the top of the card [​](https://mintlify.com/docs/components/cards#param-cta) cta string Label for the action button [​](https://mintlify.com/docs/components/cards#param-arrow) arrow boolean Enable or disable the link arrow icon Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/callouts) [ColumnsShow cards side by side in a grid format\ \ Next](https://mintlify.com/docs/components/columns) Card Example Image Card Example Copy Ask AI This is how you use a card with an icon and a link. Clicking on this card brings you to the Columns page. Assistant Responses are generated using AI and may contain mistakes. --- # Code groups - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Code groups Use the `CodeGroup` component to display multiple code blocks in a tabbed interface, allowing users to compare implementations across different programming languages or see alternative approaches for the same task. helloWorld.js hello\_world.py HelloWorld.java Copy Ask AI console.log("Hello World"); [​](https://mintlify.com/docs/components/code-groups#creating-code-groups) Creating code groups -------------------------------------------------------------------------------------------------- To create a code group, wrap multiple code blocks with `` tags. Each code block must include a title, which becomes the tab label. Copy Ask AI ```javascript helloWorld.js console.log("Hello World"); ``` ```python hello_world.py print('Hello World!') ``` ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` [​](https://mintlify.com/docs/components/code-groups#language-dropdown) Language dropdown -------------------------------------------------------------------------------------------- You can replace the tabs in a code group with a dropdown menu to toggle between languages using the `dropdown` prop. helloWorld.js Javascript Copy Ask AI console.log("Hello World"); Copy Ask AI ```javascript helloWorld.js console.log("Hello World"); ``` ```python hello_world.py print('Hello World!') ``` ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/columns) [ExamplesDisplay code blocks in the right sidebar on desktop devices\ \ Next](https://mintlify.com/docs/components/examples) On this page * [Creating code groups](https://mintlify.com/docs/components/code-groups#creating-code-groups) * [Language dropdown](https://mintlify.com/docs/components/code-groups#language-dropdown) Assistant Responses are generated using AI and may contain mistakes. --- # Callouts - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Callouts Callout Example Copy Ask AI This adds a note in the content Callouts can be styled as a Note, Warning, Info, Tip, or Check: This adds a note in the content Copy Ask AI This adds a note in the content This raises a warning to watch out for Copy Ask AI This raises a warning to watch out for This draws attention to important information Copy Ask AI This draws attention to important information This suggests a helpful tip Copy Ask AI This suggests a helpful tip This brings us a checked status Copy Ask AI This brings us a checked status This is a danger callout Copy Ask AI This is a danger callout Callout Example Copy Ask AI This adds a note in the content Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/accordions) [CardsHighlight main points or links with customizable icons\ \ Next](https://mintlify.com/docs/components/cards) Callout Example Copy Ask AI This adds a note in the content Assistant Responses are generated using AI and may contain mistakes. --- # Columns - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Columns Card Group Example Copy Ask AI Neque porro quisquam est qui dolorem ipsum quia dolor sit amet Lorem ipsum dolor sit amet, consectetur adipiscing elit The `Columns` component lets you group multiple `Card` components together. It’s most often used to put multiple cards in a grid, by specifying the number of grid columns. First Card ---------- Neque porro quisquam est qui dolorem ipsum quia dolor sit amet Second Card ----------- Lorem ipsum dolor sit amet, consectetur adipiscing elit Card Group Example Copy Ask AI Neque porro quisquam est qui dolorem ipsum quia dolor sit amet Lorem ipsum dolor sit amet, consectetur adipiscing elit ### [​](https://mintlify.com/docs/components/columns#props) Props [​](https://mintlify.com/docs/components/columns#param-cols) cols default:2 The number of columns per row Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/cards) [Code groupsDisplay multiple code examples in one component\ \ Next](https://mintlify.com/docs/components/code-groups) Card Group Example Copy Ask AI Neque porro quisquam est qui dolorem ipsum quia dolor sit amet Lorem ipsum dolor sit amet, consectetur adipiscing elit Assistant Responses are generated using AI and may contain mistakes. --- # Panel - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Panel Pin info to the side panel. Or add any other component. You can use the `` component to customize the right side panel of a page with any components that you want. If a page has a `` component, any [RequestExample](https://mintlify.com/docs/components/examples#request-example) and [ResponseExample](https://mintlify.com/docs/components/examples#response-example) components must be inside ``. The components in a `` will replace a page’s table of contents. Copy Ask AI Pin info to the side panel. Or add any other component. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/mermaid-diagrams) [StepsSequence content using the Steps component\ \ Next](https://mintlify.com/docs/components/steps) Pin info to the side panel. Or add any other component. Assistant Responses are generated using AI and may contain mistakes. --- # Expandables - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Expandables Expandable Example Copy Ask AI The full name of the user Whether the user is over 21 years old [​](https://mintlify.com/docs/components/expandables#param-user) user User Object Show properties [​](https://mintlify.com/docs/components/expandables#param-full-name) full\_name string The full name of the user [​](https://mintlify.com/docs/components/expandables#param-is-over-21) is\_over\_21 boolean Whether the user is over 21 years old Expandable Example Copy Ask AI The full name of the user Whether the user is over 21 years old See all 11 lines [​](https://mintlify.com/docs/components/expandables#props) Props -------------------------------------------------------------------- [​](https://mintlify.com/docs/components/expandables#param-title) title string The name of the object you are showing. Used to generate the “Show NAME” and “Hide NAME” text. [​](https://mintlify.com/docs/components/expandables#param-default-open) defaultOpen boolean default:"false" Set to true to show the component as open when the page loads. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/examples) [FieldsSet parameters for your API or SDK references\ \ Next](https://mintlify.com/docs/components/fields) Expandable Example Copy Ask AI The full name of the user Whether the user is over 21 years old Assistant Responses are generated using AI and may contain mistakes. --- # Frames - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Frames Frame Frame with Captions Copy Ask AI Frames are very helpful if you want to center an image. [​](https://mintlify.com/docs/components/frames#captions) Captions --------------------------------------------------------------------- You can add additional context to an image using the optional `caption` prop. Yosemite National Park is visited by over 3.5 million people every year [​](https://mintlify.com/docs/components/frames#props) Props --------------------------------------------------------------- [​](https://mintlify.com/docs/components/frames#param-caption) caption string Optional caption text to show centered under your component. Frame Frame with Captions Copy Ask AI Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/fields) [IconsUse icons from popular icon libraries\ \ Next](https://mintlify.com/docs/components/icons) Frame Frame with Captions Copy Ask AI Assistant Responses are generated using AI and may contain mistakes. --- # Authentication setup - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Authentication and personalization Authentication setup Authentication requires users to log in before accessing your documentation. This guide covers setup for each available handshake method. **Need help choosing?** See the [overview](https://mintlify.com/docs/authentication-personalization/overview) to compare options. Authentication methods are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication) . [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#configuring-authentication) Configuring authentication ------------------------------------------------------------------------------------------------------------------------------------------- Select the handshake method that you want to configure. * JWT * OAuth 2.0 * Mintlify Dashboard * Password ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#prerequisites) Prerequisites * An authentication system that can generate and sign JWTs. * A backend service that can create redirect URLs. ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#implementation) Implementation 1 Generate a private key. 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication) . 2. Select **Full Authentication** or **Partial Authentication**. 3. Select **JWT**. 4. Enter the URL of your existing login flow and select **Save changes**. 5. Select **Generate new key**. 6. Store your key securely where it can be accessed by your backend. 2 Integrate Mintlify authentication into your login flow. Modify your existing login flow to include these steps after user authentication: * Create a JWT containing the authenticated user’s info in the `User` format. See [Sending Data](https://mintlify.com/docs/authentication-personalization/sending-data) for more information. * Sign the JWT with your secret key, using the EdDSA algorithm. * Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash. ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#example) Example Your documentation is hosted at `docs.foo.com` with an existing authentication system at `foo.com`. You want to extend your login flow to grant access to the docs while keeping your docs separate from your dashboard (or you don’t have a dashboard). Create a login endpoint at `https://foo.com/docs-login` that extends your existing authentication. After verifying user credentials: * Generate a JWT with user data in Mintlify’s format. * Sign the JWT and redirect to `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`. TypeScript Python Copy Ask AI import * as jose from 'jose'; import { Request, Response } from 'express'; const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA'); export async function handleRequest(req: Request, res: Response) { const user = { expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration groups: res.locals.user.groups, content: { firstName: res.locals.user.firstName, lastName: res.locals.user.lastName, }, }; const jwt = await new jose.SignJWT(user) .setProtectedHeader({ alg: 'EdDSA' }) .setExpirationTime('10 s') // 10 second JWT expiration .sign(signingKey); return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`); } ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#redirecting-unauthenticated-users) Redirecting unauthenticated users When an unauthenticated user tries to access a protected page, their intended destination is preserved in the redirect to your login URL: 1. User attempts to visit a protected page: `https://docs.foo.com/quickstart`. 2. Redirect to your login URL with a redirect query parameter: `https://foo.com/docs-login?redirect=%2Fquickstart`. 3. After authentication, redirect to `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`. 4. User lands in their original destination. ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#prerequisites) Prerequisites * An authentication system that can generate and sign JWTs. * A backend service that can create redirect URLs. ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#implementation) Implementation 1 Generate a private key. 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication) . 2. Select **Full Authentication** or **Partial Authentication**. 3. Select **JWT**. 4. Enter the URL of your existing login flow and select **Save changes**. 5. Select **Generate new key**. 6. Store your key securely where it can be accessed by your backend. 2 Integrate Mintlify authentication into your login flow. Modify your existing login flow to include these steps after user authentication: * Create a JWT containing the authenticated user’s info in the `User` format. See [Sending Data](https://mintlify.com/docs/authentication-personalization/sending-data) for more information. * Sign the JWT with your secret key, using the EdDSA algorithm. * Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash. ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#example) Example Your documentation is hosted at `docs.foo.com` with an existing authentication system at `foo.com`. You want to extend your login flow to grant access to the docs while keeping your docs separate from your dashboard (or you don’t have a dashboard). Create a login endpoint at `https://foo.com/docs-login` that extends your existing authentication. After verifying user credentials: * Generate a JWT with user data in Mintlify’s format. * Sign the JWT and redirect to `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`. TypeScript Python Copy Ask AI import * as jose from 'jose'; import { Request, Response } from 'express'; const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA'); export async function handleRequest(req: Request, res: Response) { const user = { expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration groups: res.locals.user.groups, content: { firstName: res.locals.user.firstName, lastName: res.locals.user.lastName, }, }; const jwt = await new jose.SignJWT(user) .setProtectedHeader({ alg: 'EdDSA' }) .setExpirationTime('10 s') // 10 second JWT expiration .sign(signingKey); return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`); } ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#redirecting-unauthenticated-users) Redirecting unauthenticated users When an unauthenticated user tries to access a protected page, their intended destination is preserved in the redirect to your login URL: 1. User attempts to visit a protected page: `https://docs.foo.com/quickstart`. 2. Redirect to your login URL with a redirect query parameter: `https://foo.com/docs-login?redirect=%2Fquickstart`. 3. After authentication, redirect to `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`. 4. User lands in their original destination. ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#prerequisites-2) Prerequisites * An OAuth server that supports the Authorization Code Flow. * Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable personalization features). ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#implementation-2) Implementation 1 Configure your OAuth settings. 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication) . 2. Select **Full Authentication** or **Partial Authentication**. 3. Select **OAuth** and configure these fields: * **Authorization URL**: Your OAuth endpoint. * **Client ID**: Your OAuth 2.0 client identifier. * **Client Secret**: Your OAuth 2.0 client secret. * **Scopes**: Permissions to request. Use multiple scopes if you need different access levels. * **Token URL**: Your OAuth token exchange endpoint. * **Info API URL** (optional): Endpoint to retrieve user info for personalization. If omitted, the OAuth flow will only be used to verify identity and the user info will be empty. 4. Select **Save changes**. 2 Configure your OAuth server. 1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication) . 2. Add the redirect URL as an authorized redirect URL for your OAuth server. 3 Create your user info endpoint (optional). To enable personalization features, create an API endpoint that: * Accepts OAuth access tokens for authentication. * Returns user data in the `User` format. See [Sending Data](https://mintlify.com/docs/authentication-personalization/sending-data) for more information. Add this endpoint URL to the **Info API URL** field in your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication) . ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#example-2) Example Your documentation is hosted at `foo.com/docs` and you have an existing OAuth server at `auth.foo.com` that supports the Authorization Code Flow. **Configure your OAuth server details** in your dashboard: * **Authorization URL**: `https://auth.foo.com/authorization` * **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH` * **Scopes**: `['docs-user-info']` * **Token URL**: `https://auth.foo.com/exchange` * **Info API URL**: `https://api.foo.com/docs/user-info` **Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `docs-user-info` scope, and returns: Copy Ask AI { "content": { "firstName": "Jane", "lastName": "Doe" }, "groups": ["engineering", "admin"] } **Configure your OAuth server to allow redirects** to your callback URL. ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#prerequisites-3) Prerequisites * Your documentation users are also your documentation editors. ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#implementation-3) Implementation 1 Enable Mintlify dashboard authentication. 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication) . 2. Select **Full Authentication** or **Partial Authentication**. 3. Select **Mintlify Auth**. 4. Select **Enable Mintlify Auth**. 2 Add authorized users. 1. In your dashboard, go to [Members](https://dashboard.mintlify.com/settings/organization/members) . 2. Add each person who should have access to your documentation. 3. Assign appropriate roles based on their editing permissions. ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#example-3) Example Your documentation is hosted at `docs.foo.com` and your team uses the dashboard to edit your docs. You want to restrict access to team members only. **Enable Mintlify authentication** in your dashboard settings. **Verify team access** by checking that all team members are added to your organization. Password authentication provides access control only and does **not** support content personalization. ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#prerequisites-4) Prerequisites * Your security requirements allow sharing passwords among users. ### [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#implementation-4) Implementation 1 Create a password. 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication) . 2. Select **Full Authentication** or **Partial Authentication**. 3. Select **Password**. 4. Enter a secure password. 5. Select **Save changes**. 2 Distribute access. Securely share the password and documentation URL with authorized users. [​](https://mintlify.com/docs/authentication-personalization/authentication-setup#example-4) Example ------------------------------------------------------------------------------------------------------- Your documentation is hosted at `docs.foo.com` and you need basic access control without tracking individual users. You want to prevent public access while keeping setup simple. **Create a strong password** in your dashboard. **Share credentials** with authorized users. That’s it! Was this page helpful? YesNo [Previous](https://mintlify.com/docs/authentication-personalization/overview) [Partial authentication setupControl access to specific pages\ \ Next](https://mintlify.com/docs/authentication-personalization/partial-authentication-setup) On this page * [Configuring authentication](https://mintlify.com/docs/authentication-personalization/authentication-setup#configuring-authentication) Assistant Responses are generated using AI and may contain mistakes. --- # Contact support - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Guides Contact support [​](https://mintlify.com/docs/contact-support#ask-our-docs) Ask our docs --------------------------------------------------------------------------- Select Command + I to start a chat with our AI assistant trained on our documentation. [​](https://mintlify.com/docs/contact-support#watch-video-tutorials) Watch video tutorials --------------------------------------------------------------------------------------------- Visit our [YouTube](https://www.youtube.com/@GetMintlify/videos) channel for tutorials and guides on using Mintlify. [​](https://mintlify.com/docs/contact-support#message-support) Message support --------------------------------------------------------------------------------- Send us a message from your [dashboard](https://dashboard.mintlify.com/) by selecting **Support** in the sidebar. We aim to respond to all requests within 24 hours, but delays may occur during busy times. [​](https://mintlify.com/docs/contact-support#email-support) Email support ----------------------------------------------------------------------------- If you can’t access your dashboard, please email us at [](https://mintlify.com/cdn-cgi/l/email-protection#e1929491918e9395a18c888f958d888798cf828e8c) [\[email protected\]](https://mintlify.com/cdn-cgi/l/email-protection#7c0f090c0c130e083c1115120810151a05521f1311) . Was this page helpful? YesNo [Previous](https://mintlify.com/docs/guides/deployments) [Analytics integrationsIntegrate with an analytics platform to track events\ \ Next](https://mintlify.com/docs/integrations/analytics/overview) On this page * [Ask our docs](https://mintlify.com/docs/contact-support#ask-our-docs) * [Watch video tutorials](https://mintlify.com/docs/contact-support#watch-video-tutorials) * [Message support](https://mintlify.com/docs/contact-support#message-support) * [Email support](https://mintlify.com/docs/contact-support#email-support) Assistant Responses are generated using AI and may contain mistakes. --- # Mermaid - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Mermaid Mermaid Flowchart Example Copy Ask AI ```mermaid flowchart LR subgraph subgraph1 direction TB top1[top] --> bottom1[bottom] end subgraph subgraph2 direction TB top2[top] --> bottom2[bottom] end %% ^ These subgraphs are identical, except for the links to them: %% Link *to* subgraph1: subgraph1 direction is maintained outside --> subgraph1 %% Link *within* subgraph2: %% subgraph2 inherits the direction of the top-level graph (LR) outside ---> top2 ``` Mermaid Flowchart Example Copy Ask AI ```mermaid flowchart LR subgraph subgraph1 direction TB top1[top] --> bottom1[bottom] end subgraph subgraph2 direction TB top2[top] --> bottom2[bottom] end %% ^ These subgraphs are identical, except for the links to them: %% Link *to* subgraph1: subgraph1 direction is maintained outside --> subgraph1 %% Link *within* subgraph2: %% subgraph2 inherits the direction of the top-level graph (LR) outside ---> top2 ``` [Mermaid](https://mermaid.js.org/) lets you create visual diagrams using text and code. For a complete list of diagrams supported by Mermaid, check out their [website](https://mermaid.js.org/) . [​](https://mintlify.com/docs/components/mermaid-diagrams#syntax-for-mermaid-diagrams) Syntax for Mermaid diagrams --------------------------------------------------------------------------------------------------------------------- To create a flowchart, you can write the Mermaid flowchart inside a Mermaid code block. Copy Ask AI ```mermaid // Your mermaid code block here ``` Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/icons) [PanelSpecify the content of the right side panel\ \ Next](https://mintlify.com/docs/components/panel) Mermaid Flowchart Example Copy Ask AI ```mermaid flowchart LR subgraph subgraph1 direction TB top1[top] --> bottom1[bottom] end subgraph subgraph2 direction TB top2[top] --> bottom2[bottom] end %% ^ These subgraphs are identical, except for the links to them: %% Link *to* subgraph1: subgraph1 direction is maintained outside --> subgraph1 %% Link *within* subgraph2: %% subgraph2 inherits the direction of the top-level graph (LR) outside ---> top2 ``` Assistant Responses are generated using AI and may contain mistakes. --- # Tooltips - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Tooltips Tooltip Example Copy Ask AI Hover over me Tooltips are a way to show a definition when you hover over text. Hover over me and see a tooltip in action Tooltip Example Copy Ask AI Hover over me Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/tabs) [UpdateKeep track of changes and updates\ \ Next](https://mintlify.com/docs/components/update) Tooltip Example Copy Ask AI Hover over me Assistant Responses are generated using AI and may contain mistakes. --- # AI assistant - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Guides AI assistant The AI assistant is automatically enabled on [Pro, Growth, and Enterprise plans](https://mintlify.com/pricing?ref=assistant) . [​](https://mintlify.com/docs/guides/assistant#about-the-assistant) About the assistant ------------------------------------------------------------------------------------------ The assistant answers questions about your documentation through natural language queries. It is embedded directly in your documentation site, providing users with immediate access to contextual help. The assistant uses agentic RAG (retrieval-augmented generation) with tool calling powered by Claude Sonnet 4. When users ask questions, the assistant: * **Searches and retrieves** relevant content from your documentation to provide accurate answers. * **Cites sources** and provides navigable links to take users directly to referenced pages. * **Generates copyable code examples** to help users implement solutions from your documentation. You can view assistant usage through your dashboard to understand user behavior and documentation effectiveness. Export and analyze query data to help identify: * Frequently asked questions that might need better coverage. * Content gaps where users struggle to find answers. * Popular topics that could benefit from additional content. [​](https://mintlify.com/docs/guides/assistant#using-the-assistant) Using the assistant ------------------------------------------------------------------------------------------ Users can access the assistant in two ways: * **Keyboard shortcut**: Command + I (Ctrl + I on Windows) * **Assistant button** next to the search bar Both methods open a chat panel on the right side of your docs. Users can ask any question and the assistant will search your documentation for an answer. If no relevant information is found, the assistant will respond that it cannot answer the question. [​](https://mintlify.com/docs/guides/assistant#making-content-ai-ingestible) Making content AI ingestible ------------------------------------------------------------------------------------------------------------ Structure your documentation to help the assistant provide accurate, relevant answers. Clear organization and comprehensive context benefit both human readers and AI understanding. Structure and organization -------------------------- * Use semantic markup. * Write descriptive headings for sections. * Create a logical information hierarchy. * Use consistent formatting across your docs. * Include comprehensive metadata in page frontmatter. * Break up long blocks of text into shorter paragraphs. Context ------- * Define specific terms and acronyms when first introduced. * Provide sufficient conceptual content about features and procedures. * Include examples and use cases. * Cross-reference related topics. * Add [hidden pages](https://mintlify.com/docs/guides/hidden-pages) with additional context that users don’t need, but the assistant can reference. [​](https://mintlify.com/docs/guides/assistant#exporting-and-analyzing-queries) Exporting and analyzing queries ------------------------------------------------------------------------------------------------------------------ Review and export queries from your dashboard to understand how people interact with your documentation and identify improvement opportunities. Some ways that analyzing queries can help you improve your documentation: * Identify content gaps where frequent queries receive insufficient answers. * Discover user behavior patterns and common information needs from themes and patterns in queries. * Prioritize high-traffic pages for accuracy and quality improvements. You can explore queries from your [dashboard](https://dashboard.mintlify.com/products/assistant) , but to get more powerful insights we recommend exporting a `CSV` file of your queries, responses, and sources to analyze with your preferred AI tool. 1. Navigate to the [assistant page](https://dashboard.mintlify.com/products/assistant) in your dashboard. 2. Select **Export to CSV**. 3. Analyze the exported data using your preferred tool. Sample analysis prompts ----------------------- * Summarize the most common themes of the queries. * List any queries that had no sources cited. * Find patterns in unsuccessful interactions. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/guides/analytics) [Model Context ProtocolGenerate MCP servers from your documentation or OpenAPI specs\ \ Next](https://mintlify.com/docs/mcp) On this page * [About the assistant](https://mintlify.com/docs/guides/assistant#about-the-assistant) * [Using the assistant](https://mintlify.com/docs/guides/assistant#using-the-assistant) * [Making content AI ingestible](https://mintlify.com/docs/guides/assistant#making-content-ai-ingestible) * [Exporting and analyzing queries](https://mintlify.com/docs/guides/assistant#exporting-and-analyzing-queries) Assistant Responses are generated using AI and may contain mistakes. --- # Tabs - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Tabs Tabs Example Copy Ask AI ☝️ Welcome to the content that you can only see inside the first Tab. ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` ✌️ Here's content that's only inside the second Tab. 💪 Here's content that's only inside the third Tab. You can add any number of tabs, and other components inside of tabs. * First Tab * Second Tab * Third Tab ☝️ Welcome to the content that you can only see inside the first Tab. You can add any number of components inside of tabs. HelloWorld.java Copy Ask AI class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ☝️ Welcome to the content that you can only see inside the first Tab. You can add any number of components inside of tabs. HelloWorld.java Copy Ask AI class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ✌️ Here’s content that’s only inside the second Tab. 💪 Here’s content that’s only inside the third Tab. Tabs Example Copy Ask AI ☝️ Welcome to the content that you can only see inside the first Tab. ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` ✌️ Here's content that's only inside the second Tab. 💪 Here's content that's only inside the third Tab. [​](https://mintlify.com/docs/components/tabs#tab-props) Tab Props --------------------------------------------------------------------- [​](https://mintlify.com/docs/components/tabs#param-title) title string required The title of the tab. Short titles are easier to navigate. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/steps) [TooltipsShow a definition when you hover over text\ \ Next](https://mintlify.com/docs/components/tooltips) Tabs Example Copy Ask AI ☝️ Welcome to the content that you can only see inside the first Tab. ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` ✌️ Here's content that's only inside the second Tab. 💪 Here's content that's only inside the third Tab. Assistant Responses are generated using AI and may contain mistakes. --- # Examples - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Examples The `` and `` components display code blocks in the right sidebar to create a two-column layout that keeps examples visible while users scroll through your content. These components are designed for API documentation, but they work on all pages. Common use cases: * API endpoint documentation with request and response examples * Configuration examples alongside explanatory text * Code samples that users reference while following instructions * Before and after examples in tutorials On mobile devices, `` and `` components display as regular code blocks and can be scrolled past. [​](https://mintlify.com/docs/components/examples#requestexample) RequestExample ----------------------------------------------------------------------------------- Use `` to pins code examples in the right sidebar. This component works similarly to the [CodeGroup](https://mintlify.com/docs/components/code-groups) component, but displays the code in the sidebar instead of inline. You can include multiple code blocks inside a single ``. Each code block must have a title attribute. RequestExample Copy Ask AI ```bash Request curl --request POST \ --url https://dog-api.kinduff.com/api/facts ``` [​](https://mintlify.com/docs/components/examples#responseexample) ResponseExample ------------------------------------------------------------------------------------- The `` component pins code examples in the right sidebar beneath any `` content on the same page. ResponseExample Copy Ask AI ```json Response { "status": "success" } ``` Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/code-groups) [ExpandablesToggle to display nested properties.\ \ Next](https://mintlify.com/docs/components/expandables) On this page * [RequestExample](https://mintlify.com/docs/components/examples#requestexample) * [ResponseExample](https://mintlify.com/docs/components/examples#responseexample) Assistant Responses are generated using AI and may contain mistakes. --- # Introduction - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Getting started Introduction Documentation ================= Meet the next generation of documentation. AI-native, beautiful out-of-the-box, and built for developers. [### Quickstart\ \ Deploy your first docs site in minutes with our step-by-step guide](https://mintlify.com/docs/quickstart) [### CLI installation\ \ Install the CLI to preview and develop your docs locally](https://mintlify.com/docs/installation) [### Web editor\ \ Make quick updates and manage content with our browser-based editor](https://mintlify.com/docs/editor) [### Components\ \ Build rich, interactive documentation with our ready-to-use components](https://mintlify.com/docs/components) Assistant Responses are generated using AI and may contain mistakes. --- # AI ingestion - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Core configuration AI ingestion Generate optimized formats and provide shortcuts that help users get faster, more accurate responses when using your documentation as context for LLMs and AI tools. [​](https://mintlify.com/docs/ai-ingestion#contextual-menu) Contextual menu ------------------------------------------------------------------------------ Provide quick access to AI-optimized content and direct integrations with popular AI tools from a contextual menu on your pages. * **Copy page**: Copies the current page as Markdown for pasting as context into AI tools. * **View as Markdown**: Opens the current page as Markdown. * **Open in ChatGPT**: Creates a ChatGPT conversation with the current page as context. * **Open in Claude**: Creates a Claude conversation with the current page as context. * **Ask Perplexity**: Creates a Perplexity conversation with the current page as context. * [**Your custom options**](https://mintlify.com/docs/_sites/mintlify/ai-ingestion#adding-custom-options) : Add your own options to the contextual menu. ### [​](https://mintlify.com/docs/ai-ingestion#enabling-the-contextual-menu) Enabling the contextual menu Add the `contextual` field to your `docs.json` and specify which options you want to include in your menu. Copy Ask AI { "contextual": { "options": [\ "copy",\ "view",\ "chatgpt",\ "claude",\ "perplexity"\ ] } } ### [​](https://mintlify.com/docs/ai-ingestion#adding-custom-options) Adding custom options Create custom options in the contextual menu by adding an object to the `options` array. Each custom option requires these properties: [​](https://mintlify.com/docs/ai-ingestion#param-title) title string required The title of the option. [​](https://mintlify.com/docs/ai-ingestion#param-description) description string required The description of the option. Displayed beneath the title when the contextual menu is expanded. [​](https://mintlify.com/docs/ai-ingestion#param-icon) icon string required The icon of the option. Accepts any icon from the [Icons](https://mintlify.com/docs/components/icons) collection. [​](https://mintlify.com/docs/ai-ingestion#param-href) href string | object required The href of the option. Use a string for simple links or an object for dynamic links with query parameters. Show href object [​](https://mintlify.com/docs/ai-ingestion#param-base) base string required The base URL for the option. [​](https://mintlify.com/docs/ai-ingestion#param-query) query object required The query parameters for the option. Show query object [​](https://mintlify.com/docs/ai-ingestion#param-key) key string required The query parameter key. [​](https://mintlify.com/docs/ai-ingestion#param-value) value string required The query parameter value. Use `$page` to insert the current page content in Markdown or `$path` to insert the current page path. Example custom option: Example with Perplexity Copy Ask AI "contextual": { "options": [\ "copy",\ "view",\ "chatgpt",\ "claude",\ {\ "title": "Ask Perplexity",\ "description": "Ask Perplexity about the current page",\ "icon": "search",\ "href": {\ "base": "https://www.perplexity.ai/search",\ "query": [\ {\ "key": "q",\ "value": "Ask question about https://mintlify.com/docs$path.md"\ }\ ]\ }\ }\ ] } [​](https://mintlify.com/docs/ai-ingestion#%2Fllms-txt) /llms.txt -------------------------------------------------------------------- The [/llms.txt file](https://llmstxt.org/) is an industry standard that helps general-purpose LLMs index more efficiently, similar to how a sitemap helps search engines. Every documentation site automatically hosts an `/llms.txt` file at the root that lists all available pages in your documentation. AI tools can use this file to understand your documentation structure and find relevant content to user prompts. [Open llms.txt for this site](https://mintlify.com/docs/llms.txt) [​](https://mintlify.com/docs/ai-ingestion#%2Fllms-full-txt) /llms-full.txt ------------------------------------------------------------------------------ The `/llms-full.txt` file combines your entire documentation site into a single file as context for AI tools. Every documentation site automatically hosts an `/llms-full.txt` file at the root. [Open llms-full.txt for this site](https://mintlify.com/docs/llms-full.txt) [​](https://mintlify.com/docs/ai-ingestion#generating-markdown-versions-of-pages) Generating Markdown versions of pages -------------------------------------------------------------------------------------------------------------------------- Markdown provides structured text that AI tools can process more efficiently than HTML, which results in better response times and lower token usage. ### [​](https://mintlify.com/docs/ai-ingestion#md-extension) .md extension Add a `.md` to a page’s URL to display a Markdown version of that page. [Open quickstart.md](https://mintlify.com/docs/quickstart.md) ### [​](https://mintlify.com/docs/ai-ingestion#command-%2B-c-shortcut) Command + C shortcut Select Command + C (Ctrl + C on Windows) to copy any page as Markdown. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/settings/custom-domain) [Headers and textLearn how to format text, create headers, and style content\ \ Next](https://mintlify.com/docs/text) On this page * [Contextual menu](https://mintlify.com/docs/ai-ingestion#contextual-menu) * [Enabling the contextual menu](https://mintlify.com/docs/ai-ingestion#enabling-the-contextual-menu) * [Adding custom options](https://mintlify.com/docs/ai-ingestion#adding-custom-options) * [/llms.txt](https://mintlify.com/docs/ai-ingestion#%2Fllms-txt) * [/llms-full.txt](https://mintlify.com/docs/ai-ingestion#%2Fllms-full-txt) * [Generating Markdown versions of pages](https://mintlify.com/docs/ai-ingestion#generating-markdown-versions-of-pages) * [.md extension](https://mintlify.com/docs/ai-ingestion#md-extension) * [Command + C shortcut](https://mintlify.com/docs/ai-ingestion#command-%2B-c-shortcut) Assistant Responses are generated using AI and may contain mistakes. --- # Update - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Update Use the `Update` component to display changelog entries, version updates, and release notes with consistent formatting. [​](https://mintlify.com/docs/components/update#example) Example v0.1.1 [​](https://mintlify.com/docs/components/update#example-update) Example update --------------------------------------------------------------------------------- You can add anything here, like a screenshot, a code snippet, or a list of changes. ### [​](https://mintlify.com/docs/components/update#features) Features * Responsive design * Anchor for each update * Generated RSS feed entry for each update [​](https://mintlify.com/docs/components/update#how-to-use) How to use ------------------------------------------------------------------------- Update example Copy Ask AI This is how you use a changelog with a label, description, and tags. Use multiple `Update` components to create [changelogs](https://mintlify.com/docs/guides/changelogs) . [​](https://mintlify.com/docs/components/update#props) Props --------------------------------------------------------------- [​](https://mintlify.com/docs/components/update#param-label) label string required Label for the update. Appears to the left of the update and creates an anchor link. Labels should be unique. [​](https://mintlify.com/docs/components/update#param-tags) tags string\[\] Tags for the update. Shown as filters in the right side panel. [​](https://mintlify.com/docs/components/update#param-description) description string Description of the update. Appears below the label and tag. [​](https://mintlify.com/docs/components/update#param-rss) rss object Title and description that will appear in the RSS feed entry for the update. Copy Ask AI # What's New in v1.0.1 * Bug fixes * Improvements Example Update item in RSS feed Copy Ask AI <![CDATA[v1.0.1 released]]> https://mintlify.com/changelog#v101 https://mintlify.com/changelog#v101 Fri, 20 Jun 2025 21:32:19 GMT Learn more about [subscribable changelogs](https://mintlify.com/docs/guides/changelogs#subscribable-changelogs) . Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/tooltips) [PlaygroundEnable users to interact with your API\ \ Next](https://mintlify.com/docs/api-playground/overview) On this page * [Example](https://mintlify.com/docs/components/update#example) * [How to use](https://mintlify.com/docs/components/update#how-to-use) * [Props](https://mintlify.com/docs/components/update#props) Assistant Responses are generated using AI and may contain mistakes. --- # Icons - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Icons Icon Example Copy Ask AI Icon Example Copy Ask AI [​](https://mintlify.com/docs/components/icons#inline-icons) Inline Icons ---------------------------------------------------------------------------- The icon will be placed inline when used in a paragraph. Inline Icon Example Copy Ask AI The documentation you want, effortlessly. The documentation you want, effortlessly. ### [​](https://mintlify.com/docs/components/icons#props) Props [​](https://mintlify.com/docs/components/icons#param-icon) icon string required A [Font Awesome](https://fontawesome.com/icons) icon, [Lucide](https://lucide.dev/icons) icon, URL to an icon, or relative path to an icon. [​](https://mintlify.com/docs/components/icons#param-icon-type) iconType string One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` (only for [Font Awesome](https://fontawesome.com/icons) icons). [​](https://mintlify.com/docs/components/icons#param-color) color string The color of the icon as a hex code (e.g., `#FF5733`) [​](https://mintlify.com/docs/components/icons#param-size) size number The size of the icon in pixels Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/frames) [MermaidDisplay diagrams using Mermaid\ \ Next](https://mintlify.com/docs/components/mermaid-diagrams) Icon Example Copy Ask AI Assistant Responses are generated using AI and may contain mistakes. --- # Accordions - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Accordions Accordion Example Accordion Group Example Copy Ask AI You can put any content in here, including other components, like code: ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` I am an Accordion. You can put any content in here, including other components, like code: HelloWorld.java Copy Ask AI class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } Accordion Example Accordion Group Example Copy Ask AI You can put any content in here, including other components, like code: ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` ### [​](https://mintlify.com/docs/components/accordions#props) Props [​](https://mintlify.com/docs/components/accordions#param-title) title string required Title in the Accordion preview. [​](https://mintlify.com/docs/components/accordions#param-description) description string Detail below the title in the Accordion preview. [​](https://mintlify.com/docs/components/accordions#param-default-open) defaultOpen boolean default:"false" Whether the Accordion is open by default. [​](https://mintlify.com/docs/components/accordions#param-icon) icon string or svg A [Font Awesome icon](https://fontawesome.com/icons) , [Lucide icon](https://lucide.dev/icons) , or SVG code [​](https://mintlify.com/docs/components/accordions#param-icon-type) iconType string One of “regular”, “solid”, “light”, “thin”, “sharp-solid”, “duotone”, or “brands” [​](https://mintlify.com/docs/components/accordions#accordion-groups) Accordion Groups ----------------------------------------------------------------------------------------- You can group multiple accordions into a single display. Simply add `` around your existing `` components. FAQ without Icon You can put other components inside Accordions. HelloWorld.java Copy Ask AI class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } Check out the [Accordion](https://mintlify.com/docs/components/accordions) docs for all the supported props. FAQ with Icon Check out the [Accordion](https://mintlify.com/docs/components/accordions) docs for all the supported props. FAQ without Icon Check out the [Accordion](https://mintlify.com/docs/components/accordions) docs for all the supported props. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/reusable-snippets) [CalloutsUse callouts to add eye-catching context to your content\ \ Next](https://mintlify.com/docs/components/callouts) Accordion Example Accordion Group Example Copy Ask AI You can put any content in here, including other components, like code: ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` Assistant Responses are generated using AI and may contain mistakes. --- # Claude Code - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Guides Claude Code Claude Code is an agentic command line tool that can help you maintain your documentation. It can write new content, review existing pages, and keep docs up to date. You can train Claude Code to understand your documentation standards and workflows by adding a `CLAUDE.md` file to your project and refining it over time. [​](https://mintlify.com/docs/guides/claude-code#getting-started) Getting started ------------------------------------------------------------------------------------ **Prerequisites:** * Active Claude subscription (Pro, Max, or API access) **Setup:** 1. Install Claude Code: Copy Ask AI npm install -g @anthropic-ai/claude-code 2. Navigate to your docs directory. 3. (Optional) Add the `CLAUDE.md` file below to your project. 4. Run `claude` to start. [​](https://mintlify.com/docs/guides/claude-code#claude-md-template) CLAUDE.md template ------------------------------------------------------------------------------------------ Save a `CLAUDE.md` file at the root of your docs directory to help Claude Code understand your project. This file trains Claude Code on your documentation standards, preferences, and workflows. See [Manage Claude’s memory](https://docs.anthropic.com/en/docs/claude-code/memory) in the Anthropic docs for more information. Copy this example template or make changes for your docs specifications: Copy Ask AI # Mintlify documentation ## Working relationship - You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so - ALWAYS ask for clarification rather than making assumptions - NEVER lie, guess, or make up information ## Project context - Format: MDX files with YAML frontmatter - Config: docs.json for navigation, theme, settings - Components: Mintlify components ## Content strategy - Document just enough for user success - not too much, not too little - Prioritize accuracy and usability of information - Make content evergreen when possible - Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason - Check existing patterns for consistency - Start by making the smallest reasonable changes ## Frontmatter requirements for pages - title: Clear, descriptive page title - description: Concise summary for SEO/navigation ## Writing standards - Second-person voice ("you") - Prerequisites at start of procedural content - Test all code examples before publishing - Match style and formatting of existing pages - Include both basic and advanced use cases - Language tags on all code blocks - Alt text on all images - Relative paths for internal links ## Git workflow - NEVER use --no-verify when committing - Ask how to handle uncommitted changes before starting - Create a new branch when no clear branch exists for changes - Commit frequently throughout development - NEVER skip or disable pre-commit hooks ## Do not - Skip frontmatter on any MDX file - Use absolute URLs for internal links - Include untested code examples - Make assumptions - always ask for clarification [​](https://mintlify.com/docs/guides/claude-code#sample-prompts) Sample prompts ---------------------------------------------------------------------------------- Once you have Claude Code set up, try these prompts to see how it can help with common documentation tasks. You can copy and paste these examples directly, or adapt them for your specific needs. ### [​](https://mintlify.com/docs/guides/claude-code#convert-notes-to-polished-docs) Convert notes to polished docs Turn rough drafts into proper Markdown pages with components and frontmatter. **Example prompt:** Copy Ask AI Convert this text into a properly formatted MDX page: [paste your text here] ### [​](https://mintlify.com/docs/guides/claude-code#review-docs-for-consistency) Review docs for consistency Get suggestions to improve style, formatting, and component usage. **Example prompt:** Copy Ask AI Review the files in docs/ and suggest improvements for consistency and clarity ### [​](https://mintlify.com/docs/guides/claude-code#update-docs-when-features-change) Update docs when features change Keep documentation current when your product evolves. **Example prompt:** Copy Ask AI Our API now requires a version parameter. Update our docs to include version=2024-01 in all examples ### [​](https://mintlify.com/docs/guides/claude-code#generate-comprehensive-code-examples) Generate comprehensive code examples Create multi-language examples with error handling. **Example prompt:** Copy Ask AI Create code examples for [your API endpoint] in JavaScript, Python, and cURL with error handling [​](https://mintlify.com/docs/guides/claude-code#extending-claude-code) Extending Claude Code ------------------------------------------------------------------------------------------------ Beyond manually prompting Claude Code, you can integrate it with your existing workflows. ### [​](https://mintlify.com/docs/guides/claude-code#automation-with-github-actions) Automation with GitHub Actions Run Claude Code automatically when code changes to keep docs up to date. You can trigger documentation reviews on pull requests or update examples when API changes are detected. ### [​](https://mintlify.com/docs/guides/claude-code#multi-instance-workflows) Multi-instance workflows Use separate Claude Code sessions for different tasks - one for writing new content and another for reviewing and quality assurance. This helps maintain consistency and catch issues that a single session might miss. ### [​](https://mintlify.com/docs/guides/claude-code#team-collaboration) Team collaboration Share your refined `CLAUDE.md` file with your team to ensure consistent documentation standards across all contributors. Teams often develop project-specific prompts and workflows that become part of their documentation process. ### [​](https://mintlify.com/docs/guides/claude-code#custom-commands) Custom commands Create reusable slash commands in `.claude/commands/` for frequently used documentation tasks specific to your project or team. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/mcp) [CursorConfigure Cursor to be your writing assistant\ \ Next](https://mintlify.com/docs/guides/cursor) On this page * [Getting started](https://mintlify.com/docs/guides/claude-code#getting-started) * [CLAUDE.md template](https://mintlify.com/docs/guides/claude-code#claude-md-template) * [Sample prompts](https://mintlify.com/docs/guides/claude-code#sample-prompts) * [Convert notes to polished docs](https://mintlify.com/docs/guides/claude-code#convert-notes-to-polished-docs) * [Review docs for consistency](https://mintlify.com/docs/guides/claude-code#review-docs-for-consistency) * [Update docs when features change](https://mintlify.com/docs/guides/claude-code#update-docs-when-features-change) * [Generate comprehensive code examples](https://mintlify.com/docs/guides/claude-code#generate-comprehensive-code-examples) * [Extending Claude Code](https://mintlify.com/docs/guides/claude-code#extending-claude-code) * [Automation with GitHub Actions](https://mintlify.com/docs/guides/claude-code#automation-with-github-actions) * [Multi-instance workflows](https://mintlify.com/docs/guides/claude-code#multi-instance-workflows) * [Team collaboration](https://mintlify.com/docs/guides/claude-code#team-collaboration) * [Custom commands](https://mintlify.com/docs/guides/claude-code#custom-commands) Assistant Responses are generated using AI and may contain mistakes. --- # Steps - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Components Steps Steps Example Copy Ask AI These are instructions or content that only pertain to the first step. These are instructions or content that only pertain to the second step. These are instructions or content that only pertain to the third step. Steps are the best way to display a series of actions of events to your users. You can add as many steps as desired. 1 First Step These are instructions or content that only pertain to the first step. 2 Second Step These are instructions or content that only pertain to the second step. 3 Third Step These are instructions or content that only pertain to the third step. Steps Example Copy Ask AI These are instructions or content that only pertain to the first step. These are instructions or content that only pertain to the second step. These are instructions or content that only pertain to the third step. [​](https://mintlify.com/docs/components/steps#steps-props) Steps Props -------------------------------------------------------------------------- [​](https://mintlify.com/docs/components/steps#param-children) children ReactElement\[\] required A list of `Step` components. [​](https://mintlify.com/docs/components/steps#param-title-size) titleSize string default:"p" The size of the step titles. One of `p`, `h2` and `h3`. [​](https://mintlify.com/docs/components/steps#individual-step-props) Individual Step Props ---------------------------------------------------------------------------------------------- [​](https://mintlify.com/docs/components/steps#param-children-1) children string | ReactNode required The content of a step either as plain text, or components. [​](https://mintlify.com/docs/components/steps#param-icon) icon string or svg A [Font Awesome icon](https://fontawesome.com/icons) , [Lucide icon](https://lucide.dev/icons) , or SVG code in `icon={}` [​](https://mintlify.com/docs/components/steps#param-icon-type) iconType string One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` [​](https://mintlify.com/docs/components/steps#param-title) title string The title is the primary text for the step and shows up next to the indicator. [​](https://mintlify.com/docs/components/steps#param-step-number) stepNumber number The number of the step. [​](https://mintlify.com/docs/components/steps#param-title-size-1) titleSize string default:"p" The size of the step titles. One of `p`, `h2` and `h3`. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/components/panel) [TabsToggle content using the Tabs component\ \ Next](https://mintlify.com/docs/components/tabs) Steps Example Copy Ask AI These are instructions or content that only pertain to the first step. These are instructions or content that only pertain to the second step. These are instructions or content that only pertain to the third step. Assistant Responses are generated using AI and may contain mistakes. --- # Windsurf - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Guides Windsurf Transform Windsurf into a documentation expert that understands your style guide, components, and project context through workspace rules and memories. [​](https://mintlify.com/docs/guides/windsurf#using-windsurf-with-mintlify) Using Windsurf with Mintlify ----------------------------------------------------------------------------------------------------------- Windsurf’s Cascade AI assistant can be tuned to write documentation according to your standards using Mintlify components. Workspace rules and memories provide persistent context about your project, ensuring more consistent suggestions from Cascade. * **Workspace rules** are stored in your documentation repository and shared with your team. * **Memories** provide individual context that builds up over time. We recommend setting up workspace rules for shared documentation standards. You can develop memories as you work, but since they are not shared, they will not be consistent across team members. Create workspace rules in the `.windsurf/rules` directory of your docs repo. See [Memories & Rules](https://docs.windsurf.com/windsurf/cascade/memories) in the Windsurf documentation for more information. [​](https://mintlify.com/docs/guides/windsurf#example-workspace-rule) Example workspace rule ----------------------------------------------------------------------------------------------- This rule provides Cascade with context about Mintlify components and general technical writing best practices. You can use this example rule as-is or customize it for your documentation: * **Writing standards**: Update language guidelines to match your style guide. * **Component patterns**: Add project-specific components or modify existing examples. * **Code examples**: Replace generic examples with real API calls and responses for your product. * **Style and tone preferences**: Adjust terminology, formatting, and other rules. Save your rule as a `.md` file in the `.windsurf/rules` directory of your docs repo. Copy Ask AI # Mintlify technical writing rule ## Project context - This is a documentation project on the Mintlify platform - We use MDX files with YAML frontmatter - Navigation is configured in `docs.json` - We follow technical writing best practices ## Writing standards - Use second person ("you") for instructions - Write in active voice and present tense - Start procedures with prerequisites - Include expected outcomes for major steps - Use descriptive, keyword-rich headings - Keep sentences concise but informative ## Required page structure Every page must start with frontmatter: ```yaml --- title: "Clear, specific title" description: "Concise description for SEO and navigation" --- ``` ## Mintlify components ### Callouts - `` for helpful supplementary information - `` for important cautions and breaking changes - `` for best practices and expert advice - `` for neutral contextual information - `` for success confirmations ### Code examples - When appropriate, include complete, runnable examples - Use `` for multiple language examples - Specify language tags on all code blocks - Include realistic data, not placeholders - Use `` and `` for API docs ### Procedures - Use `` component for sequential instructions - Include verification steps with `` components when relevant - Break complex procedures into smaller steps ### Content organization - Use `` for platform-specific content - Use `` for progressive disclosure - Use `` and `` for highlighting content - Wrap images in `` components with descriptive alt text ## API documentation requirements - Document all parameters with `` - Show response structure with `` - Include both success and error examples - Use `` for nested object properties - Always include authentication examples ## Quality standards - Test all code examples before publishing - Use relative paths for internal links - Include alt text for all images - Ensure proper heading hierarchy (start with h2) - Check existing patterns for consistency [​](https://mintlify.com/docs/guides/windsurf#working-with-cascade) Working with Cascade ------------------------------------------------------------------------------------------- Once your rules are set up, you can use Cascade to assist with various documentation tasks. See [Cascade](https://docs.windsurf.com/windsurf/cascade) in the Windsurf documentation for more information. ### [​](https://mintlify.com/docs/guides/windsurf#example-prompts) Example prompts **Writing new content**: Copy Ask AI Create a new page explaining how to authenticate with our API. Include code examples in JavaScript, Python, and cURL. **Improving existing content**: Copy Ask AI Review this page and suggest improvements for clarity and component usage. Focus on making the steps easier to follow. **Creating code examples**: Copy Ask AI Generate a complete code example showing error handling for this API endpoint. Use realistic data and include expected responses. **Maintaining consistency**: Copy Ask AI Check if this new page follows our documentation standards and suggest any needed changes. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/guides/cursor) [ReactBuild interactive and reusable elements with React components\ \ Next](https://mintlify.com/docs/react-components) On this page * [Using Windsurf with Mintlify](https://mintlify.com/docs/guides/windsurf#using-windsurf-with-mintlify) * [Example workspace rule](https://mintlify.com/docs/guides/windsurf#example-workspace-rule) * [Working with Cascade](https://mintlify.com/docs/guides/windsurf#working-with-cascade) * [Example prompts](https://mintlify.com/docs/guides/windsurf#example-prompts) Assistant Responses are generated using AI and may contain mistakes. --- # Migrations - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Guides Migrations You can use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to convert your existing documentation to Mintlify. We currently support automated migration for: Docusaurus ---------- ReadMe ------ Don’t see your docs provider or have a home grown system? We can still help! Please [contact support](https://mintlify.com/docs/contact-support) . [​](https://mintlify.com/docs/guides/migration#commands) Commands -------------------------------------------------------------------- * `mintlify-scrape section [url]` - Scrapes multiple pages in a site. * `mintlify-scrape page [url]` - Scrapes a single page in a site. The commands will automatically detect the framework. [​](https://mintlify.com/docs/guides/migration#installation) Installation ---------------------------------------------------------------------------- First, install the package: Copy Ask AI npm i @mintlify/scraping One-time use: Section Page Copy Ask AI npx @mintlify/scraping@latest section [url] Global installation: Copy Ask AI npm install @mintlify/scraping@latest -g Global usage: Section Page Copy Ask AI mintlify-scrape section [url] Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint. Copy Ask AI mintlify-scrape openapi-file [openApiFilename] -w, --writeFiles Whether or not to write the frontmatter files [boolean] [default: true] -o, --outDir The folder in which to write any created frontmatter files [string] Was this page helpful? YesNo [Previous](https://mintlify.com/docs/authentication-personalization/sending-data) [AnalyticsSee information about your docs' performance in your dashboard\ \ Next](https://mintlify.com/docs/guides/analytics) On this page * [Commands](https://mintlify.com/docs/guides/migration#commands) * [Installation](https://mintlify.com/docs/guides/migration#installation) Assistant Responses are generated using AI and may contain mistakes. --- # Deployments - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Guides Deployments Your documentation site automatically deploys when you push changes to your connected repository. This requires the Mintlify GitHub app to be properly installed and connected. If your latest changes are not appearing on your live site, first check that the GitHub app is installed on the account or organization that owns your docs repository. See [GitHub troubleshooting](https://mintlify.com/docs/settings/github#troubleshooting) for more information. If the GitHub app is connected, but changes are still not deploying, you can manually trigger a rebuild from your dashboard. [​](https://mintlify.com/docs/guides/deployments#manually-triggering-a-deployment) Manually triggering a deployment ---------------------------------------------------------------------------------------------------------------------- 1 Verify your latest commit was successful. Check that your latest commit appears in your docs repository and did not encounter any errors. 2 Manually trigger a deployment. Go to your [dashboard](https://dashboard.mintlify.com/) and select the deploy button. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/advanced/dashboard/roles) [Contact supportWe're here to help you get the most out of Mintlify\ \ Next](https://mintlify.com/docs/contact-support) On this page * [Manually triggering a deployment](https://mintlify.com/docs/guides/deployments#manually-triggering-a-deployment) Assistant Responses are generated using AI and may contain mistakes. --- # Monorepo setup - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Guides Monorepo setup Configure Mintlify to deploy documentation from a specific directory within a monorepo. This setup allows you to maintain documentation alongside your code in repositories that contain multiple projects or services. [​](https://mintlify.com/docs/guides/monorepo#prerequisites) Prerequisites ----------------------------------------------------------------------------- * Admin access to your Mintlify project. * Documentation files organized in a dedicated directory within your monorepo. * A valid `docs.json` in your documentation directory. [​](https://mintlify.com/docs/guides/monorepo#configure-monorepo-deployment) Configure monorepo deployment ------------------------------------------------------------------------------------------------------------- 1 Access Git settings Navigate to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) in your dashboard. 2 Set your documentation path 1. Select the **Set up as monorepo** toggle button. 2. Enter the relative path to your docs directory. For example, if your docs are in the `docs` directory, enter `/docs`. Do not include a trailing slash in the path. 3. Select **Save changes**. Was this page helpful? YesNo [Previous](https://mintlify.com/docs/settings/broken-links) [CloudflareHost documentation at a /docs subpath using Cloudflare Workers\ \ Next](https://mintlify.com/docs/advanced/subpath/cloudflare) On this page * [Prerequisites](https://mintlify.com/docs/guides/monorepo#prerequisites) * [Configure monorepo deployment](https://mintlify.com/docs/guides/monorepo#configure-monorepo-deployment) Assistant Responses are generated using AI and may contain mistakes. --- # CLI installation - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Getting started CLI installation [​](https://mintlify.com/docs/installation#installing-the-cli) Installing the CLI ------------------------------------------------------------------------------------ **Prerequisite**: Please install [Node.js](https://nodejs.org/en) before proceeding. 1 Install the CLI. Run the following command to install the [CLI](https://www.npmjs.com/package/mint) : Copy Ask AI npm i -g mint 2 Preview locally. Navigate to your docs directory (where your `docs.json` file is located) and execute the following command: Copy Ask AI mint dev A local preview of your documentation will be available at `http://localhost:3000`. Alternatively, if you do not want to install the CLI globally, you can run a one-time script: Copy Ask AI npx mint dev [​](https://mintlify.com/docs/installation#updates) Updates -------------------------------------------------------------- If your local preview is out of sync with what you see on the web in the production version, update your local CLI: Copy Ask AI mint update If this `mint update` command is not available on your local version, re-install the CLI with the latest version: Copy Ask AI npm i -g mint@latest [​](https://mintlify.com/docs/installation#custom-ports) Custom ports ------------------------------------------------------------------------ By default, the CLI uses port 3000. You can customize the port using the `--port` flag. To run the CLI on port 3333, for instance, use this command: Copy Ask AI mint dev --port 3333 If you attempt to run on a port that is already in use, it will use the next available port: Copy Ask AI Port 3000 is already in use. Trying 3001 instead. [​](https://mintlify.com/docs/installation#additional-commands) Additional commands -------------------------------------------------------------------------------------- While `mint dev` is the most commonly used command, there are other commands you can use to manage your documentation. ### [​](https://mintlify.com/docs/installation#finding-broken-links) Finding broken links The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: Copy Ask AI mint broken-links ### [​](https://mintlify.com/docs/installation#checking-openapi-spec) Checking OpenAPI spec You can use the CLI to check your OpenAPI file for errors using the following command: Copy Ask AI mint openapi-check You can pass in a filename (e.g. `./openapi.yaml`) or a URL (e.g. `https://petstore3.swagger.io/api/v3/openapi.json`). ### [​](https://mintlify.com/docs/installation#renaming-files) Renaming files You can rename and update all references to files using the following command: Copy Ask AI mint rename [​](https://mintlify.com/docs/installation#formatting) Formatting -------------------------------------------------------------------- While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files. If you use Cursor, Windsurf, or VSCode, we recommend the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) for syntax highlighting, and setting up [Prettier](https://prettier.io/docs/webstorm) for code formatting. [​](https://mintlify.com/docs/installation#troubleshooting) Troubleshooting ------------------------------------------------------------------------------ Error: Could not load the "sharp" module using the darwin-arm64 runtime This may be due to an outdated version of node. Try the following: 1. Remove the currently-installed version of the mint CLI: `npm uninstall -g mint` 2. Upgrade to Node.js. 3. Reinstall the mint CLI: `npm install -g mint` Issue: Encountering an unknown error **Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again. Error: permission denied This is due to not having the required permissions to globally install node packages. **Solution**: Try running `sudo npm i -g mint`. You will be prompted for your password, which is the one you use to unlock your computer. The local preview doesn't look the same as my docs do on the web This is likely due to an outdated version of the CLI. **Solution:** Run `mint update` to get the latest changes. mintlify vs. mint package If you have any problems with the CLI package, you should first run `npm ls -g`. This command shows what packages are globally installed on your machine. If you have a package named `mint` and a package named `mintlify` installed, you should uninstall `mintlify`. 1. Uninstall the old package: Copy Ask AI npm uninstall -g mintlify 2. Clear your npm cache: Copy Ask AI npm cache clean --force 3. Reinstall the new package: Copy Ask AI npm install -g mint Was this page helpful? YesNo [Previous](https://mintlify.com/docs/quickstart) [Web editorBuild your documentation using the Mintlify web editor\ \ Next](https://mintlify.com/docs/editor) On this page * [Installing the CLI](https://mintlify.com/docs/installation#installing-the-cli) * [Updates](https://mintlify.com/docs/installation#updates) * [Custom ports](https://mintlify.com/docs/installation#custom-ports) * [Additional commands](https://mintlify.com/docs/installation#additional-commands) * [Finding broken links](https://mintlify.com/docs/installation#finding-broken-links) * [Checking OpenAPI spec](https://mintlify.com/docs/installation#checking-openapi-spec) * [Renaming files](https://mintlify.com/docs/installation#renaming-files) * [Formatting](https://mintlify.com/docs/installation#formatting) * [Troubleshooting](https://mintlify.com/docs/installation#troubleshooting) Assistant Responses are generated using AI and may contain mistakes. --- # Changelogs - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Guides Changelogs Create a changelog for your docs by adding [Update components](https://mintlify.com/docs/components/update) to a page. Check out the [Mintlify changelog](https://mintlify.com/docs/changelog) as an example: you can include links, images, text, and demos of your new features in each update. [​](https://mintlify.com/docs/guides/changelogs#setting-up-your-changelog) Setting up your changelog ------------------------------------------------------------------------------------------------------- 1 Create a page for your changelog 1. Create a new page in your docs such as `changelog.mdx` or `updates.mdx`. 2. Add your changelog page to your navigation scheme in your `docs.json`. 2 Add Update components to your changelog Add an `Update` for each changelog entry. Include relevant information like feature releases, bug fixes, or other announcements. Example changelog.mdx Copy Ask AI --- title: "Changelog" description: "Product updates and announcements" --- Added a new Wintergreen flavor. Released a new version of the Spearmint flavor, now with 10% more mint. Released a new version of the Spearmint flavor. [​](https://mintlify.com/docs/guides/changelogs#customizing-your-changelog) Customizing your changelog --------------------------------------------------------------------------------------------------------- Control how people navigate your changelog and stay up to date with your product information. ### [​](https://mintlify.com/docs/guides/changelogs#table-of-contents) Table of contents Each `label` property for an `Update` automatically creates an entry in the right sidebar’s table of contents. This is the default navigation for your changelog. ### [​](https://mintlify.com/docs/guides/changelogs#tag-filters) Tag filters Add `tags` to your `Update` components to replace the table of contents with tag filters. Users can filter the changelog by selecting one or more tags: Tag filters example Copy Ask AI Added a new Wintergreen flavor. Released a new version of the Spearmint flavor, now with 10% more mint. Released a new version of the Spearmint flavor. Deprecated the Peppermint flavor. Released a new version of the Spearmint flavor. The table of contents and changelog filters are hidden when using `custom`, `center`, or `wide` page modes. Learn more about [page modes](https://mintlify.com/docs/pages#page-mode) . ### [​](https://mintlify.com/docs/guides/changelogs#subscribable-changelogs) Subscribable changelogs Using `Update` components creates a subscribable RSS feed at your page URL + `/rss.xml`. For example, `mintlify.com/docs/changelog/rss.xml`. New updates are automatically included in the feed when published. Example RSS feed Copy Ask AI <![CDATA[Product Updates]]> https://mintlify-changelogs-guide.mintlify.app RSS for Node Fri, 20 Jun 2025 21:36:14 GMT https://mintlify-changelogs-guide.mintlify.app <![CDATA[Subscribable changelogs]]> https://mintlify-changelogs-guide.mintlify.app/changelog#june-20-2025 https://mintlify-changelogs-guide.mintlify.app/changelog#june-20-2025 Fri, 20 Jun 2025 21:04:47 GMT RSS feeds can integrate with Slack, email, or other subscription tools to notify users of product changes. Some options include: * [Slack](https://slack.com/help/articles/218688467-Add-RSS-feeds-to-Slack) * [Email](https://zapier.com/apps/email/integrations/rss/1441/send-new-rss-feed-entries-via-email) via Zapier * Discord bots like [Readybot](https://readybot.io/) or [RSS Feeds to Discord Bot](https://rss.app/en/bots/rssfeeds-discord-bot) To make the RSS feed discoverable, you can display an RSS icon button that links to the feed at the top of the page. Add `rss: true` to the page frontmatter: Copy Ask AI --- rss: true --- Was this page helpful? YesNo [Previous](https://mintlify.com/docs/settings/seo) [Hidden pagesExclude pages from your navigation\ \ Next](https://mintlify.com/docs/guides/hidden-pages) On this page * [Setting up your changelog](https://mintlify.com/docs/guides/changelogs#setting-up-your-changelog) * [Customizing your changelog](https://mintlify.com/docs/guides/changelogs#customizing-your-changelog) * [Table of contents](https://mintlify.com/docs/guides/changelogs#table-of-contents) * [Tag filters](https://mintlify.com/docs/guides/changelogs#tag-filters) * [Subscribable changelogs](https://mintlify.com/docs/guides/changelogs#subscribable-changelogs) Assistant Responses are generated using AI and may contain mistakes. --- # Osano - Mintlify [Mintlify home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/light.svg)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/logo/dark.svg)](https://mintlify.com/) Search... ⌘KAsk AI Search... Navigation Privacy Osano Add the following to your `docs.json` file to add the [Osano](https://www.osano.com/) cookie consent manager. Integration options in docs.json Example Copy Ask AI "integrations": { "osano": "SOURCE" } The `SOURCE` can be found as the `src` value in the code snippet generated by Osano. It always starts with `https://cmp.osano.com/`. Code snippet from Osano Copy Ask AI