The AI assistant is on by default. To turn it off, set hide to true.
By default, users can access the AI assistant with the floating Ask AI button in the bottom-right corner. Users can also open it through the Search modal in the top navigation bar.
Use the aiAssistant configuration to:
- hide the AI assistant
- add suggested pages to the search modal
- set the built-in prompt text
- choose the categories that project analytics sorts questions into
- add an Ask AI button
The aiAssistant option also supports page-level configuration using front matter.
The AI assistant indexes and searches across all content in your project:
- API descriptions - OpenAPI, GraphQL, AsyncAPI, and SOAP description files
- Documentation pages - Markdown files
- API versions - All versions of APIs are indexed and filtered based on the active version
- Multiple products - All products in multi-product projects are indexed and filtered based on the active product
When you have multiple versions of an API, the AI assistant shows results from the active version by default. Results also include default versions from other APIs and non-versioned content.
In projects with multiple products configured, opening the AI assistant from a product page automatically restricts searches and answers to that product based on the current URL. Users can remove the product filter in the search dialog to search across all products.
The index includes content that RBAC protects. The AI assistant serves users only the content that they can access. To build the index, Redocly sends the content to a Google embedding model. To keep content out of the index, see the AI governance FAQ.
| Option | Type | Description |
|---|---|---|
| hide | boolean | Hides the AI assistant when set to true. Default: false. |
| prompt | string | Built-in instructions for the AI assistant. Applied to all AI assistant answers in the project and not visible to users. Use to set greeting, tone, or other answer conditions. |
| suggestions | [string] | List of suggestions displayed in the AI assistant interface. |
| categories | [Question category] | Categories that project analytics sorts AI assistant questions into, up to 20. A question that matches none of them gets the other category. A list replaces the built-in categories. An empty list turns off the categories. Default: all built-in categories. Project analytics requires the Scale or Enterprise plan. On other plans, questions get no category. |
| trigger | Trigger button | Configures the Ask AI floating button. |
| Option | Type | Description |
|---|---|---|
| hide | boolean | Hides the trigger button when set to true. Default: false. |
| inputType | string | Type of UI component used to render trigger button. Possible values: button, icon. Default: button. |
| inputIcon | string | Icon of the trigger button component. Possible values: redocly, sparkles, chat. Default: sparkles. |
| Option | Type | Description |
|---|---|---|
| name | string | REQUIRED. Name of the category, up to 50 characters. Spaces at the start and end are removed, and names are compared without letter case. The AI assistant ignores an entry when the name is empty, is longer than 50 characters, has quotes or backslashes, or repeats an earlier name. It also ignores the reserved name other. To use a built-in category, give its name. |
| description | string | What questions in this category ask about, up to 500 characters. An entry with an empty or longer description is ignored. On a built-in category, it replaces the built-in definition. Without it, a custom category is matched by its name only. A description gives more accurate categories. |
| Name | Questions about |
|---|---|
setup | Getting access and first steps: API keys, tokens, client credentials, a sandbox, base URLs, or authentication. |
capabilities | Whether the product or API can do something, or which endpoint does it. |
usage | The steps to do a task with a known feature. |
reference | One fact, such as what a field, value, limit, or response is. |
code | Code samples, request examples, generated specs, or help with code. |
troubleshooting | An error, a failure, or an unexpected result. |
ai-tools | Using the documentation with AI tools, such as an MCP server, an AI agent, or a Markdown export. |
account | The user's own account, plan, prices, payments, or contact with sales or support. |
The AI assistant is available on all plans with a monthly limit of 3500 questions per organization. The limit resets at the beginning of each calendar month. Above the limit, users receive regular search results instead of AI answers. These limits can change.
Data usage and privacy: Curious how the AI assistant uses your data? The Redocly AI assistant runs in inference-only mode and does not train or fine-tune AI models on your content. For details, see the AI governance and security FAQ.
AI assistant and Typesense search indexes are only built on the production branch. Changes to search configuration or content exclusions, like the excludeFromSearch front matter option, appear in search results after the next production build.
Display the AI assistant button with a custom prompt:
aiAssistant:
hide: false
prompt: Speak only in rhymes
Set AI assistant suggestions:
aiAssistant:
hide: false
suggestions:
- How to create a new API?
- What is Redocly?
- How to manage an organization?
aiAssistant:
trigger:
hide: false
inputType: button
inputIcon: redocly
Sort questions into two built-in categories and one custom category:
aiAssistant:
categories:
- name: troubleshooting
- name: usage
- name: payments
description: The user asks about payments, refunds, or invoices.
- AI governance and security FAQ - How the AI assistant works, what data it uses, and which controls protect it
search- Learn how to customize search in your project, curate search results, and exclude pages from search- Configuration options - Explore other project configuration options for comprehensive documentation and platform customization