> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mintlify/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Assistant

> Add AI-powered chat to your docs that answers questions, cites sources, and generates code examples.

<Info>
  The assistant is automatically enabled on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=assistant).
</Info>

## About the assistant

The assistant answers questions about your documentation through natural language queries. Users access the assistant on your documentation site, so they can find answers quickly and succeed with your product even if they don't know where to look.

The assistant uses agentic RAG (retrieval-augmented generation) with tool calling. When users ask questions, the assistant:

* **Searches and retrieves** relevant content from your documentation to provide accurate answers.
* **Cites sources** and provides navigable links to take users directly to referenced pages.
* **Generates copyable code examples** to help users implement solutions from your documentation.

You can view assistant usage through your dashboard to understand user behavior and documentation effectiveness. Export and analyze query data to help identify:

* Frequently asked questions that might need better coverage.
* Content gaps where users struggle to find answers.
* Popular topics that could benefit from additional content.

### How indexing works

The assistant automatically indexes your published documentation to answer questions accurately. When you publish changes, the assistant immediately indexes new, updated, or deleted content. The assistant does not index draft branches or preview deployments.

By default, the assistant does not index hidden pages. To include hidden pages in the assistant's index, set `seo.indexing: "all"` in your `docs.json`. See [Hidden pages](/organize/hidden-pages#search-seo-and-ai-indexing) for more information.

### How the assistant handles unknown questions

The assistant only answers questions based on information in your documentation. If it cannot find relevant information after searching, it responds that it doesn't have enough information to answer.

