# Feedback
If you encounter incorrect, outdated, or confusing documentation on any page, submit feedback:
POST https://www.mintlify.com/docs/feedback
```json
{
"path": "/current-page-path",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Customize agent behavior
Source: https://www.mintlify.com/docs/agent/customize
Customize agent behavior with an `AGENTS.md` configuration file to control how the agent handles documentation tasks and follows your conventions.
Create a `.mintlify/AGENTS.md` file at the root of your documentation project to customize the agent's behavior (`Agents.md` is also an accepted filename).
Place your `AGENTS.md` file inside the `.mintlify/` directory, not at the root of your project. If you store the file at the root of your project, your custom instructions are publicly accessible by the `/agents.md` path. The `.mintlify/` directory is not served publicly so your `AGENTS.md` file is not accessible when in that directory.
If you must store your `AGENTS.md` file at the root of your project or any other directory, add it to your [`.mintignore`](/docs/organize/mintignore) file to exclude it from your documentation site.
Add any instructions that you want the agent to follow. The agent appends these instructions to its system prompt, so the instructions apply to all tasks whether you use the agent in your dashboard, on Slack, or via the API.
## What to include in AGENTS.md
Consider adding instructions for:
* **Style preferences**: Voice, tone, formatting, and terminology specific to your documentation.
* **Code standards**: Programming languages, frameworks, and coding conventions to use in examples.
* **Content requirements**: What sections or information to include for different types of pages.
* **Project context**: Specific details about your product, architecture, or user base that inform documentation decisions.
## Example AGENTS.md file
```markdown .mintlify/AGENTS.md theme={null}
# Documentation agent instructions
## Code examples
- Use TypeScript for all code examples. Our users are primarily TypeScript developers.
- Always include error handling in API call examples.
- Show both success and error response examples for all endpoints.
- Include import statements at the top of code examples.
## API documentation standards
- Every endpoint must document: authentication requirements, rate limits, and common error codes.
- Use real-world parameter values in examples (not foo/bar placeholders).
- Include a complete request/response cycle for each endpoint.
## Style and formatting
- Write for developers with 2-5 years of experience. Don't oversimplify, but explain non-obvious concepts.
- Use active voice and second person ("you").
- Date format: ISO 8601 (YYYY-MM-DD).
- When referencing UI elements, use bold: **Settings** button.
## What to include
- Add prerequisite sections to guides when users need API keys, environment setup, or dependencies.
- Include "Next steps" sections linking to related documentation.
- Add troubleshooting sections for common issues we see in support tickets.
```
# Write effective prompts
Source: https://www.mintlify.com/docs/agent/effective-prompts
Write clear, specific prompts to get better results from the Mintlify agent, with examples of effective instructions and tips for common patterns.
Think of the agent as a helpful assistant that needs your guidance to complete tasks. Give it clear instructions and context. More focused tasks are easier to complete, so break down complex projects into smaller steps.
## Make prompts specific and outcome-focused
Generic prompts like `@mintlify Improve the onboarding page` apply general best practices, but may not improve content in the specific way that you were picturing.
Try prompts based on outcomes you want your users to achieve or problems that they encounter.
* `@mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI`
* `@mintlify Developers keep getting 401 errors when following our authentication guide. Review the auth docs and add clearer examples showing how to properly format the API key`
## Use broad prompts for maintenance tasks
Use broad prompts for general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs.
* `@mintlify Find and fix all typos in the docs`
* `@mintlify change all unordered lists to use * instead of -`
## Specify a domain name for multi-site organizations
If you have multiple documentation sites, include the `subdomain` parameter in your message to specify which documentation set the agent should work on.
To find your domain name, look at your dashboard URL for the documentation set you want to update. The domain name is the last part after your organization name. For example, if your dashboard URL is `https://dashboard.mintlify.com/org-name/domain-name`, your domain name is `domain-name`.
Use the format `@mintlify subdomain= ` to prompt the agent to work on a specific documentation set.
* `@mintlify subdomain=public-docs Add a new section to the quickstart about inviting collaborators based on this PR`: Prompts the agent to update the quickstart only on the `public-docs` site.
* `@mintlify subdomain=customer-docs Update the auth docs for the new authentication method`: Prompts the agent to update the auth docs only on the `customer-docs` site.
# What is the agent?
Source: https://www.mintlify.com/docs/agent/index
Learn how the Mintlify agent researches, plans, and writes documentation, then opens pull requests with proposed changes for your team to review.
The agent is available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=agent).
The agent is an AI tool that creates pull requests with proposed changes to your documentation based on your prompts. When you send a request, the agent:
* **Researches**: Searches and reads your existing documentation, any connected repositories, relevant context, and the web.
* **Plans**: Creates a structured task list for complex documentation work.
* **Writes**: Generates or updates content following writing standards and best practices.
* **Validates**: Runs Mintlify CLI checks to ensure documentation builds correctly.
* **Creates a PR**: Opens a pull request with proposed changes for review.
All changes go through pull requests. The agent never commits directly to your main branch.
## What you can do with the agent
Use the agent to:
* Write new content based on your prompts, pull requests, Slack threads, or file attachments.
* Update existing documentation for new features or API changes.
* Process and include images, diagrams, and other files from Slack attachments.
* Search and revise code examples and API references across your docs.
* Reference source code from any repository that has the Mintlify GitHub App installed.
* Automate documentation maintenance with workflows.
* Answer questions about your docs and technical writing topics.
* Address code review feedback to maintain documentation quality.
* Capture knowledge from Slack conversations and pull requests before it gets lost.
* Navigate and coordinate changes across multiple files and directories efficiently.
## Connect your GitHub account
By default, the agent opens pull requests attributed to the Mintlify bot. To attribute pull requests to you, connect your GitHub account on the [My profile](https://dashboard.mintlify.com/settings/account) page of the dashboard.
## Connect repositories as context
The agent can only access repositories that you connect through the Mintlify GitHub App. Configure which repositories the agent can access in the agent panel **Settings** or in the [GitHub App settings](https://github.com/apps/mintlify/installations/new).
## Use AI tools alongside the agent
The agent works asynchronously through pull requests, but you can also use AI coding tools like Cursor or Claude Code locally for fast, iterative edits. Install the Mintlify [skill](/docs/ai/skillmd) and connect the [MCP server](/docs/ai/model-context-protocol) so your editor has the same context the agent uses.
To let an external agent edit your content directly through MCP tool calls, connect it to the [Mintlify MCP server](/docs/ai/mintlify-mcp).
Install the Mintlify skill for context on project structure, components, and documentation best practices:
npx skills add [https://mintlify.com/docs](https://mintlify.com/docs)
Add the Mintlify Docs MCP server for documentation search:
[https://mintlify.com/docs/mcp](https://mintlify.com/docs/mcp)
Add the Mintlify MCP server for dashboard access and content management:
[https://mcp.mintlify.com](https://mcp.mintlify.com)
## Next steps
Add the agent to your Slack workspace.
Give the agent access to your Notion workspace.
Configure the agent with an `AGENTS.md` file.
Get better results with focused prompts.
Automate recurring tasks and documentation maintenance with workflows.
# Connect Notion to the agent
Source: https://www.mintlify.com/docs/agent/notion
Connect Notion to the Mintlify agent so it can reference your workspace pages and databases as context when creating documentation updates.
Connect your Notion workspace to the agent so that it can search your Notion content and use it as context when creating documentation updates. The additional context from your team's knowledge base, product specs, and internal documentation stored in Notion helps the agent create more accurate and complete documentation.
## Connect your Notion workspace
1. Go to the [Agent](https://dashboard.mintlify.com/products/agent) page in your dashboard.
2. In the "Agent settings" section, click **Install Notion app**.
![The App settings section with the Slack and Notion install buttons.]()
![The App settings section with the Slack and Notion install buttons.]()
3. Follow the prompts to authorize Mintlify to access your Notion workspace.
4. In Notion's authorization screen, select which pages and databases to share with Mintlify.
## What the agent can do with Notion
The Notion integration uses Notion's [MCP tools](https://developers.notion.com/guides/mcp/mcp-supported-tools#mcp-tools) to search and read your workspace content.
Your content in Notion becomes additional context for the agent to use when generating documentation.
When the agent has access to your Notion workspace, it can:
* **Search Notion**: Find relevant pages and databases in your connected Notion workspace based on the context of your request.
* **Read Notion pages**: Access the content of Notion pages to use as reference material when generating documentation.
* **Reference databases**: Pull structured data from Notion databases to inform documentation updates.
## Use cases
* **Sync product specs to docs**: Reference product requirement documents and design specs stored in Notion when writing feature documentation.
* **Document from meeting notes**: Point the agent to meeting notes or decision logs in Notion to draft documentation based on team discussions.
* **Pull from internal knowledge bases**: Use internal wikis and knowledge bases in Notion as source material for public-facing documentation.
## Best practices
* **Scope access carefully**: Only grant access to the Notion pages and databases that contain information relevant to your documentation.
* **Provide specific references**: When prompting the agent, mention the specific Notion page or database you want it to reference for best results.
* **Review generated content**: Always review pull requests to ensure information from Notion is appropriately adapted for your public documentation.
# Add the agent to Slack
Source: https://www.mintlify.com/docs/agent/slack
Add the Mintlify agent to Slack to ask questions about your docs, create documentation updates from conversations, and capture team knowledge.
If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify app before you connect it.
## Connect your Slack workspace
1. Go to the [Agent](https://dashboard.mintlify.com/products/agent) page in your dashboard.
2. In the "Agent settings" section, click **Install Slack app**.
![The App settings section with the Slack and Notion install buttons.]()
![The App settings section with the Slack and Notion install buttons.]()
3. Follow the Slack prompts to install the `mintlify` app in your workspace.
4. Follow the Slack prompts to link your Mintlify account to your Slack workspace.
5. Test that the agent is working and responds when you:
* Send a direct message to the agent.
* Mention the agent with `@mintlify` in a channel.
If your organization has multiple deployments, the agent asks you to choose which deployment to work with the first time you send a request.
Your preferred deployment is personal to your Slack account and does not affect
other team members. You can switch to a different deployment at any time during a
conversation by clicking the **Switch deployment** button on the agent's status
message in the thread. The agent retains your conversation history so you can
continue where you left off with the new deployment.
## Connect additional integrations from Slack
After you connect your Slack workspace, you can ask the agent in Slack to set up any third-party integration that it should use as context. The agent uses [Composio](https://docs.composio.dev/toolkits) to support a broad catalog of third-party services, including issue trackers, knowledge bases, CRMs, and developer tools.
You must configure GitHub and GitLab through Mintlify, not Composio. Use the [GitHub app](/docs/deploy/github) or [GitLab integration](/docs/deploy/gitlab) to control which repositories the agent can access.
To add a new integration from Slack:
1. In a direct message or a thread that mentions `@mintlify`, ask the agent to set up the integration. For example:
* "Connect Jira so you can read tickets."
* "Install the HubSpot integration."
* "Set up the Linear integration."
2. The agent replies with an authorization link.
3. Click the link, sign in to the third-party service, and approve the requested permissions.
4. Return to Slack. The agent confirms the connection and can immediately use the integration as context for future requests.
Integrations that you connect from Slack apply to individual Slack users, so each teammate sets up their own connections and the agent uses the connections of whoever sent the message. If a Slack user has not connected a service, the agent falls back to the organization-level integrations installed from the [Agent](https://dashboard.mintlify.com/products/agent) page in the dashboard.
To remove or reauthorize an organization-level integration, use the **Agent settings** section of the [Agent](https://dashboard.mintlify.com/products/agent) page.
For the full list of supported services, see the [Composio toolkits catalog](https://docs.composio.dev/toolkits).
## Use the agent in Slack
Once connected, you can:
* Send direct messages to the agent to use it privately.
* Mention `@mintlify` in a channel to use it publicly and collaboratively.
* Attach files and images directly to your messages for the agent to process and include in your docs.
* Continue conversations in threads to iterate on changes or ask follow-up questions.
* Share pull request links with the agent to update related documentation.
## Ask questions about your docs
Ask the agent questions about your product or documentation and receive answers in the thread.
* **New question**: Send a direct message to the agent or mention `@mintlify` in a channel with your question.
* **Existing thread**: Reply in the thread and mention `@mintlify` with a follow-up question.
Example questions:
* "Which pages mention the API rate limit?"
* "How do I set up authentication?"
* "How is our navigation structured?"
## Update documentation
Use the agent to update your documentation with a new request or in an existing thread.
* **New request**: Send a direct message to the agent or mention `@mintlify` in a channel with instructions on what to update.
* **Existing thread**: Reply in the thread and mention `@mintlify` with instructions on what to update.
* **With attachments**: Upload images, diagrams, code files, or other documents with your message. The agent automatically processes and includes them in your documentation.
The agent reads the context of the request or thread and creates a pull request in your connected repository with the updates.
## Reference other repositories
The agent can read source code from any repository that has the Mintlify GitHub App installed, even if it isn't your documentation repository. This lets the agent build deeper context to guide documentation updates.
When you mention another repository in your request, the agent clones it on demand and inspects the relevant files before drafting changes.
Example prompts:
* "Update the authentication guide based on the changes in `acme/api-server/src/auth.ts`."
* "Document the new endpoints added in `acme/backend#1234`."
* "What repositories do you have access to?"
The agent treats cloned repositories as read-only. It uses them for context, but always opens pull requests against your documentation repository.
## Track progress in real time
When the agent is making changes to your documentation, it provides live feedback in the Slack thread.
* **Status updates**: A live-updating message shows what the agent is doing, such as how many files it has searched, read, and edited.
* **Task progress**: When the agent breaks your request into multiple tasks, it displays a checklist so you can track progress on each one.
* **Questions**: If the agent needs more information, it presents options for you to select from or reply in the thread with a custom answer.
* **Permission requests**: Before the agent runs a third-party action that writes data, such as sending an email or creating a ticket, it asks you to approve or deny the action. The permission request is only visible to the person who triggered the request. Click **Approve** to let the agent proceed or **Deny** to cancel the action.
* **Interruptions**: If you send a follow-up message while the agent is still working, it stops the current task and starts on the new one.
* **Completion**: When the agent finishes, it posts a summary with a link to the pull request and a link to open the changes in the web editor.
## Best practices
* **Be specific**: Tell the agent exactly what you want to know or what you want changed and where.
* **Add context**: If a thread doesn't contain all the necessary information, include additional details in your message to the agent.
* **Review carefully**: You should always review pull requests that the agent creates before merging them.
# Use cases
Source: https://www.mintlify.com/docs/agent/use-cases
Explore real-world examples of using the Mintlify agent to automate documentation updates, capture knowledge, and maintain accurate docs.
The agent assists with many different documentation tasks. These examples show some of the ways you can integrate the agent into your documentation process. Try an approach that fits how your team currently works and adapt it to your specific needs.
## Iterate on a prompt in a Slack thread
Prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates.
For example: `@mintlify Our quickstart page needs a new section on inviting collaborators`. Then `@mintlify The new section should be called "Inviting collaborators"`. Followed by any other iterations.
## Start with the agent, finish manually
Prompt the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task.
For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method.
## Update docs when merging feature changes
When you merge a feature pull request, share the PR link with the agent to update relevant docs.
For example: `@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`.
## Generate release notes from a pull request
Prompt the agent with a specific pull request to generate release notes or changelog updates based on the commit history.
For example: `@mintlify Generate release notes for this PR: [PR link]`.
## Address pull request review feedback
Share a pull request link with the agent to address reviewer comments and code review feedback on documentation pull requests.
For example: `@mintlify Address the review comments on this PR: [PR link]`.
## Generate code examples
Prompt the agent to generate code examples for features throughout your docs or on specific pages.
For example: `@mintlify Generate a code example to make the authentication method easier to understand`.
## Add images or files to your docs
Attach files or images directly to your Slack message when prompting the agent. The agent processes the attachment and includes it in the documentation.
For example: `@mintlify Add this diagram to the architecture overview page` with the image attached to the message.
## Review existing content
Prompt the agent to review existing content for technical accuracy, style, grammar, or other issues.
For example: `@mintlify Review the API rate limiting section. We changed limits last month`.
## Respond to user feedback
Prompt the agent with feedback from your users to make focused updates to your docs.
For example: `@mintlify Users are getting confused by step 3 in the setup guide. What might be making it unclear?`.
## Automate with workflows
Create workflows to automate recurring tasks and reactive maintenance tasks like writing changelogs or updating content when you add new features to your product.
See [Workflows](/docs/workflows/index) for more information.
## Automate with the API
Integrate the agent into your existing automation tools to automatically update documentation when code changes occur, trigger content reviews, or sync documentation updates across multiple repositories.
Use the agent endpoints to [create jobs](/docs/api/agent/v2/create-agent-job), [get job status](/docs/api/agent/v2/get-agent-job), and [send messages](/docs/api/agent/v2/send-message).
When creating jobs via the API, you can control whether pull requests open in draft mode using the `asDraft` parameter (defaults to `false`). Set `asDraft: true` to create draft pull requests, or keep the default to create non-draft pull requests ready for immediate review and merging in automated workflows.
Learn how to set up API automation in the [Auto-update documentation when code is merged](/docs/guides/automate-agent) tutorial.
# AI-native documentation
Source: https://www.mintlify.com/docs/ai-native
Discover how AI-native features enhance reading, writing, and discovering your documentation with the assistant, agent, and MCP server.
When you host your documentation on Mintlify, built-in AI features help your users find answers and your team maintain content more efficiently. Your content provides the context for these AI-native features to improve the experiences of reading, writing, and discovering your documentation.
## What makes your documentation AI-native
### Reading
In addition to reading individual pages, users can chat with the [assistant](/docs/assistant) in your documentation for immediate answers to their questions and links to relevant content. The assistant helps guide users through your product with accurate information from your documentation. Embed the assistant into custom apps with the [API](/docs/api/assistant/create-assistant-message-v2) to extend where users can access your documentation.
### Writing
The [agent](/docs/agent) helps you write and maintain documentation. It creates pull requests with proposed changes based on your prompts, pull requests, and Slack threads. Add the agent to your Slack workspace so that anyone on your team can help maintain your documentation by chatting with the agent. Or embed the agent into custom apps via the [API](/docs/api/agent/v2/create-agent-job).
Create [workflows](/docs/workflows/index) to run the agent on a schedule or on a push to a repository. Each workflow defines a prompt for the agent and a trigger for when to run it.
Configure popular tools like [Cursor](/docs/guides/cursor), [Claude Code](/docs/guides/claude-code), and [Windsurf](/docs/guides/windsurf) to reference the Mintlify schema, your style guide, and best practices.
### Discovering
Your site is automatically optimized for AI tools and search engines to help users discover your documentation. All pages send their content as Markdown to AI agents instead of HTML, which helps these tools process your content faster and use fewer tokens. Every page is also available to view as Markdown by appending `.md` to the URL. Use the [visibility](/docs/components/visibility) component to tailor content for each audience.
Mintlify hosts `llms.txt` and `skill.md` files for your documentation. These industry-standard files help LLMs respond efficiently with relevant information to user queries and provide a list of capabilities for agents to use, so that users are more successful with your product.
Teach your users how to install your `skill.md` file so they get better results when using your product with AI tools. Embed an installation prompt directly in your docs with the [`Prompt` component](/docs/components/prompt):
```mdx theme={null}
npx skills add https://your-docs-domain.com
```
Your documentation site also hosts an MCP server that lets users connect your documentation directly to their AI tools for up-to-date information about your product directly where they want it.
Full-text search and semantic understanding help users and AI tools find relevant information quickly. Search understands user intent rather than just matching keywords. And if a user encounters a 404 error, your site suggests related pages to help them find what they're looking for. No configuration required.
## Enable AI features
Select any of the following cards for more information.
Configure the assistant to search external sites or direct people to your support team if it can't answer their questions.
Get documentation updates automatically on a schedule or when a push event occurs.
Add a menu to pages that lets users query AI tools, connect to your MCP server, and copy pages as context with one click.
# Mintlify MCP
Source: https://www.mintlify.com/docs/ai/mintlify-mcp
Let AI tools directly edit your content on Mintlify with the MCP server. Connect Claude, Cursor, or any MCP client to draft, save, and ship doc changes.
## About the Mintlify MCP
The Mintlify MCP server gives AI tools write access to your Mintlify content. Where the [documentation MCP server](/docs/ai/model-context-protocol) lets AI tools read and search your published content, the Mintlify MCP lets them propose changes: edit pages, restructure navigation, update `docs.json`, and open pull requests.
Connect any MCP client like Claude, Claude Code, or Cursor to the Mintlify MCP to collaborate on your Mintlify content with the same tools you use to write code. When you use the MCP server, all changes happen on a branch and require a pull request to merge.
The Mintlify MCP edits your documentation. Treat it like a developer with commit access. Connect it only from trusted AI tools and review every pull request before merging.
### How the Mintlify MCP differs from the documentation MCP
| | Documentation MCP | Mintlify MCP |
| :------------ | :------------------------------ | :----------------------------------------------- |
| **Audience** | Your end users | Your team |
| **Access** | Read and search published pages | Read, edit, restructure, save |
| **Endpoints** | `/mcp` on your site domain | Hosted by Mintlify, scoped to your project |
| **Output** | Search results and page content | Content edits, navigation changes, pull requests |
## Connect to the Mintlify MCP
Connecting requires an interactive OAuth login against your Mintlify account. The AI tool exchanges that login for a session token scoped to one project.
1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
2. Select **Add custom connector**.
3. Add the connector
* Name: Mintlify MCP
* URL: `https://mcp.mintlify.com`
4. Select **Add** and complete the OAuth login.
Select the attachments button (the plus icon), then select your Mintlify MCP server. Claude can now call the Mintlify MCP tools while answering your prompt.
Add the Mintlify MCP server with the Claude Code CLI:
```bash theme={null}
claude mcp add --transport http mintlify https://mcp.mintlify.com
```
On first use, Claude Code opens a browser window to complete the OAuth login. After authenticating, the session is reused for subsequent calls.
1. Open the command palette with Command + Shift + P (Ctrl + Shift + P on Windows).
2. Search for **Open MCP settings** and select **Add custom MCP**.
3. In `mcp.json`, add the Mintlify MCP:
```json theme={null}
{
"mcpServers": {
"mintlify": {
"url": "https://mcp.mintlify.com"
}
}
}
```
4. Reload Cursor and complete the OAuth login when prompted.
## How a session works
Every Mintlify MCP session binds to a single Git branch. The flow is:
The first call must be `checkout`. It creates a fresh `mintlify-mcp/-` branch from your deploy branch (or attaches to an existing branch you name) and returns an `editorUrl` you can open to follow along in the dashboard editor.
Call `list_branches` before `checkout` if you need to discover or filter existing branches in the repository.
The AI uses tools like `search`, `read`, `list_nodes`, `edit_page`, `write_page`, `create_node`, and `update_config` to make changes. All edits buffer on the session branch in real time—nothing touches your deploy branch yet.
Call `diff` at any time to see exactly what changed since `main`. Open the `editorUrl` in your dashboard to see the same changes rendered.
Call `save` to flush the branch to Git. Use `mode: "pr"` (default) to open a pull request, or `mode: "commit"` to push directly to an existing PR branch.
Call `discard_session` to drop all in-session changes and release the branch.
Calling `checkout` again during an active session switches the session to the new branch. Use this to abandon an in-progress draft and start fresh without ending the conversation.
## What the Mintlify MCP can do
### Content
* **`read`** — Fetch the full MDX of any page on the session branch.
* **`search`** — Find lines matching a substring or regex across every page.
* **`edit_page`** — Apply a targeted edit to a page.
* **`write_page`** — Overwrite a page's full MDX content.
### Navigation
* **`list_nodes`** — Walk the navigation tree, filtered by type, language, version, or tab.
* **`create_node`** — Add a new page, group, tab, anchor, version, language, product, or dropdown.
* **`update_node`** — Update a node's properties in place (rename a group, change an icon, set a default version).
* **`move_node`** — Move a node, including renaming a page's path.
* **`delete_node`** — Remove a node from the navigation.
### Configuration
* **`update_config`** — Modify `docs.json` (theme, navigation roots, integrations, SEO settings).
### Session
* **`checkout`** — Bind the session to a branch.
* **`list_branches`** — List Git branches available for the project, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Call this before `checkout` to attach to an existing branch by name.
* **`get_session_state`** — Inspect the current branch, edited files, and pending nav diff.
* **`diff`** — List all changes between the session and `main`.
* **`save`** — Open a pull request or commit to the session branch.
* **`discard_session`** — Drop the session and its in-flight changes.
## Example prompts
After you connect the Mintlify MCP, you can drive it with natural-language prompts. For example:
* *"Check out a branch called `add-billing-faq` and create a new page under the FAQ group titled 'Billing'. Draft answers for the five questions in this Linear issue."*
* *"Find every page that mentions the deprecated `legacy_token` field and update the example to use `api_key` instead. Save as a PR titled 'docs: replace legacy\_token references'."*
* *"Reorganize the API reference: move the webhooks pages into a new group called 'Webhooks' and update the icons to match the rest of the section."*
## Best practices
Every `checkout` returns an `editorUrl`. Open it in a separate tab so you can watch the AI's changes render live in the dashboard editor while you prompt.
The Mintlify MCP is powerful enough to rewrite hundreds of pages in a single session. Before merging, read the PR diff and skim the rendered preview. Don't rubber-stamp large changes.
Pass a `slug` to `checkout` (for example, `add-quickstart`) so the auto-generated branch is human-readable. Without it, the branch name derives from the session token and is hard to recognize in your repository.
Keep each session focused to one change. Smaller sessions produce easier to review pull requests and preserve agents' context windows. Use `discard_session` and `checkout` again to pivot to unrelated work.
Sessions hold an in-memory branch on the Mintlify side. If you abandon a session without saving or discarding it, the branch persists until your next checkout overwrites it. Avoid leaving stale `mintlify-mcp/*` branches in your repository. Clean them up periodically.
# Add SDK examples
Source: https://www.mintlify.com/docs/api-playground/adding-sdk-examples
Add SDK code samples to your API documentation with autogenerated examples from Speakeasy and Stainless across multiple languages.
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.
Add this property to any request method. It has the following schema.
The language of the code sample.
The label for the sample. This is useful when providing multiple examples for a single endpoint.
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.
```yaml theme={null}
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 });
```
# AsyncAPI setup
Source: https://www.mintlify.com/docs/api-playground/asyncapi-setup
Set up real-time WebSocket documentation using AsyncAPI specification files to generate interactive channel and message reference pages.
## Demo
See the [WebSocket playground](/docs/api-playground/websocket-playground) for an example of the AsyncAPI playground.
## Add an AsyncAPI specification file
To create pages for your WebSocket channels, you must have a valid AsyncAPI schema document in either JSON or YAML format that follows the [AsyncAPI specification 3.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0).
Use the [AsyncAPI Studio](https://studio.asyncapi.com/) to validate your AsyncAPI schema.
```json {3} theme={null}
/your-project
|- docs.json
|- asyncapi.json
```
## Auto-populate WebSocket pages
To automatically generate pages for all channels in your AsyncAPI schema, add an `asyncapi` property to any navigation element. The `asyncapi` property accepts a path to an AsyncAPI schema document in your documentation repo, a URL to a hosted AsyncAPI document, or an array of links to AsyncAPI schema documents.
### Examples with tabs
```json Local file theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"asyncapi": "/path/to/asyncapi.json"
}
]
}
```
```json Remote URL theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"asyncapi": "https://github.com/asyncapi/spec/blob/master/examples/simple-asyncapi.yml"
}
]
}
```
```json Multiple files theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"asyncapi": [
"/path/to/events.json",
"/path/to/webhooks.json"
]
}
]
}
```
When you specify multiple AsyncAPI files, each file generates its own set of channel pages.
### Examples with groups
```json theme={null}
"navigation": {
"tabs": [
{
"tab": "AsyncAPI",
"groups": [
{
"group": "Websockets",
"asyncapi": {
"source": "/path/to/asyncapi.json",
"directory": "websockets"
}
}
]
}
]
}
```
The `directory` field is optional. If not specified, Mintlify adds the files to the **api-reference** folder of the docs repository.
### Examples with nested groups
The `asyncapi` property supports nested groups. Mintlify generates the channel pages and adds them to the nested group, alongside any existing pages.
This is useful when you want to organize WebSocket channels as a subsection of a broader API group, or when you need to combine multiple AsyncAPI specifications under a shared parent group.
```json theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Voice API",
"pages": [
"voice/overview",
{
"group": "Voice API Commands",
"asyncapi": "/path/to/voice-asyncapi.json"
}
]
}
]
}
]
}
```
## Channel page
If you want more control over how you order your channels or if you want to reference only specific channels, create an MDX file with the `asyncapi` property in the frontmatter.
```mdx theme={null}
---
title: "Websocket Channel"
asyncapi: "/path/to/asyncapi.json channelName"
---
```
# Complex data types
Source: https://www.mintlify.com/docs/api-playground/complex-data-types
Describe APIs with flexible schemas using oneOf, anyOf, and allOf keywords for optional properties, polymorphism, and multiple data formats.
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.
## `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.
### 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/).
```yaml theme={null}
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
```
The ID of the organization
An array containing all users in the organization
### Providing options with `oneOf` and `anyOf`
When you use `oneOf` or `anyOf`, the options display 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:
```yaml theme={null}
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
# ...
```
The street address of the residence
The number of the PO Box
# Manage page visibility
Source: https://www.mintlify.com/docs/api-playground/managing-page-visibility
Control which API endpoints appear in your documentation navigation by hiding, filtering, or organizing autogenerated OpenAPI pages.
For internal-only endpoints, deprecated operations, beta features, or endpoints that should be accessible via direct URL but not discoverable through site navigation, you can control which OpenAPI operations get published as documentation pages and their visibility in navigation.
If your pages are autogenerated from an OpenAPI document, manage page visibility with the `x-hidden` and `x-excluded` extensions.
## `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 link to from other content.
* Endpoints for specific users.
## `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.
## 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.
```json Endpoint example {11, 19} theme={null}
"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": { /*...*/ }
}
}
},
```
```json Webhook example {9, 15} theme={null}
"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!)"
}
}
}
```
# Create manual API pages
Source: https://www.mintlify.com/docs/api-playground/mdx-setup
Create API reference pages manually with MDX files when you need full control over layout for small APIs, prototypes, or custom docs.
You can manually define API endpoints in individual MDX pages. This approach is useful for small APIs or prototyping.
## Setup
In your `docs.json` file, define your base URL and authentication method.
```json Example docs.json theme={null}
"api": {
"mdx": {
"server": "https://api.acme.com/",
"auth": {
"method": "key",
"name": "x-api-key"
}
}
}
```
If you want to hide the API playground, set the `display` field to `none`. You don't need to include an authentication method if you hide the playground.
```json theme={null}
"api": {
"playground": {
"display": "none"
}
}
```
Find a full list of API configurations in [Settings](/docs/organize/settings-api).
Create an MDX file for each endpoint. Define the `title` and `api` in the frontmatter:
```mdx theme={null}
---
title: 'Create new user'
api: 'POST /v1/users'
---
```
The `api` frontmatter field accepts either a full URL or a relative path:
* **Full URL** like `POST https://api.acme.com/v1/users`. The `server` field in `docs.json` is ignored for that endpoint.
* **Relative path** like `POST /v1/users`. Requires a `server` field in `docs.json`. The server URL is prepended to the path.
Specify path parameters by wrapping them in `{}`:
```bash theme={null}
https://api.example.com/v1/endpoint/{userId}
```
To override the global playground display mode for a specific page, add `playground` to the frontmatter:
```mdx theme={null}
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
```
Options:
* `playground: 'interactive'` - Display the interactive playground (default)
* `playground: 'simple'` - Display a copyable endpoint with no playground
* `playground: 'none'` - Hide the playground entirely
Use [parameter and response fields](/docs/components/fields) to document your endpoint's parameters and return values.
```mdx theme={null}
Unique identifier for the user
User's email address
Unique identifier for the newly created user
User's email address
```
Add your endpoint pages to the navigation by updating the `pages` field in your `docs.json`:
```json docs.json theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Users",
"pages": [
"api-reference/users/create-user",
"api-reference/users/get-user",
"api-reference/users/update-user"
]
},
{
"group": "Orders",
"pages": [
"api-reference/orders/create-order",
"api-reference/orders/list-orders"
]
}
]
}
]
}
```
Each page path corresponds to an MDX file in your docs repository. For example, `api-reference/users/create-user.mdx`. Learn more about structuring your docs in [Navigation](/docs/organize/navigation).
### Using OpenAPI endpoints in navigation
If you have an OpenAPI specification, you can reference endpoints directly in your navigation without creating individual MDX files. Reference specific endpoints by including the OpenAPI file path and the endpoint:
```json docs.json theme={null}
"navigation": {
"pages": [
"introduction",
"/path/to/users-openapi.json POST /users",
"/path/to/orders-openapi.json GET /orders"
]
}
```
You can also set a default OpenAPI spec for a navigation group and reference endpoints by method and path:
```json docs.json theme={null}
{
"group": "API reference",
"openapi": "/path/to/openapi-v1.json",
"pages": [
"overview",
"authentication",
"GET /users",
"POST /users",
{
"group": "Orders",
"openapi": "/path/to/openapi-v2.json",
"pages": [
"GET /orders",
"POST /orders"
]
}
]
}
```
For more details on OpenAPI integration, see [OpenAPI setup](/docs/api-playground/openapi-setup).
## Enable authentication
You can set authentication globally in `docs.json` or override it on individual pages using the `authMethod` field in frontmatter. A page-specific method overrides the global setting.
### Bearer token
```json docs.json theme={null}
"api": {
"mdx": {
"auth": {
"method": "bearer"
}
}
}
```
```mdx Page Metadata theme={null}
---
title: "Your page title"
authMethod: "bearer"
---
```
### Basic authentication
```json docs.json theme={null}
"api": {
"mdx": {
"auth": {
"method": "basic"
}
}
}
```
```mdx Page Metadata theme={null}
---
title: "Your page title"
authMethod: "basic"
---
```
### API key
```json docs.json theme={null}
"api": {
"mdx": {
"auth": {
"method": "key",
"name": "x-api-key"
}
}
}
```
```mdx Page Metadata theme={null}
---
title: "Your page title"
authMethod: "key"
---
```
### None
To disable authentication on a specific page, set `authMethod` to `none`:
```mdx Page Metadata theme={null}
---
title: "Your page title"
authMethod: "none"
---
```
# Multiple responses
Source: https://www.mintlify.com/docs/api-playground/multiple-responses
Document multiple response variations for API endpoints, including success and error cases, with status codes and example payloads.
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.
Add this property to any response. It has the following schema.
```yaml theme={null}
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
```
The playground also handles non-JSON response types differently based on their content type.
## Audio response examples
For endpoints that return audio files, set the response content type to `audio/*` and provide a URL to an audio file as the example value. The playground renders an interactive audio player instead of a code snippet.
```yaml theme={null}
responses:
"200":
description: Audio file generated successfully
content:
audio/mpeg:
schema:
type: string
format: binary
examples:
sample:
summary: Sample audio output
value: "https://example.com/sample-audio.mp3"
```
# OpenAPI setup
Source: https://www.mintlify.com/docs/api-playground/openapi-setup
Generate interactive API documentation from OpenAPI specification files with automatic endpoint pages, request builders, and navigation.
OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0 and 3.1 documents to generate interactive API documentation and keep it up to date.
## Add an OpenAPI specification file
To document your endpoints with OpenAPI, you need one or more valid OpenAPI specifications in either JSON or YAML format that follow the [OpenAPI specification 3.0 or 3.1](https://swagger.io/specification/).
Add OpenAPI specifications to your documentation repository or host them online where you can access the specifications by URL. Specifications stored in your repository are [served as downloadable files](/docs/create/files) at their path on your docs domain. For example, `https://your-domain/docs/openapi.json`.
Reference any number of OpenAPI specifications in the navigation element of your `docs.json` to create pages for your API endpoints. Each specification file generates its own set of endpoints.
```json Single specification theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": "openapi.json"
}
]
}
```
```json Multiple specifications theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": [
"openapi/v1.json",
"openapi/v2.json"
]
}
]
}
```
Mintlify supports `$ref` for **internal references only** within a single OpenAPI document. External references are not supported.
### Describe your API
We recommend the following resources to learn about and construct your OpenAPI specification.
* [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/v3_0/basic-structure/) to learn the OpenAPI syntax.
* [The OpenAPI specification Markdown sources](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) to reference details of the latest OpenAPI specification.
* [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 validate`.
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.
### Specify the base URL for your API
To enable the API playground, add a `servers` field to your OpenAPI specification with your API's base URL.
```json theme={null}
{
"servers": [
{
"url": "https://api.example.com/v1"
}
]
}
```
In an OpenAPI specification, 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 allows users to toggle between servers. If you do not specify a server, the API playground uses 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 `servers` field](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) for a given path or operation.
### Specify authentication
To enable authentication in your API documentation and playground, configure the `securitySchemes` and `security` fields in your OpenAPI specification. The API descriptions and API playground add authentication fields based on the security configurations in your OpenAPI specification.
Add a `securitySchemes` field to define how users authenticate.
This example shows a configuration for bearer authentication.
```json theme={null}
{
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
```
Add a `security` field to require authentication.
```json theme={null}
{
"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.
#### Set default values for security schemes
Use the `x-default` extension on a security scheme to pre-fill the authentication field in the API playground. This is useful for providing placeholder values or test credentials that help users get started quickly.
```json {6} theme={null}
{
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"x-default": "your-api-key-here"
}
}
}
}
```
The `x-default` extension supports `apiKey` and `http` bearer security scheme types. The value appears as the default input in the playground's authentication fields.
You can also use `x-default` on any schema property in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition.
## Customize your endpoint pages
Customize your endpoint pages by adding the `x-mint` extension to your OpenAPI specification. The `x-mint` extension gives you additional control over how your API documentation generates and displays.
### Metadata
Override the default metadata for generated API pages by adding `x-mint: metadata` to any operation. You can use any metadata field that would be valid in MDX frontmatter except for `openapi`.
```json {7-14} theme={null}
{
"paths": {
"/users": {
"get": {
"summary": "Get users",
"description": "Retrieve a list of users",
"x-mint": {
"metadata": {
"title": "List all users",
"sidebarTitle": "List users",
"description": "Fetch paginated user data with filtering options",
"og:title": "Display a list of users"
}
},
"parameters": [
{
// Parameter configuration
}
]
}
}
}
}
```
You can also control playground display per endpoint using the `playground` and `groups` metadata fields:
```json {7-11} theme={null}
{
"paths": {
"/admin/users": {
"post": {
"summary": "Create admin user",
"x-mint": {
"metadata": {
"playground": "auth",
"groups": ["admin"],
"public": true
}
}
}
}
}
}
```
This configuration makes the page publicly visible while restricting the interactive playground to authenticated users in the `admin` group.
### Content
Add content before the auto-generated API documentation using `x-mint: content`. The `x-mint: content` extension supports all Mintlify MDX components and formatting.
```json {6-8} theme={null}
{
"paths": {
"/users": {
"post": {
"summary": "Create user",
"x-mint": {
"content": "## Prerequisites\n\nThis endpoint requires admin privileges and has rate limiting.\n\nUser emails must be unique across the system."
},
"parameters": [
{
// Parameter configuration
}
]
}
}
}
}
```
### href
Set the URL of the autogenerated endpoint page using `x-mint: href`. When `x-mint: href` is present, the generated API page uses the specified URL instead of the default autogenerated URL.
```json {6-8, 14-16} theme={null}
{
"paths": {
"/legacy-endpoint": {
"get": {
"summary": "Legacy endpoint",
"x-mint": {
"href": "/deprecated-endpoints/legacy-endpoint"
}
}
},
"/documented-elsewhere": {
"post": {
"summary": "Special endpoint",
"x-mint": {
"href": "/guides/special-endpoint-guide"
}
}
}
}
}
```
### Parameter pills
Annotate parameters in the API reference and playground with custom pill labels using `x-mint.pre` and `x-mint.post` on any schema. Pre pills render before the parameter name and post pills render after it, alongside Mintlify's built-in pills like `required`, `read-only`, and `write-only`.
Both fields accept an array of strings. Each string becomes its own pill.
```json {7-10} theme={null}
{
"components": {
"schemas": {
"User": {
"properties": {
"email": {
"type": "string",
"x-mint": {
"pre": ["PII"],
"post": ["indexed", "unique"]
}
}
}
}
}
}
}
```
To surface arbitrary OpenAPI spec fields as pills across every parameter without editing each schema, configure [`api.params.post`](/docs/organize/settings-api#api-params) in your `docs.json`. List the field keys you want to display, and Mintlify reads each value from the schema and renders matching pills automatically.
```json theme={null}
{
"api": {
"params": {
"post": ["nullable", "x-internal"]
}
}
}
```
With this configuration, a property like `{ "type": "string", "nullable": true, "x-internal": "admin" }` renders `nullable` and `admin` pills next to its name. Post pills appear in this order: built-in pills (`read-only`, `write-only`), then `api.params.post` config-driven pills, then per-property `x-mint.post` pills.
### Group display names
Set a custom display name for a tag's navigation group using the `x-group` extension on a tag object. By default, Mintlify uses the tag `name` as both the navigation group label and the URL path segment. The `x-group` extension overrides the group label while keeping the tag name for the URL.
This is useful when you want a human-readable group name that differs from the tag used in your API paths.
```json {4-9} theme={null}
{
"tags": [
{
"name": "user-management",
"description": "Endpoints for managing users",
"x-group": "User Management"
}
],
"paths": {
"/users": {
"get": {
"tags": ["user-management"],
"summary": "List users"
}
}
}
}
```
In this example, the navigation group displays as "User Management" but the generated page URL still uses the `user-management` tag name as its path segment.
## Auto-populate API pages
Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.
The `openapi` field accepts either a path in your docs repo or a URL to a hosted OpenAPI document.
When you use a URL for your OpenAPI spec, changes to the spec don't trigger a Git push, so your docs won't redeploy automatically. To keep your docs in sync, call the [Trigger deployment](/docs/api/update/trigger) API endpoint in the same CI action that generates or updates your spec. This way your docs update automatically without needing to manually trigger a deployment from the dashboard.
Generated endpoint pages have these default metadata values:
* `title`: The operation's `summary` field, if present. If there is no `summary`, Mintlify generates the title from the HTTP method and endpoint.
* `description`: The operation's `description` field, if present.
* `version`: The `version` value from the parent anchor or tab, if present.
* `deprecated`: The operation's `deprecated` field. If `true`, a deprecated label appears next to the endpoint title in the side navigation and on the endpoint page.
To exclude specific endpoints from your auto-generated API pages, add the [x-hidden](/docs/api-playground/managing-page-visibility#x-hidden) property to the operation in your OpenAPI spec.
There are two approaches for adding endpoint pages into your documentation:
1. **Dedicated API sections**: Reference OpenAPI specs in navigation elements for dedicated API sections.
2. **Selective endpoints**: Reference specific endpoints in your navigation alongside other pages.
### Dedicated API sections
Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. All endpoints in the specification appear in the generated section.
```json {5} theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
}
]
}
```
To organize multiple OpenAPI specifications in separate sections of your documentation, assign each specification to a different group in your navigation hierarchy. Each group can reference its own OpenAPI specification.
```json {8-11, 15-18} theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"groups": [
{
"group": "Users API",
"openapi": {
"source": "/path/to/users-openapi.json",
"directory": "users-api-reference"
}
},
{
"group": "Admin API",
"openapi": {
"source": "/path/to/admin-openapi.json",
"directory": "admin-api-reference"
}
}
]
}
]
}
```
The `directory` field is optional and specifies where Mintlify stores generated API pages in your docs repo. If not specified, defaults to the `api-reference` directory of your repo.
### Selective endpoints
When you want more control over where endpoints appear in your documentation, you can reference specific endpoints in your navigation. This approach allows you to generate pages for API endpoints alongside other content. You can also use this approach to mix endpoints from different OpenAPI specifications.
#### Set a default OpenAPI spec
Configure a default OpenAPI specification for a navigation element. Then reference specific endpoints in the `pages` field.
```json {12, 15-16} theme={null}
"navigation": {
"tabs": [
{
"tab": "Getting started",
"pages": [
"quickstart",
"installation"
]
},
{
"tab": "API reference",
"openapi": "/path/to/openapi.json",
"pages": [
"api-overview",
"GET /users",
"POST /users",
"guides/authentication"
]
}
]
}
```
Any page entry matching the format `METHOD /path` generates an API page for that endpoint using the default OpenAPI specification.
#### OpenAPI spec inheritance
Child navigation elements inherit their parent's OpenAPI specification unless they define their own.
```json {3, 7-8, 11, 13-14} theme={null}
{
"group": "API reference",
"openapi": "/path/to/openapi-v1.json",
"pages": [
"overview",
"authentication",
"GET /users",
"POST /users",
{
"group": "Orders",
"openapi": "/path/to/openapi-v2.json",
"pages": [
"GET /orders",
"POST /orders"
]
}
]
}
```
#### Individual endpoints
Reference specific endpoints without setting a default OpenAPI specification by including the file path. You can reference endpoints from multiple OpenAPI specifications in the same documentation section.
```json {5-6} theme={null}
"navigation": {
"pages": [
"introduction",
"user-guides",
"/path/to/users-openapi.json POST /users",
"/path/to/orders-openapi.json GET /orders"
]
}
```
This approach is useful when you need individual endpoints from different specifications, only want to include select endpoints, or want to include endpoints alongside other types of documentation.
## Create MDX pages from your OpenAPI specification
For more granular control over individual endpoint pages, create MDX pages from your OpenAPI specification. This lets you customize page metadata, content, and reorder or exclude pages in your navigation while still using the auto-generated parameters and responses.
There are two ways to document your OpenAPI specification with individual MDX pages:
* Document endpoints with the `openapi` field in the frontmatter.
* Document data models with the `openapi-schema` field in the frontmatter.
### Document endpoints
Create a page for each endpoint and specify which OpenAPI operation to display using the `openapi` field in the frontmatter.
```mdx Example theme={null}
---
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"
---
```
```mdx Format theme={null}
---
title: "title of the page"
description: "description of the page"
openapi: openapi-file-path method path
deprecated: boolean (not required)
version: "version-string" (not required)
---
```
The method and path must exactly match your OpenAPI spec. If you have multiple OpenAPI specifications, include the path to the correct specification in your reference. You can also reference external OpenAPI URLs in `docs.json`.
#### Autogenerate endpoint pages
To autogenerate MDX files from your OpenAPI specification, use the Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping).
```bash theme={null}
npx @mintlify/scraping@latest openapi-file -o
```
Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files populate in the working directory.
### Document data models
Create a page for each data structure defined in your OpenAPI specification's `components.schemas` using the `openapi-schema` field in the frontmatter.
```mdx Example theme={null}
---
openapi-schema: OrderItem
---
```
```mdx Format theme={null}
---
openapi-schema: "openapi-file-path schema-key"
---
```
If you have schemas with the same name in multiple files, specify the OpenAPI file:
```mdx Example theme={null}
---
openapi-schema: en-schema.json OrderItem
---
```
```mdx Format theme={null}
---
openapi-schema: "path-to-schema-file schema-key"
---
```
## Webhooks
Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. OpenAPI 3.1+ documents support webhooks.
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.
To create an MDX page for a webhook (OpenAPI 3.1+), use `webhook` instead of an HTTP method:
```mdx theme={null}
---
title: "Order updated webhook"
description: "Triggered when an order is updated"
openapi: "openapi.json webhook orderUpdated"
---
```
The webhook name must exactly match the key in your OpenAPI spec's `webhooks` field.
# Playground
Source: https://www.mintlify.com/docs/api-playground/overview
Let developers test API endpoints directly in your documentation with an interactive playground that sends real requests and shows responses.
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.
See [Trigger an update](/docs/api/update/trigger) for an example of the API playground in action.
![API playground for the trigger an update endpoint.]()
![API playground for the trigger an update endpoint.]()
The playground generates interactive pages for your endpoints based on your OpenAPI specification or AsyncAPI schema. If you modify your API, the playground automatically updates the relevant pages.
We recommend generating your API playground from an OpenAPI specification. However, you can manually create API reference pages after defining a base URL and authentication method in your `docs.json`.
## Get started
Validate your OpenAPI specification file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint) command `mint validate`.
```bash {3} theme={null}
/your-project
|- docs.json
|- openapi.json
```
Update your `docs.json` to reference your OpenAPI specification.
**To automatically generate pages for all endpoints in your OpenAPI specification**, add an `openapi` property to any navigation element.
This example generates a page for each endpoint specified in `openapi.json` and organizes the pages in the "API reference" group.
```json Generate all endpoint pages theme={null}
"navigation": {
"groups": [
{
"group": "API reference",
"openapi": "openapi.json"
}
]
}
```
**To generate pages for only specific endpoints**, list the endpoints in the `pages` property of the navigation element.
This example generates pages for only the `GET /users` and `POST /users` endpoints. To generate other endpoint pages, add additional endpoints to the `pages` array.
```json Generate specific endpoint pages theme={null}
"navigation": {
"groups": [
{
"group": "API reference",
"openapi": "openapi.json",
"pages": [
"GET /users",
"POST /users"
]
}
]
}
```
## Customize your playground
Customize your API playground by defining the following properties in your `docs.json`.
Configurations for the API playground.
The display mode of the API playground.
* `"interactive"`: Display the interactive playground.
* `"simple"`: Display a copyable endpoint with no playground.
* `"none"`: Display nothing.
* `"auth"`: Display the interactive playground only to authenticated users. Unauthenticated users or users not in the required groups see no playground.
Defaults to `interactive`.
Whether to pass API requests through Mintlify's proxy server. Defaults to `true`.
When `true`, playground requests are routed through Mintlify's servers. When `false`, the playground sends requests directly from the browser to your API. Set to `false` when your API accepts direct browser requests and you don't need Mintlify to proxy the traffic. For example, when your API requires specific headers that can't be forwarded through the proxy or when you need the request to originate directly from the user's browser for authentication purposes.
Whether to include cookies, authorization headers, and TLS client certificates for cross-origin requests when `proxy` is `false`. Defaults to `false`.
When `true` and `proxy` is `false`, the playground sends requests with browser-managed credentials included. For example, when your API uses cookie-based authentication or HTTP session tokens.
This option has no effect when `proxy` is `true`.
The display mode for base URLs in endpoint headers. When set to `full`, the full base URL displays for every endpoint page. By default, only the relative endpoint path displays.
Configurations for the autogenerated API examples.
Example languages for the autogenerated API snippets.
Languages display in the order specified.
| Display name | Key | Aliases |
| ------------ | ------------ | ------------------------- |
| cURL | `bash` | `curl`, `sh`, `shell` |
| Python | `python` | `py` |
| JavaScript | `javascript` | `js` |
| Node.js | `node` | `nodejs`, `node.js` |
| PHP | `php` | |
| Go | `go` | `golang` |
| Java | `java` | |
| Ruby | `ruby` | `rb` |
| PowerShell | `powershell` | |
| Swift | `swift` | |
| C# | `csharp` | `c#` |
| .NET | `dotnet` | `.net`, `.NET`, `dot-net` |
| TypeScript | `typescript` | `ts` |
| C | `c` | |
| C++ | `c++` | `cpp` |
| Kotlin | `kotlin` | `kt` |
| Rust | `rust` | `rs` |
| Dart | `dart` | `flutter` |
Whether to show optional parameters in API examples. Defaults to `all`.
Whether to prefill the API playground with data from schema examples. When enabled, the playground automatically populates request fields with example values from your OpenAPI specification. Defaults to `false`.
Whether to generate code samples for endpoints from API specifications. Defaults to `true`. When set to `false`, only manually written code samples (from `x-codeSamples` in OpenAPI specifications or `` components in MDX) appear in the API playground.
### Example configuration
This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. It only shows required parameters in the code snippets, and the playground prefills the request body with example values.
```json theme={null}
{
"api": {
"playground": {
"display": "interactive"
},
"examples": {
"languages": ["curl", "python", "javascript"],
"defaults": "required",
"prefill": true
}
}
}
```
### Auth-based playground display
Use the `auth` display mode to show the interactive playground only to authenticated users. This is useful when you want to let users view your API documentation publicly while restricting playground access to logged-in users.
When `display` is set to `auth`:
* Authenticated users see the interactive playground.
* Unauthenticated users see no playground (equivalent to `none`).
You can also combine `auth` with the `groups` property in page frontmatter to restrict playground access to specific user groups.
```mdx Page with group-restricted playground theme={null}
---
title: "Create user"
openapi: POST /users
playground: auth
groups: ["admin", "developer"]
public: true
---
```
In this example:
* The page is publicly visible (anyone can view the documentation).
* Only authenticated users in the `admin` or `developer` groups see the interactive playground.
* Users not in those groups see no playground.
If the page has no `groups` property, all authenticated users see the interactive playground.
The `auth` display mode requires your documentation to have [authentication](/docs/deploy/authentication-setup) configured.
### Custom endpoint pages
When you need more control over your API documentation, use the `x-mint` extension in your OpenAPI specification or create individual MDX pages for your endpoints.
Both options allow you to:
* Customize page metadata
* Add additional content like examples
* Control playground behavior per page
We recommend the `x-mint` extension so that all of your API documentation generates automatically from your OpenAPI specification and stays maintained in one file.
We recommend individual MDX pages for small APIs or when you want to experiment with changes on a per-page basis.
## Response rendering
The playground automatically renders responses based on the `Content-Type` header returned by your API.
* **Images**: Rendered inline (`image/*`).
* **Audio**: Rendered with a built-in audio player (`audio/*`).
* **Video**: Rendered with a built-in video player (`video/*`). Any response with a `video/*` content type, such as `video/mp4` or `video/webm`, displays as a playable video directly in the playground.
* **All other responses**: Displayed in a code block.
## Parameter anchor links
Every parameter in the API playground has a clickable anchor link. Hover over a parameter name to reveal the link icon, then click to copy a direct URL to that parameter.
Use parameter anchor links to:
* Share links to specific parameters in support conversations or documentation
* Navigate directly to a parameter from another page or external resource
* Bookmark frequently referenced parameters
The URL format is `your-docs-url/endpoint-path#parameter-name`. For nested parameters, the anchor includes the parent path.
## Further reading
* [OpenAPI setup](/docs/api-playground/openapi-setup) for more information on creating your OpenAPI document.
* [x-mint extension](/docs/api-playground/openapi-setup#customize-your-endpoint-pages) for more information on customizing your endpoint pages.
* [MDX setup](/docs/api-playground/mdx-setup) for more information on manually creating individual API reference pages.
* [AsyncAPI setup](/docs/api-playground/asyncapi-setup) for more information on creating your AsyncAPI schema to generate WebSocket reference pages.
# Troubleshooting
Source: https://www.mintlify.com/docs/api-playground/troubleshooting
Troubleshoot common issues with API playground configuration, including OpenAPI validation errors, missing endpoints, and auth problems.
If your API pages aren't displaying correctly, check these common configuration issues.
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 passes 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):
![Screenshot of the Swagger Editor with the Edit menu expanded and the "Convert to OpenAPI 3" menu item highlighted.]()
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.
Mintlify automatically resolves trailing slash differences between your `openapi` reference
and the OpenAPI specification. For example, `GET /users/{id}/` matches a specification path of `/users/{id}`.
Here's an example of how things might go wrong:
```mdx get-user.mdx theme={null}
---
openapi: "GET /user/{id}"
---
```
```yaml openapi.yaml theme={null}
paths:
"/users/{id}":
get: ...
```
Notice that the path in the `openapi` field says `/user/{id}` (singular), whereas the path in the OpenAPI
document is `/users/{id}` (plural).
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:
```mdx api-reference/v1/users/get-user.mdx theme={null}
---
openapi: "v1 GET /users/{id}"
---
```
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
`/_mintlify/api/request` path on the docs site. If you configure your reverse proxy to only allow `GET`
requests, then all of these requests fail. To fix this, configure your reverse proxy to
allow `POST` requests to the `/_mintlify/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](/docs/organize/settings-api). When using this configuration, you must configure CORS on your server since requests come directly from users' browsers rather than through your proxy.
If you are using an OpenAPI navigation configuration, but the pages aren't generating, check these common issues:
1. **Missing default OpenAPI spec**: Ensure you have an `openapi` field set for the navigation element:
```json {5} theme={null}
"navigation": {
"groups": [
{
"group": "API reference",
"openapi": "/path/to/openapi.json",
"pages": [
"GET /users",
"POST /users"
]
}
]
}
```
2. **OpenAPI spec inheritance**: If using nested navigation, ensure child groups inherit the correct OpenAPI spec or specify their own.
3. **Validation issues**: Use `mint validate` to verify your OpenAPI document is valid.
1. **Hidden operations**: Operations marked with `x-hidden: true` in your OpenAPI spec won't appear in auto-generated navigation.
2. **Invalid operations**: Operations with validation errors in the OpenAPI spec may be skipped. Check your OpenAPI document for syntax errors.
3. **Manual vs automatic inclusion**: If you reference any endpoints from an OpenAPI spec, only the explicitly referenced operations appear in navigation. No other pages are automatically added. This includes operations that are referenced in child navigation elements.
When combining OpenAPI operations with regular documentation pages in navigation:
1. **File conflicts**: You cannot have both an `MDX` file and a navigation entry for the same operation. For example, if you have `get-users.mdx`, do not also include `"GET /users"` in your navigation. If you need to have a file that shares a name with an operation, use the `x-mint` extension for the endpoint to have the href point to a different location.
2. **Path resolution**: Navigation entries that don't match OpenAPI operations are treated as file paths. Ensure your `MDX` files exist at the expected locations.
3. **Case sensitivity**: OpenAPI operation matching is case-sensitive. Ensure HTTP methods are uppercase in navigation entries.
# Analyze your documentation
Source: https://www.mintlify.com/docs/cli/analytics
Use the mint analytics command to view traffic, search queries, user feedback, and AI assistant conversations directly from your terminal.
The `mint analytics` command gives you access to your [documentation analytics](/docs/optimize/analytics) from the terminal. This is useful for scripting analytics reports, piping data into other tools, and quick checks without opening the dashboard.
## Prerequisites
You must log in to use analytics commands. Run `mint login` to authenticate with your Mintlify account.
See [Preview locally](/docs/cli/preview#log-in-for-search-and-assistant) for details on authentication.
## View key metrics
Display a summary of views, visitors, searches, feedback, and assistant usage:
```bash theme={null}
mint analytics stats
```
Use flags to filter by date range or page:
* `--from`: Start date in `YYYY-MM-DD` format. Defaults to 7 days ago.
* `--to`: End date in `YYYY-MM-DD` format. Defaults to today.
* `--page`: Filter to a specific page path.
```bash Example analytics stats flags theme={null}
mint analytics stats --from 2025-01-01 --to 2025-01-31
mint analytics stats --page /quickstart
```
## View search analytics
See what your users are searching for, with hit counts and click-through rates:
```bash theme={null}
mint analytics search
```
Use flags to filter by query string or page:
* `--query`: Filter by search query substring.
* `--page`: Filter to a specific page path.
```bash Example analytics search flags theme={null}
mint analytics search --query "authentication"
mint analytics search --page /api-reference
```
## View feedback
Review feedback submitted by users on your documentation pages:
```bash theme={null}
mint analytics feedback
```
Use flags to aggregate feedback by page, or filter to code snippet feedback:
* `--type`: Aggregate feedback by page or code snippet. Defaults to page.
* `--page`: Filter to a specific page path.
```bash Example analytics feedback flags theme={null}
mint analytics feedback --type page
mint analytics feedback --type code
```
## View assistant conversations
List recent conversations and conversation category buckets from the AI assistant:
```bash theme={null}
mint analytics conversation list
mint analytics conversation buckets list
```
Each list output includes an ID for each entry. Pass that ID to the corresponding `view` command to see full details:
```bash theme={null}
mint analytics conversation view
mint analytics conversation buckets view
```
## Choose an output format
All analytics commands default to `plain` output, which is tab-separated and suitable for piping to other tools. Use `--format` to change the output:
```bash theme={null}
mint analytics stats --format table # Pretty-printed table with colors
mint analytics stats --format json # Raw JSON
mint analytics stats --format graph # Horizontal bar chart
```
The CLI automatically detects AI agent environments like Claude Code or non-interactive terminals and defaults to JSON output.
## Set defaults with config
To avoid repeating common flags, set defaults with `mint config`. The configuration saves in `~/.config/mintlify/config.json`.
When you run `mint login`, the CLI sets the `subdomain` key. If you have multiple deployments, the CLI prompts you to choose one. You can override the default at any time with `mint config set subdomain `.
Available configuration keys:
| Key | Description |
| ----------- | -------------------------------------------------------------------------- |
| `subdomain` | Default subdomain for analytics commands. Set by the `mint login` command. |
| `dateFrom` | Default start date for analytics queries (`YYYY-MM-DD`). |
| `dateTo` | Default end date for analytics queries (`YYYY-MM-DD`). |
```bash Example configs theme={null}
mint config set subdomain my-docs
mint config set dateFrom 2025-01-01
```
Once set, analytics commands use these values automatically:
```bash theme={null}
# Uses the configured subdomain and dateFrom without flags
mint analytics stats
```
To view or clear a value, run:
```bash theme={null}
mint config get subdomain
mint config clear subdomain
```
# Commands
Source: https://www.mintlify.com/docs/cli/commands
Complete reference for every Mintlify CLI command and flag, including mint dev, mint build, mint validate, mint analytics, and more.
## Global flags
These flags are available on all commands.
| Flag | Description |
| ------------------- | -------------------------------------------------- |
| `--telemetry`, `-t` | Enable or disable anonymous usage telemetry. |
| `--help`, `-h` | Display help for the command. |
| `--version`, `-v` | Display the CLI version. Alias for `mint version`. |
## `mint dev`
Start a local preview of your documentation.
```bash theme={null}
mint dev [flags]
```
| Flag | Description |
| ------------------- | -------------------------------------------------------- |
| `--port` | Port to run the local preview on. Defaults to `3000`. |
| `--no-open` | Do not open the browser automatically. |
| `--groups` | Comma-separated list of user groups to mock for preview. |
| `--disable-openapi` | Skip OpenAPI file processing to improve performance. |
| `--local-schema` | Allow locally hosted OpenAPI files served over HTTP. |
***
## `mint login`
Authenticate with your Mintlify account.
```bash theme={null}
mint login
```
Opens a browser window to complete authentication. If the browser does not open, the CLI displays a URL to open manually and a prompt to paste the authorization code. Credentials save in `~/.config/mintlify/config.json`.
If you have more than one deployment, the CLI prompts you to select a default after you log in. You can change the default project later with `mint config set subdomain `.
***
## `mint logout`
Remove stored credentials.
```bash theme={null}
mint logout
```
***
## `mint status`
Display your current session details including CLI version, account email, organization, and configured subdomain.
```bash theme={null}
mint status
```
***
## `mint analytics`
View analytics data for your documentation. Requires authentication with `mint login`.
```bash theme={null}
mint analytics [flags]
```
All subcommands accept these shared flags:
| Flag | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `--subdomain` | Documentation subdomain. Defaults to the value set with `mint config set subdomain`, or the first project on your account. |
| `--from` | Start date in `YYYY-MM-DD` format. Defaults to 7 days ago, or the value set with `mint config set dateFrom`. |
| `--to` | End date in `YYYY-MM-DD` format. Defaults to today, or the value set with `mint config set dateTo`. |
| `--format` | Output format: `plain` (default), `table`, `json`, or `graph`. |
### `mint analytics stats`
Display a summary of views, visitors, searches, feedback, and assistant usage.
```bash theme={null}
mint analytics stats [flags]
```
| Flag | Description |
| -------- | ------------------------------- |
| `--page` | Filter to a specific page path. |
### `mint analytics search`
Display search queries with hit counts and click-through rates.
```bash theme={null}
mint analytics search [flags]
```
| Flag | Description |
| --------- | --------------------------------- |
| `--query` | Filter by search query substring. |
| `--page` | Filter by top clicked page. |
### `mint analytics feedback`
Display feedback submitted by users.
```bash theme={null}
mint analytics feedback [flags]
```
| Flag | Description |
| -------- | ---------------------------------------------------------------------------- |
| `--type` | Feedback type: `page` (aggregate by page) or `code` (code snippet feedback). |
| `--page` | Filter to a specific page path. |
### `mint analytics conversation`
View assistant conversation data.
```bash theme={null}
mint analytics conversation [flags]
```
#### `mint analytics conversation list`
List assistant conversations. Each entry includes a conversation ID.
```bash theme={null}
mint analytics conversation list [flags]
```
| Flag | Description |
| -------- | --------------------------------------------------------------- |
| `--page` | Filter conversations that reference a specific page in sources. |
#### `mint analytics conversation view `
View a single conversation by ID. Use `mint analytics conversation list` to get IDs.
```bash theme={null}
mint analytics conversation view
```
#### `mint analytics conversation buckets list`
List grouped conversation categories. Each entry includes a bucket ID.
```bash theme={null}
mint analytics conversation buckets list
```
#### `mint analytics conversation buckets view `
View conversations in a category bucket. Use `mint analytics conversation buckets list` to get IDs.
```bash theme={null}
mint analytics conversation buckets view
```
***
## `mint config`
Manage persistent default values for CLI commands. The configuration saves in `~/.config/mintlify/config.json`.
```bash theme={null}
mint config [value]
```
| Subcommand | Description |
| ------------------- | ------------------------------ |
| `set ` | Set a configuration value. |
| `get ` | Display a configuration value. |
| `clear ` | Remove a configuration value. |
### Configuration keys
| Key | Description | Used by |
| ----------- | -------------------------------------------------------- | ---------------- |
| `subdomain` | Default documentation subdomain. | `mint analytics` |
| `dateFrom` | Default start date for analytics queries (`YYYY-MM-DD`). | `mint analytics` |
| `dateTo` | Default end date for analytics queries (`YYYY-MM-DD`). | `mint analytics` |
***
## `mint broken-links`
Check for broken internal links in your documentation.
```bash theme={null}
mint broken-links [flags]
```
The command excludes files matching [.mintignore](/docs/organize/mintignore) patterns. Links that point to ignored files report as broken.
| Flag | Description |
| ------------------- | -------------------------------------------------------------------------------- |
| `--check-anchors` | Also validate anchor links (for example, `/page#section`) against heading slugs. |
| `--check-external` | Also check external URLs for broken links. |
| `--check-redirects` | Also check that redirect destinations in `docs.json` resolve to valid paths. |
| `--check-snippets` | Also check links inside `` components. |
***
## `mint a11y`
Check for accessibility issues in your documentation.
```bash theme={null}
mint a11y [flags]
```
Checks color contrast ratios and missing alt text on images and videos.
| Flag | Description |
| ----------------- | ----------------------------- |
| `--skip-contrast` | Skip color contrast checks. |
| `--skip-alt-text` | Skip missing alt text checks. |
***
## `mint validate`
Validate your documentation build in strict mode. Exits with an error if there are any warnings or errors. Includes automatic validation of OpenAPI specifications referenced in your `docs.json`.
```bash theme={null}
mint validate [flags]
```
| Flag | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| `--groups` | Comma-separated list of user groups to mock for validation. |
| `--disable-openapi` | Skip OpenAPI file processing and validation. |
| `--local-schema` | Allow validation of locally hosted OpenAPI files served over HTTP. Only supports HTTPS in production. |
The standalone `mint openapi-check` command is deprecated. Use `mint validate` instead.
***
## `mint export`
Export your documentation as a self-contained zip archive for offline viewing and distribution.
```bash theme={null}
mint export [flags]
```
| Flag | Description |
| ------------------- | -------------------------------------------------------------------- |
| `--output` | Output filename. Defaults to `export.zip`. |
| `--groups` | Comma-separated list of user groups to include restricted pages for. |
| `--disable-openapi` | Skip OpenAPI processing. |
See [Offline export](/docs/deploy/export) for details.
***
## `mint score`
Run agent readiness checks against a public documentation site. Requires authentication with `mint login`.
```bash theme={null}
mint score [url] [flags]
```
| Argument | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url` | Optional. URL of the docs site to check. If omitted, the command scores your configured subdomain (from `mint config` or the subdomain associated with your logged-in account). |
| Flag | Description |
| ---------- | ----------------------------------------------------------------------------- |
| `--format` | Output format: `table` (default, colored), `plain` (pipeable TSV), or `json`. |
The command displays an overall readiness score and a breakdown of individual checks with pass/fail indicators.
### Examples
```bash theme={null}
# Score your default subdomain
mint score
# Score a specific site
mint score docs.example.com
```
### Checks
The score evaluates the following areas:
| Check | What it verifies |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `llmsTxtExists` | Agents can reach an [llms.txt](/docs/ai/llmstxt) file at the site root. |
| `llmsTxtValid` | The `llms.txt` file follows the expected format with headings, blockquote summary, and Markdown links. |
| `llmsTxtSize` | The `llms.txt` file is within the size threshold so agents can consume it without truncation. |
| `llmsTxtLinksResolve` | Links inside `llms.txt` resolve to live pages. |
| `llmsTxtLinksMarkdown` | Links inside `llms.txt` use Markdown syntax. |
| `llmsTxtDirective` | The `llms.txt` file contains usage directives. |
| `llmsTxtFullExists` | An [llms-full.txt](/docs/ai/llmstxt/#llms-full-txt) file is available for agents that need the complete content. Runs independently of `llmsTxtExists`. |
| `llmsTxtFullSize` | The `llms-full.txt` file is within a reasonable size for agents to process. |
| `llmsTxtFullValid` | The `llms-full.txt` file contains valid content with headings. |
| `llmsTxtFullLinksResolve` | Links inside `llms-full.txt` resolve to live pages. |
| `skillMd` | Agents can reach a [skill.md](https://www.mintlify.com/docs/ai/skillmd) file for agent tool use. |
| `contentNegotiationMarkdown` | The site returns Markdown when agents request it through content negotiation. |
| `contentNegotiationPlaintext` | The site returns plain text when agents request it through content negotiation. |
| `mcpServerDiscoverable` | Agents can discover an [MCP server](/docs/ai/model-context-protocol) for tool-based agents. |
| `mcpToolCount` | The MCP server exposes at least one tool. |
| `openApiSpec` | There is an available OpenAPI or Swagger specification at a standard path. |
| `robotsTxtAllowsAI` | The `robots.txt` file does not block AI crawlers. |
| `sitemapExists` | There is a sitemap available for page discovery. |
| `structuredData` | The homepage contains [JSON-LD](https://json-ld.org/) structured data (`