You can [set a deflection email](/ai/assistant#set-deflection-email) so that the assistant provides your support email to users whose questions it cannot answer. This gives users a path forward, even if the documentation doesn't address their specific question.

## Configure the assistant

The assistant is active on Pro and Enterprise plans by default.

Manage the assistant from the [Assistant Configurations](https://dashboard.mintlify.com/products/assistant/settings) page of your dashboard. Enable or disable the assistant, configure response handling, add default questions, and manage your message allowance.

### Enable or disable the assistant

Toggle the assistant status to enable or disable the assistant for your documentation site.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/status-light.png" alt="The assistant status toggle in the dashboard." className="block dark:hidden" />

  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/status-dark.png" alt="The assistant status toggle in the dashboard." className="hidden dark:block" />
</Frame>

### Set deflection email

In the Response Handling section, enable the assistant to redirect unanswered questions to your support team.

Specify an email address for the assistant to give to users if it cannot answer their question. You can also enable a "Contact support" button to appear in the assistant chat panel.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/deflection-light.png" alt="The assistant deflection panel in the dashboard. Assistant deflection is toggled on and support@mintlify.com is set as the deflection email." className="block dark:hidden" />

  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/deflection-dark.png" alt="The assistant deflection panel in the dashboard. Assistant deflection is toggled on and support@mintlify.com is set as the deflection email." className="hidden dark:block" />
</Frame>

### Search domains

In the Response Handling section, configure domains that the assistant can use for web search to find additional context when answering questions.

* Domains must be publicly available.
* Domains that require JavaScript to load are not supported.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/search-domains-light.png" alt="The assistant search domains panel enabled in the dashboard. The assistant is configured to search the mintlify.com/pricing domain." className="block dark:hidden" />

  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/search-domains-dark.png" alt="The assistant search domains panel enabled in the dashboard. The assistant is configured to search the mintlify.com/pricing domain." className="hidden dark:block" />
</Frame>

For more precise control over what the assistant can search, use filtering syntax.

* **Domain-level filtering**
  * `example.com`: Search only the `example.com` domain
  * `docs.example.com`: Search only the `docs.example.com` subdomain
  * `*.example.com`: Search all subdomains of `example.com`
* **Path-level filtering**
  * `docs.example.com/api`: Search all pages under the `/api` subpath
* **Multiple patterns**
  * Add multiple entries to target different sections of sites

### Add sample questions

Help your users begin conversations with the assistant by adding starter questions. Add commonly asked questions or questions about topics that you want your users to know about. You can add up to 5 starter questions. Click **Ask AI** for recommended questions based on your documentation.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/search-suggestions-light.png" alt="The search suggestions panel in the dashboard with starter questions enabled and populated with three questions." className="block dark:hidden" />

  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/search-suggestions-dark.png" alt="The search suggestions panel in the dashboard with starter questions enabled and populated with three questions." className="hidden dark:block" />
</Frame>

## Customize assistant behavior

Add an `Assistant.md` (or `ASSISTANT.md`) file to your project to give the assistant custom instructions that shape how it responds. The assistant uses these instructions as system-level context for every response.

Create the file at `.mintlify/Assistant.md` (or `.mintlify/ASSISTANT.md`) in your project root.

Instructions in an `Assistant.md` file add to the assistant's system prompt. They do not replace or override the assistant's default instructions.

To remove the custom instructions, remove the `Assistant.md` file.

Use `Assistant.md` to:

* Adjust the assistant's persona and tone
* Provide product-specific context
* Define support escalation paths
* Specify terminology preferences
* Restrict or scope the assistant's focus areas
* Provide version-specific guidance

```markdown Example Assistant.md theme={null}
You are a helpful assistant for Acme Corp's developer platform.

## Tone
- Be concise and direct. Getting to the point helps people more than being exhaustive.
- Use technical language appropriate for software developers. Most people asking you questions are familiar with Acme's products.

## Product context
- Acme SDK v3 is the current stable release. v2 is deprecated. If people ask about v2, remind them it's deprecated but answer their questions.
- Direct billing questions to support@acme.com.

## Terminology
- Use "workspace" instead of "project" or "organization".
- Use "access token" instead of "API key".
```

## Manage billing

The assistant uses tiered message allowances. A message is any user interaction with the assistant that receives a correct response. If you have unused messages, up to half of your message allowance can carry over to the next billing cycle. For example, if you have a 1,000 message allowance and you use 300 messages, 500 messages carry over to the next billing cycle giving you a total of 1,500 messages for the next billing cycle.

By default, the assistant allows overages. You can disable overages to avoid incurring additional costs for usage beyond your tier. If you reach your message allowance with overages disabled, the assistant is unavailable until your message allowance resets. If you allow overages, each message beyond your allowance incurs an overage charge, but occasional overages may be cheaper than upgrading to a higher tier depending on your usage.

### Change your assistant tier

Assistant tiers determine your monthly message allowance and pricing.

View and change your current tier on the [Billing tab](https://dashboard.mintlify.com/products/assistant/settings/billing) of the assistant page in your dashboard.

In the **Spending Controls** section, select your preferred tier from the dropdown menu.

**Upgrade your tier:**

* Your new message allowance is available immediately.
* You pay a prorated difference for the current billing cycle.

**Downgrade your tier:**

* Your message allowance updates immediately.
* Pricing changes take effect at the start of your next billing cycle.
* Unused messages from your current tier **do not** carry over.

### Allow overages

If you want to disallow overages, disable them in the **Billing Controls** section of the [Billing tab](https://dashboard.mintlify.com/products/assistant/settings/billing) of the assistant page in your dashboard.

### Set usage alerts

In the Billing Controls section, set usage alerts to receive an email when you reach a certain percentage of your message allowance.

## Connect apps

In the connect apps section, add the assistant to your [Discord](/ai/discord) server and [Slack](/ai/slack-bot) workspace to allow users to get answers from your documentation on those platforms.

## Assistant insights

Use assistant insights to understand how users interact with your documentation and identify improvement opportunities.

The [assistant page](https://dashboard.mintlify.com/products/assistant) shows usage trends for the month to date. View more detailed insights on the [analytics](/optimize/analytics#assistant) page.

## Make content AI ingestible

Structure your documentation to help the assistant provide accurate, relevant answers. Clear organization and comprehensive context benefit both human readers and AI understanding.

<Card title="Structure and organization">
  * Use semantic markup.
  * Write descriptive headings for sections.
  * Create a logical information hierarchy.
  * Use consistent formatting across your docs.
  * Include comprehensive metadata in page frontmatter.
  * Break up long blocks of text into shorter paragraphs.
</Card>

<Card title="Context">
  * Define specific terms and acronyms when first introduced.
  * Provide sufficient conceptual content about features and procedures.
  * Include examples and use cases.
  * Cross-reference related topics.
  * Add [hidden pages](/organize/hidden-pages) with additional context that users don't need, but the assistant can reference.
</Card>

## Use the assistant

Users have multiple ways to start a conversation with the assistant. Each method opens a chat panel on the right side of your docs. Users can ask any question and the assistant searches your documentation for an answer. If the assistant cannot retrieve relevant information, the assistant responds that it cannot answer the question.

Add the assistant as a bot to your [Slack workspace](/ai/slack-bot) or [Discord server](/ai/discord) so that your community can ask questions without leaving their preferred platform.

### UI placement

The assistant appears in two locations: as a button next to the search bar and as a bar at the bottom of the page.

<Columns cols={2}>
  <Frame caption="Assistant button next to the search bar.">
    <img
      src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/assistant-button-light.png"
      className="block dark:hidden"
      style={{
width: '268px',
height: 'auto',
}}
      alt="Search bar and assistant button in light mode."
    />

    <img
      src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/assistant-button-dark.png"
      className="hidden dark:block"
      style={{
width: '268px',
height: 'auto',
}}
      alt="Search bar and assistant button in dark mode."
    />
  </Frame>

  <Frame caption="Assistant button at the bottom of the page.">
    <img
      src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/assistant-bar-light.png"
      className="block dark:hidden"
      style={{
width: '268px',
height: 'auto',
}}
      alt="Assistant bar in light mode."
    />

    <img
      src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/assistant-bar-dark.png"
      className="hidden dark:block"
      style={{
width: '268px',
height: 'auto',
}}
      alt="Assistant bar in dark mode."
    />
  </Frame>
</Columns>

### Keyboard shortcut

Open the assistant chat panel with the keyboard shortcut <kbd>Command</kbd> + <kbd>I</kbd> on macOS and <kbd>Ctrl</kbd> + <kbd>I</kbd> on Windows.

### Highlight text

Highlight text on a page and click the **Add to assistant** pop up button to open the assistant chat panel and add the highlighted text as context. You can add multiple text snippets or code blocks to the assistant's context.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/highlight-light.png" alt="The Add to assistant button above highlighted text in light mode." className="block dark:hidden" />

  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/highlight-dark.png" alt="The Add to assistant button above highlighted text in dark mode." className="hidden dark:block" />
</Frame>

### Code blocks

Click the **Ask AI** button in a code block to open the assistant chat panel and add the code block as context. You can add multiple code blocks or text snippets to the assistant's context.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/code-block-light.png" alt="The Ask AI button in a code block in light mode." className="block dark:hidden" />

  <img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify-docs/images/assistant/code-block-dark.png" alt="The Ask AI button in a code block in dark mode." className="hidden dark:block" />
</Frame>

### URLs

Open the assistant with a URL query parameter to create deep links that guide users to specific information or share assistant conversations with pre-filled questions.

* **Open the assistant**: Append `?assistant=open` to open the assistant chat panel when the page loads.
  * Example: [https://mintlify.com/docs?assistant=open](https://mintlify.com/docs?assistant=open)
* **Open with a pre-filled query**: Append `?assistant=YOUR_QUERY` to open the assistant and automatically submit a question.
  * Example: [https://mintlify.com/docs?assistant=explain webhooks](https://mintlify.com/docs?assistant=explain%20webhooks)

## Troubleshooting

<Accordion title="Assistant chat bar not visible">
  If the assistant UI is not visible in specific browsers, you may need to submit a false positive report to [EasyList](https://easylist.to). Browsers that use the EasyList Cookies List like Brave and Comet sometimes block the assistant or other UI elements. The EasyList Cookies List includes a domain-specific rule that hides fixed elements on certain domains to block cookie banners. This rule inadvertently affects legitimate UI components.

  Submit a false positive report to [EasyList](https://github.com/easylist/easylist) to request removal of the rule. This resolves the issue for all users once the filter list updates.
</Accordion>