mintlify.com/docs/

Starting URLs:
https://mintlify.com/docs/
## Page: https://mintlify.com/docs/

## Getting Started

Welcome! Follow the instructions below to learn how to deploy, update and supercharge your documentation with Mintlify.

### Creating the Repository

Mintlify docs are rendered from MDX files and configurations defined in our starter kit. We use GitHub to integrate your docs with your code, and make source control effortless. Onboard through the dashboard or clone our starter kit to get started.

### Updating the Content

Mintlify enables you to easily customize the style, structure, and content of your docs.

### Publishing

Congrats! You’ve set up your Mintlify Docs and it’s looking amazing! Need support or want to give some feedback? You can join our community or drop us an email at \[email protected\].

Was this page helpful?

---

## Page: https://mintlify.com/docs/quickstart

## Getting Started

Welcome! Follow the instructions below to learn how to deploy, update and supercharge your documentation with Mintlify.

### Creating the Repository

Mintlify docs are rendered from MDX files and configurations defined in our starter kit. We use GitHub to integrate your docs with your code, and make source control effortless. Onboard through the dashboard or clone our starter kit to get started.

### Updating the Content

Mintlify enables you to easily customize the style, structure, and content of your docs.

### Publishing

Congrats! You’ve set up your Mintlify Docs and it’s looking amazing! Need support or want to give some feedback? You can join our community or drop us an email at \[email protected\].

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/global

    {
      "name": "Mintlify",
      "logo": {
        "light": "/logo/light.svg",
        "dark": "/logo/dark.svg"
      },
      "favicon": "/favicon.svg",
      "colors": {
        "primary": "#16A34A",
        "light": "#4ADE80",
        "dark": "#166534"
      },
      "topbarLinks": [
        {
          "name": "Contact Us",
          "url": "mailto:[email protected]"
        }
      ],
      "topbarCtaButton": {
        "name": "Get Started",
        "url": "https://mintlify.com/start"
      },
      "anchors": [
        {
          "name": "API Components",
          "icon": "rectangle-terminal",
          "color": "#f59f0b",
          "url": "api-components"
        },
        {
          "name": "Community",
          "icon": "comments",
          "color": "#2564eb",
          "url": "https://mintlify.com/community"
        }
      ],
      "navigation": [
        {
          "group": "Getting Started",
          "pages": ["introduction", "quickstart"]
        },
        {
          "group": "API Components",
          "pages": ["api-playground/overview", "api-playground/configuration"]
        },
        {
          "group": "Settings",
          "pages": ["settings/global", "settings/page"]
        },
        {
          "group": "Analytics",
          "pages": ["analytics/posthog"]
        }
      ],
      "footerSocials": {
        "github": "https://github.com/mintlify",
        "slack": "https://mintlify.com/community",
        "x": "https://x.com/mintlify"
      },
      "integrations": {
        "intercom": "APP_ID",
        "frontchat": "CHAT_ID"
      }
    }

---

## Page: https://mintlify.com/docs/themes

We offer pre-built themes so you can differentiate the look and feel of your documentation based on your brand.

## Configuration

You can configure the theme in the `docs.json` file.

For example, to use the `maple` theme, you can add the following to your `docs.json` file:

## Available Themes

There are a variety of themes to choose from.

  

#### Mint

Classic documentation theme with time-tested layouts and familiar navigation.

See preview

#### Maple

Modern, clean aesthetics perfect for AI and SaaS products.

See preview

#### Palm

Sophisticated fintech theme with deep customization for enterprise documentation.

See preview

#### Willow

Stripped-back essentials for distraction-free documentation.

See preview

#### Linden

Retro terminal vibes with monospace fonts for that 80s hacker aesthetic.

See preview

Was this page helpful?

---

## Page: https://mintlify.com/docs/migration

You can use our public packages to convert your existing documentation to Mintlify.

We currently support migration for:

Don’t see your docs provider or have a home grown system? We can still help! Please get in touch at \[email protected\].

## Commands

*   `mintlify-scrape section [url]` - Scrapes multiple pages in a site.
*   `mintlify-scrape page [url]` - Scrapes a single page in a site.

The commands will automatically detect the framework.

## 🚀 Installation

First, install the package:

One-time use:

Global installation:

Global usage:

Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint.

Was this page helpful?

On this page

*   Commands
*   🚀 Installation

---

## Page: https://mintlify.com/docs/page

## The Basics

Each page is an MDX file that should begin with the following metadata syntax with `---` at the start and end:

Other metadata goes in between the same `---` lines. For example, this page uses this metadata:

## Descriptions

You can show a description that shows directly under the title with the `description` metadata.

You can show a different title in the navigation with the `sidebarTitle` metadata. This is useful if your title is long and you want something shorter in the navigation links.

Want an icon for your sidebar item like the ones in components? You can set an `icon` attribute in the metadata! All icons from Font Awesome and Lucide are available for us. You can also set an icon type for Font Awesome icons (optional). If not set, the icon type will be regular.

## API Pages

API pages let you build interactive API playgrounds. To create an API page, you must set an `api` or `openapi` property in the page metadata.

Learn more about API playgrounds in our demo.

## Page Mode

The Page Mode setting allows you to customize the appearance of your page. You can choose from different modes to adjust the layout according to your needs. If no mode is specified, the page will use the default settings.

### Default

If no specific mode is given, the page will default to standard settings. This means the page will display with the default table of contents (if headings are present) and other standard elements, providing a typical layout without any special adjustments.

### Wide Mode

In Wide Mode, you can hide the table of contents (ToC) on the right side of the page. This is particularly useful if your page doesn’t have any headings or if you prefer to utilize the extra horizontal space for other content.

### Custom Mode

Custom Mode provides a minimalist layout by removing all elements except for the top bar. This mode offers a blank canvas, which is ideal for creating a “landing page” or any page where you want a clean, distraction-free environment.

### Center Mode

Center Mode removes the sidebar and the table of contents, and centers the page content. This mode is great for changelogs or any page where you want to focus on the content.

## External Links

If you want the sidebar to open an external URL, you can set the `url` metadata in any page.

## Search Engine Optimization

You can set meta tags like the image set when shared on social media by passing them into your page’s metadata. Meta tags with colons need to be wrapped in quotes.

See our SEO page for all supported meta tags.

---

## Page: https://mintlify.com/docs/text

## Titles

Best used for section headers.

### Subtitles

Best used for subsection headers.

## Text Formatting

We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.

| Style | How to write it | Result |
| --- | --- | --- |
| Bold | `**bold**` | **bold** |
| Italic | `_italic_` | _italic_ |
| Strikethrough | `~strikethrough~` | ~strikethrough~ |

You can combine these. For example, write `**_bold and italic_**` to get _**bold and italic**_ text.

You need to use HTML to write superscript and subscript text. That is, add `<sup>` or `<sub>` around your text.

| Text Size | How to write it | Result |
| --- | --- | --- |
| Superscript | `<sup>superscript</sup>` | superscript |
| Subscript | `<sub>subscript</sub>` | subscript |

## Linking to Pages

You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to link to google.

Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/content/text)` links to the page “Text” in our components section.

Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.

You can validate broken links in your docs with our CLI.

## Blockquotes

### Singleline

To create a blockquote, add a `>` in front of a paragraph.

> Dorothy followed her through many of the beautiful rooms in her castle.

### Multiline

> Dorothy followed her through many of the beautiful rooms in her castle.
> 
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

### LaTeX

Mintlify supports in-line LaTeX by surrounding your LaTeX code with dollar signs ($). For example, `$(a^2 + b^2 = c^2)$` will render as (a2+b2\=c2)(a^2 + b^2 = c^2).

Equations on their own line can be created with double dollar signs ($$):

∃ x∉\[0,1\]\\exists \\, x \\notin \[0,1\]

### Line Breaks

Markdown syntax also recognizes a double enter in your MDX as a linebreak.

---

## Page: https://mintlify.com/docs/image-embeds

## Image

### Using Markdown

The markdown syntax lets you add images using the following code

Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like Cloudinary or S3. You can then use that URL and embed.

### Using Embeds

To get more customizability with images, you can also use embeds to add images.

### Disable Image Zoom

To disable the default zoom on click for images, add the noZoom property to image embeds.

### Linking Images

To link an image, for example to create a button on your docs, encompass the image in a link with the `noZoom` property. Images in `a` tags will automatically have a pointer cursor.

### Dark Mode

To use separate images for light and dark mode, use Tailwind CSS to hide and show images.

For more information, we recommend the following sections:

## Frame Component Reference

Read the reference for the Frame component

For YouTube videos use:

For other videos, use:

To autoplay the video, use:

## iFrames

Loads another HTML page within the document.

Was this page helpful?

---

## Page: https://mintlify.com/docs/list-table

### Ordered List

To create an ordered list, add line items with numbers followed by periods

1.  First item
2.  Second item
3.  Third item
4.  Fourth item

### Unordered List

To create an unordered list, add dashes (`-`), asterisks (`*`), or plus signs (`+`) in front of line items

*   First item
*   Second item
*   Third item
*   Fourth item

### Nested List

Add indents on list items to nest them

*   First item
*   Second item
    *   Additional item
    *   Additional item
*   Third item

## Tables

| Property | Description |
| --- | --- |
| Name | Full name of user |
| Age | Reported age |
| Joined | Whether the user joined the community |

### Creating a table

To add a table, use three or more hyphens (`---`) to create each column’s header, and use pipes (`|`) to separate each column. For compatibility, you should also add a pipe on either end of the row.

Was this page helpful?

---

## Page: https://mintlify.com/docs/code

## Basic

### Inline Code

To denote a `word` or `phrase` as code, enclose it in backticks (\`).

    To denote a `word` or `phrase` as code, enclose it in backticks (`).
    

### Code Block

Use fenced code blocks by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.

HelloWorld.java

    class HelloWorld {
        public static void main(String[] args) {
            System.out.println("Hello, World!");
        }
    }
    

    ```java HelloWorld.java
    class HelloWorld {
        public static void main(String[] args) {
            System.out.println("Hello, World!");
        }
    }
    ```
    

Visit the Code Block page for more detailed docs.

---

## Page: https://mintlify.com/docs/reusable-snippets

One of the core principles of software development is DRY (Don’t Repeat Yourself), which applies to documentation as well. If you find yourself repeating the same content in multiple places, you should create a custom snippet to keep your content in sync.

## Creating a custom snippet

**Pre-condition**: You must create your snippet file in the `snippets` directory in order for the import to work.

Any page in the `snippets` directory will be treated as a snippet and will not be rendered into a standalone page. If you want to create a standalone page from the snippet, import the snippet into another file and call it as a component.

### Default export

1.  Add content to your snippet file that you want to re-use. Optionally, you can add variables that can be filled in via props when you import the snippet. In this example, our variable is word.

snippets/my-snippet.mdx

2.  Import the snippet into your destination file.

destination-file.mdx

### Exporting with variables

1.  Optionally, you can add variables that can be filled in via props when you import the snippet. In this example, our variable is word.

snippets/my-snippet.mdx

2.  Import the snippet into your destination file with the variable. The property will fill in based on your specification.

destination-file.mdx

### Reusable variables

1.  Export a variable from your snippet file:

snippets/path/to/custom-variables.mdx

2.  Import the snippet from your destination file and use the variable:

destination-file.mdx

### Reusable components

1.  Inside your snippet file, create a component that takes in props by exporting your component in the form of an arrow function.

snippets/custom-component.mdx

2.  Import the snippet into your destination file and pass in the props

destination-file.mdx

### Client-Side Content

By default, Mintlify employs server-side rendering, generating content at build time. For client-side content loading, ensure to verify the `document` object’s availability before initiating the rendering process.

snippets/client-component.mdx

Was this page helpful?

---

## Page: https://mintlify.com/docs/api-playground/overview

API References

Enable users to interact with your API

POST

The API playground is an interactive environment to make requests and preview an API endpoint.

Authorization

string

header

required

Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.

projectId

string

required

The ID of the project to trigger an update on. Can be retrieved from your dashboard.

#### Response

202 - application/json

A successful response

statusId

string

The status id of the triggered updated.

Was this page helpful?

---

## Page: https://mintlify.com/docs/api-playground/troubleshooting

API pages are complicated. As a result, there are a lot of things that can go wrong. Here’s a list of common issues we’ve seen customers run into:

In this scenario, it’s likely that either Mintlify cannot find your OpenAPI document, or your OpenAPI document is invalid.

Running `mintlify dev` locally should reveal some of these issues.

To verify your OpenAPI document will pass validation:

1.  Visit this validator
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 (under Edit > Convert to OpenAPI 3):

This is usually caused by a misspelled `openapi` field in the page metadata. Make sure the HTTP method and path match the HTTP method and path in the OpenAPI document exactly.

Here’s an example of how things might go wrong:

get-user.mdx

    ---
    openapi: "GET /users/{id}/"
    ---
    

openapi.yaml

    paths:
      "/users/{id}":
        get: ...
    

Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI document does not.

Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document in the `openapi` field, ensure the filename is correct. For example, if you have two OpenAPI documents `openapi/v1.json` and `openapi/v2.json`, your metadata might look like this:

api-reference/v1/users/get-user.mdx

    ---
    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 `/api/request` path on the docs site. If your reverse proxy is configured to only allow `GET` requests, then all of these requests will fail. To fix this, configure your reverse proxy to allow `POST` requests to the `/api/request` path.

Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure Mintlify to send requests directly to your backend with the `api.playground.proxy` setting in the `docs.json`, as described here. This will likely require you to configure CORS on your server, as these requests will now come directly from your users’ browsers.

---

## Page: https://mintlify.com/docs/settings/custom-domain

To set up your documentation on a custom domain, you’ll need to set your desired custom domain in your Mintlify settings and configure your DNS settings on your domain provider.

## Dashboard Settings

1.  Head over to the dashboard
2.  Click on “Settings”.
3.  Click on “Custom Domain”.
4.  Enter your desired custom domain. For example, `docs.mintlify.com`.

## Verification with Vercel

If Vercel happens to be your domain provider, you will have to add a verification `TXT` record. This information will show on your dashboard after submitting your custom domain, as well as be emailed to you.

## Configuring your DNS

1.  Proceed to your domain’s DNS settings on your domain provider’s website.
2.  Create a new DNS entry, inputting the following values:

If you are using Cloudflare for your DNS provider, you’ll need to have the “full strict” security option enabled for the https setting.

Please contact support if you don’t see the custom domain set up after the above configuration.

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/seo

You can set default meta tags by adding the `metadata` field to your `docs.json`.

## Changing meta tags on one page

Add your meta tags to the page’s metadata like so:

## Sitemaps

Mintlify automatically generates a `sitemap.xml` file and a `robots.txt` file. Simply add `/sitemap.xml` to the end of your website URL to see your sitemap. We recommend submitting the sitemap to search engines for improved SEO.

Only pages included in your `docs.json` are included by default. To include hidden links, add `seo.indexing` to your `docs.json`:

## Disabling indexing

If you want to stop a page from being indexed by search engines, you can include the following in the frontmatter of your page:

You can also specify `noindex` for all pages in your docs by setting the `metadata.robots` field to `"noindex"` in your `docs.json`:

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/llms

All documentation pages are auto-hosted in a variety of markdown formats to make it easier for:

*   End users to feed your docs into large language models (LLMs) for specific information retrieval
*   LLMs to efficiently index your content without parsing HTML or JavaScript

## Supported formats

We support industry standards such as /llms.txt as well as additional markdown formats.

*   **/llms.txt**: A markdown file of a structured index of your docs is automatically hosted at /llms.txt. Helps general-purpose LLMs index more efficiently (e.g. a sitemap for AI).
*   **/llms-full.txt**: A markdown file of all your docs content is automatically hosted at /llms-full.txt. Helps users load complete context into AI tools in one link.
*   **.md support**: Add .md to an individual docs page to see a markdown version of that page. Helps load individual pages into AI tools with better token efficiency & inference time.
*   **⌘ + c shortcut**: Copy markdown source of any page using command + c.

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/custom-scripts

Add custom CSS & JS to your documentation to fully customize the look and feel.

Add any number of CSS files to your repository and the defined class names will be applied and available across all of your MDX files.

### Adding style.css

For example, you can add the following `style.css` file to customize the styling of the navbar and footer.

### Using Identifiers

Mintlify has a set of common identifiers to help you tag important elements of the UI. Some, but not all are listed in the following:

`#topbar-cta-button` `#navbar` `#sidebar` `#content-area` `#table-of-contents`

## Custom JS

Custom JS allows you to add custom executable code globally. It is the equivalent of adding a `<script>` tag with JS code into every page.

### Adding Custom JavaScript

Any `.js` file inside the content directory of your docs will be included in every documentation page. For example, you can add the following `ga.js` file to enable Google Analytics across the entire documentation.

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/broken-links

When you change the path of a file in your docs folder, it will also change the path of the URL to that page. This may happen when restructuring your docs or changing the sidebar title.

Catch broken links with our CLI. Simply install the CLI and run the command:

The CLI will identify any relative links in your docs that don’t exist.

## Redirects

Set up 301 redirects by adding the `redirects` field into your `docs.json` file.

This will permanently redirect `/source/path` to `/destination/path` so that you don’t lose any previous SEO for the original page.

To match a wildcard path, use `*` after a parameter. In this example, `/beta/:slug*` will match `/beta/introduction` and redirects it to `/v2/introduction`.

Was this page helpful?

On this page

*   Broken Links
*   Redirects

---

## Page: https://mintlify.com/docs/settings/github

Mintlify integrates with the GitHub API, enabling synchronization between your docs and your GitHub repository. This integration is made possible through the utilization of GitHub Apps.

## Installation

To begin, you need to install the Mintlify GitHub App into the GitHub account where your docs repo resides. Installing a GitHub App requires either organization ownership or admin permissions in a repository. If you lack the necessary permissions, the repository owner will need to approve the request. You can access the installation page by logging into the Mintlify dashboard.

For GitHub Apps, you can choose to only give permissions to a single repository. We highly recommend you do so as we only need access to the repository where your docs are hosted.

## Permissions

During the installation of our GitHub app, you will be prompted to grant certain permissions:

*   Read and write access to `checks`, `contents`, `deployments`, `pull requests`, and `workflows`

These permissions are leveraged to provide a seamless experience when managing your docs.

When you make a commit to the branch you configured as your docs deployment branch, we fetch the contents of the files changed to update your docs. To accomplish this we need read access to your `contents`.

When pull requests are created we create a check and preview deployment which is why we need write access to `checks` and `deployments`.

Inside the Mintlify web editor, Mintlify works on your behalf to create branches and pull requests which is why we need write access to `pull requests` and `workflows`.

## Repositories Installations

When installing our GitHub app, you will be prompted to select all repositories or a subset of them. This selection can be changed at any time by going to the GitHub app settings.

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/gitlab

Configurations

Sync your docs with a GitLab repo

We use a combination of Access tokens and Webhooks to authenticate and sync changes between GitLab and Mintlify.

*   We use Access tokens to pull information from GitLab.
*   We use Webhooks so GitLab can notify Mintlify when changes are made.
    *   This allows Mintlify to create preview deployments when a MR is created.

## Set up the connection

1

2

3

## Create the webhook

Webhooks allow us to receive events when changes are made so that we can automatically trigger deployments.

1

2

3

4

5

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/ci

Use CI checks to lint your docs for errors, and give you warnings before you deploy.

## Installation

To begin, you will need to have followed the steps on the GitHub page.

For GitHub Apps, you can choose to only give permissions to a single repository. We highly recommend you do so as we only need access to the repository where your docs are hosted.

## Configuration

You can configure the CI checks enabled for a deployment on the Mintlify dashboard by navigating to the ‘Add-Ons’ tab. There you can enable or disable the checks you’d like to run.

When enabling checks, you can choose to run them at a `Warning` or `Blocking` level.

## When Do They Run?

CI checks are configured to run on commits to your configured deployment branch, or on pull requests against that branch.

## Available CI Checks

### Broken Links

Similarly to how the CLI link checker works on your local machine, we will automatically check your docs for broken links. To see the results of this check, you can visit GitHub’s check results page for a specific commit.

### Vale

Vale is an open-source rule-based prose linter which supports a range of document types, including Markdown and MDX.

Mintlify supports automatically running Vale in a CI check, and displaying the results as a check status.

#### Configuration

If you have a `.vale.ini` file in the root the content directory for your deployment, we will automatically use that configuration file. We will also automatically use any configuration files in your specified `stylesPath`.

#### Packages

Vale supports a range of packages, which can be used to check for spelling and style errors. Any packages you include in your repository under the correct `stylesPath` will be automatically installed and used in your Vale configuration.

For packages not included in your repository, you may specify any packages from the Vale package registry, and they will automatically be downloaded and used in your Vale configuration.

#### Vale with MDX

Vale does not natively support MDX, but Vale’s author has provided a custom extension to support it.

If you’d prefer not to use this extension, we recommend the following lines in your `.vale.ini` file:

To use Vale’s in-document comments, use MDX-style comments `{/* ... */}`. If you use the `CommentDelimiters = {/*, */}` setting in your configuration, Vale will automatically interpret these comments while linting. This means you can easily use Vale’s in-built features, like skipping lines or sections.

If you choose not to use `CommentDelimiters`, but still choose to use Vale’s comments, you must wrap any Vale comments in MDX comments `{/* ... */}`. For example:

Please note that these commment tags are not supported within Mintlify components, but can be used anywhere at the base level of a document.

---

## Page: https://mintlify.com/docs/settings/preview-deployments

Preview Deployments allow you to preview changes to your docs in a live deployment without merging those changes to your production branch.

If you have created a pull or merge request when using Git, the generated preview URL will be available as a comment from the Mintlify bot in the PR. This URL will always reflect the latest deployment changes.

## Sharing Preview Deployments

After generating a preview URL, you can share that link with anybody for them to view.

### Authenticated Preview Deployments

If you’d like to restrict access to your Preview Deployments, you can set up preview deployment authentication. When using this authentication method, only Mintlify authenticated users will be able to access your Preview Deployments.

To set up preview deployment authentication, please contact sales.

Was this page helpful?

---

## Page: https://mintlify.com/docs/development

**Step 1**: Install the Mintlify CLI:

**Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command:

Alternatively, if you do not want to install the CLI globally you can use a run script available:

A local preview of your documentation will be available at `http://localhost:3000`.

### Custom Ports

By default, Mintlify uses port 3000. You can customize the port using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:

If you attempt to run on a port that’s already in use, it will use the next available port:

## Versions

Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn’t align with the production version, please update the CLI:

## Validating Links

The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:

## Deployment

If the deployment is successful, you should see the following:

## Code Formatting

We suggest using extensions on your IDE to recognize and format MDX. If you’re a VSCode user, consider the MDX VSCode extension for syntax highlighting, and Prettier for code formatting.

## Troubleshooting

Was this page helpful?

---

## Page: https://mintlify.com/docs/web-editor

Web Editor is the preferred way to edit docs directly without having to open your IDE or run `mintlify dev`.

The editor includes a few key features to integrate directly into your existing git workflow, like creating branches, pull requests, commits, and diffs for your current changes.

It also includes a fully editable experience for changing and adding content directly, even with custom components.

If you understand git workflows and our integrations already, you can skip to here.

## Git and update workflows

### Git basics

While Web Editor means you don’t need to go to GitHub or your command line to make changes, it’s still helpful to know the basics of git.

Git terminology:

*   **Repository**: The folder in which your code lives. It can be local (on your computer) or remote (like GitHub).
    
*   **Commit**: A snapshot of changes made to files in the repository.
    
*   **Branch**: A separate line of development. It’s a working copy of the code that allows you to work on changes without affecting the main version.
    
*   **Pull request:** A request to merge changes from a working branch into the main branch. This is used for reviewing content before making changes live.
    

### Making updates

In order to make updates to your docs, we include a few buttons specifically to integrate with your git workflow.

1

2

3

## Editing content

### Slash commands

The easiest way to add content in the editor is by using **“Slash commands”**, which are commands you have access to after typing `/` in the **“Visual Editor”** mode:

As you type, you’ll see more options pop up:

#### Content blocks

Here are the types of content blocks available to add in the **“Visual Editor”**:

### Adding images

You can add images to your page by typing `/image` and either clicking on the **“Image”** option or hitting ↓ + Enter on the **“Image”** option.

This will open up the image modal where you have the option to either upload a new image or use an existing image from the repo.

Uploading an image can be done through the modal:

And you can preview an existing image before you add it.

### Editing images

In order to edit images, you just have to hover over the image to see the **“Delete”** and **“Edit”** buttons on the top right of the image.

Clicking the **“Edit”** button lets you edit the attributes of the image.

If you want to update the source of an image to be a new image that you haven’t yet uploaded, you have to first delete the image you’re changing, and then add a new one using the instructions above.

## Editor modes

In order to offer the most flexibility, the editor has three modes:

### Visual Editor

The **“Visual Editor”** is the typical WYSIWYG mode you’d see in something like Notion. It offers you a view into your docs in a fully editable way that reflects what the final page would look like on your main docs site.

### Source Editor

The **“Source Editor”** offers you a way to edit your MDX files in code, the same way you’d do in your IDE. This offers less flexibility, in that our components aren’t available for auto-complete, but it does have two unique advantages.

1.  It allows you to edit props of components (see our limitations below) which is currently not available in **“Visual Editor”** mode yet.
    
2.  It allows you to correct syntax errors which might’ve appeared in your repo that might not be compatible with **“Visual Editor”** mode until you’ve fixed them.
    

### Diff View

The **“Diff View”** is a way to view the changes made to a specific document before committing it to your repository.

This will help you see changes you’ve made along with formatting changes made by the editor.

## Current limitations

We do have a few current limitations in the editor that we’re working to resolve.

## Feedback

If you have any bug reports, feature requests, or other general feedback, we’d love to hear where we can improve.

Email us at \[email protected\]

---

## Page: https://mintlify.com/docs/content/components

You can put any content in here. Check out AccordionGroup if you want to group multiple Accordions into a single display.

    <Accordion title="I am an Accordion.">
      You can put any content in here.
    </Accordion>
    

## Props

title

string

required

Title in the Accordion preview.

description

string

Detail below the title in the Accordion preview.

defaultOpen

boolean

default:"false"

Whether the Accordion is open by default.

icon

string or svg

iconType

string

One of “regular”, “solid”, “light”, “thin”, “sharp-solid”, “duotone”, or “brands”

---

## Page: https://mintlify.com/docs/api-playground/openapi/setup#autogenerate-files-recommended

## Add an OpenAPI specification file

To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI document in either JSON or YAML format that follows the OpenAPI specification. Your document must follow OpenAPI specification 3.0+.

## Auto-populate API pages

The fastest way to get started with OpenAPI is to add an `openapi` field to a tab in the `docs.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab.

**Example with Tabs:**

**Example with Groups:**

When using this option, the metadata for the generated pages will have the following default values:

*   `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.
    
*   `description`: The `description` field from the OpenAPI operation, if present.
    
*   `version`: The `version` value from the anchor or tab, if present.
    

There are some scenarios in which the default behavior isn’t sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page.

## Create MDX files for API pages

If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you’ll need an MDX page for each operation. Here is an example MDX OpenAPI page from MindsDB.

### Manually specify files

You can always create an MDX page manually, and reference the OpenAPI operation in the page’s metadata using the `openapi` field.

By using the OpenAPI reference, the name, description, parameters, responses, and the API playground will be automatically generated from the OpenAPI document.

If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have only one OpenAPI file - it will automatically detect your OpenAPI file.

If you want to reference an external OpenAPI file using this method, provide the file’s URL in the docs.json. See here for the correct format.

### Autogenerate files

For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper.

Our Mintlify scraper autogenerates MDX files for your OpenAPI endpoints.

Each generated page will correspond to an OpenAPI operation under the “paths” section of the OpenAPI schema. If your OpenAPI document is version 3.1+, the scraper will also generate pages for webhooks under the “webhooks” section of the OpenAPI schema.

Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files will populate in the working directory.

Learn more about our scraping package here.

The scraper will output an array of Navigation entries containing your OpenAPI MDX files. You can either append these entries to your existing Navigation, or reorder and add the files to your navigation manually.

## Create MDX files for OpenAPI schemas

Mintlify also allows you to create individual pages for any OpenAPI schema defined in an OpenAPI document’s `components.schemas` field:

---

## Page: https://mintlify.com/docs/api-playground/openapi/writing-openapi

## Describing your API

There are many great tools online for learning about and constructing OpenAPI documents. Here are our favorites:

*   Swagger’s OpenAPI Guide for familiarizing yourself with the OpenAPI syntax
*   OpenAPI v3.1.0 Specification for all the details about the newest OpenAPI specification
*   Swagger & OpenAPI Validator for debugging your OpenAPI document
*   Swagger’s Editor for seeing examples in action

## Specifying the URL for your API

In an OpenAPI document, different API endpoints are specified by their paths, like `/users/{id}`, or maybe simply `/`. To specify the base URL to which these paths should be appended, OpenAPI provides the `servers` field. This field is necessary to use some Mintlify features like the API Playground. Read how to configure the `servers` field in the Swagger documentation.

The API Playground will use these server URLs to determine where to send requests. If multiple servers are specified, a dropdown will appear to allow toggling between servers. If no server is supplied, the API Playground will use simple mode, as there is no way to send a request.

If different endpoints within your API exist at different URLs, you can override the server field for a given path or operation.

## Specifying authentication

Nearly all APIs require some method of authentication. OpenAPI provides the `securitySchemes` field for defining the methods of authentication used throughout your API, with simple configuration for the most common authentication types - Basic, Bearer, and API Keys. To apply these authentication methods to your endpoints, OpenAPI uses the `security` field. The syntax for defining and applying authentication is a bit unintuitive, so definitely check out Swagger’s documentation and examples on the topic.

The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document.

If different endpoints within your API require different methods of authentication, you can override the security field for a given operation.

Was this page helpful?

---

## Page: https://mintlify.com/docs/integrations/analytics/overview

Automatically send data about your documentation engagement to your third party analytics provider.

Set your analytics keys in `docs.json`. You can add an unlimited number of analytics integrations for free.

The syntax for `docs.json` is below. You only need to include entries for the platforms you want to connect.

    "integrations": {
        "amplitude": {
            "apiKey": "required"
        },
        "clearbit": {
            "publicApiKey": "required"
        },
        "fathom": {
            "siteId": "required"
        },
        "ga4": {
            "measurementId": "required"
        },
        "gtm": {
            "tagId": "required"
        },
        "hotjar": {
            "hjid": "required",
            "hjsv": "required"
        },
        "koala": {
            "publicApiKey": "required"
        },
        "logrocket": {
            "appId": "required"
        },
        "mixpanel": {
            "projectToken": "required"
        },
        "pirsch": {
            "id": "required"
        },
        "plausible": {
            "domain": "required"
        },
        "posthog": {
            "apiKey": "required",
            "apiHost": "optional"
        },
        "segment": {
          "key": "required"
        },
    }

---

## Page: https://mintlify.com/docs/_sites/mintlify/settings/global#properties

## Getting Started

Welcome! Follow the instructions below to learn how to deploy, update and supercharge your documentation with Mintlify.

### Creating the Repository

Mintlify docs are rendered from MDX files and configurations defined in our starter kit. We use GitHub to integrate your docs with your code, and make source control effortless. Onboard through the dashboard or clone our starter kit to get started.

### Updating the Content

Mintlify enables you to easily customize the style, structure, and content of your docs.

### Publishing

Congrats! You’ve set up your Mintlify Docs and it’s looking amazing! Need support or want to give some feedback? You can join our community or drop us an email at \[email protected\].

Was this page helpful?

---

## Page: https://mintlify.com/docs/navigation/versions

`"versions"` in your `docs.json` can be leveraged to partition your navigation into different versions.

docs.json

    {
      "navigation": {
        "versions": [
          {
            "version": "1.0.0",
            "groups": [
              {
                "group": "Getting Started",
                "pages": ["v1/overview", "v1/quickstart", "v1/development"]
              }
            ]
          },
          {
            "version": "2.0.0",
            "groups": [
              {
                "group": "Getting Started",
                "pages": ["v2/overview", "v2/quickstart", "v2/development"]
              }
            ]
          }
        ]
      }
    }
    

You can also add versioning to a specific section of your docs by nesting a version.

docs.json

    {
      "tabs": [
        {
          "tab": "Guides",
          "pages": ["overview", "quickstart"]
        },
        {
          "tab": "SDKs",
          "versions": [
            {
              "version": "latest",
              "anchors": [
                {
                  "anchor": "Javascript",
                  "pages": ["sdk/js/create", "sdk/js/edit", "sdk/js/delete"]
                },
                {
                  "anchor": "Python",
                  "pages": ["sdk/py/create", "sdk/py/edit", "sdk/py/delete"]
                }
              ]
            }
          ]
        }
      ]
    }

---

## Page: https://mintlify.com/docs/api-playground

API References

Enable users to interact with your API

POST

The API playground is an interactive environment to make requests and preview an API endpoint.

Authorization

string

header

required

Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.

projectId

string

required

The ID of the project to trigger an update on. Can be retrieved from your dashboard.

#### Response

202 - application/json

A successful response

statusId

string

The status id of the triggered updated.

Was this page helpful?

---

## Page: https://mintlify.com/docs/api-playground/openapi/advanced-features#x-codesamples

OpenAPI 3 has some advanced features for describing complex APIs. Here’s how you can use them with Mintlify.

## `oneOf`, `anyOf`, `allOf`

For complex datatypes, OpenAPI provides the `oneOf`, `anyOf`, and `allOf` keywords, allowing you to combine schemas in certain ways. You can read more about these keywords in the Swagger documentation, but essentially:

*   `oneOf` functions like an “exclusive-or” operator
*   `anyOf` functions like an “or” operator
*   `allOf` functions like an “and” operator

### Combining schemas with `allOf`

Mintlify performs some preprocessing on your OpenAPI document to display these 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`.

org\_with\_users

object

id

string

The ID of the organization

users

object\[\]

An array containing all users in the organization

### Providing options with `oneOf` and `anyOf`

When you use `oneOf` or `anyOf`, Mintlify displays the options in a tabbed container. To give your options helpful names, make sure to give each subschema a `title` field. For example, here’s how you might display two different types of delivery addresses:

delivery\_address

object

address\_line\_1

string

The street address of the residence

## `x-codeSamples`

If your users interact with your API using an SDK rather than directly through a network request, you can add code samples to your OpenAPI document, and Mintlify will display them in your OpenAPI pages. You can define your code samples using the `x-codeSamples` extension. This property can be added within any request method, and has the following schema:

lang

string

required

The language of the code sample.

label

string

The label for the sample. This is useful when providing multiple examples for a single endpoint.

source

string

required

The source code of the sample.

Here’s an example of some code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK.

---

## Page: https://mintlify.com/docs/navigation/overview

It can contain one of seven properties:

*   `pages`
*   `groups`
*   `anchors`
*   `tabs`
*   `dropdowns`
*   `versions`
*   `languages`

These properties all serve the function of partitioning your content and creating a hierarchy so that it’s easier for your users to navigate through your documentation.

If you’re currently using the legacy `mint.json` configuration file, please update the CLI:

    npm i -g mintlify@latest
    

And run the new `upgrade` command in your docs repository:

    mintlify upgrade
    

This will generate a `docs.json` based off of your `mint.json`. Then, please delete the `mint.json` file from your repository.

If you want to learn more about the difference between `mint.json` and `docs.json` checkout our blog

---

## Page: https://mintlify.com/docs/navigation/localization

`"languages"` in your `docs.json` can be leveraged to partition your navigation into different languages.

We currently support localization in the following languages:

*   Arabic (`ar`)
*   Chinese (`cn` or `zh`, `zh-Hans` for Simplified and `zh-Hant` for Traditional)
*   English (`en`)
*   French (`fr`)
*   German (`de`)
*   Indonesian (`id`)
*   Italian (`it`)
*   Japanese (`jp` or `ja`)
*   Korean (`ko`)
*   Portuguese (`pt`)
*   Portuguese (Brazil) (`pt-BR`)
*   Russian (`ru`)
*   Spanish (`es`)
*   Turkish (`tr`)

docs.json

## AI Translations \[BETA\]

Automatically translate your docs from one language to another from a click of a button.

AI translations allows you to choose a language you want to translate your docs to. After triggering a translation through the dashboard, it will generate a PR with the translated pages and an edited `docs.json` which gives you the opportunity to review the translations.

Was this page helpful?

On this page

*   AI Translations \[BETA\]

---

## Page: https://mintlify.com/docs/content/components/accordions

You can put any content in here. Check out AccordionGroup if you want to group multiple Accordions into a single display.

    <Accordion title="I am an Accordion.">
      You can put any content in here.
    </Accordion>
    

## Props

title

string

required

Title in the Accordion preview.

description

string

Detail below the title in the Accordion preview.

defaultOpen

boolean

default:"false"

Whether the Accordion is open by default.

icon

string or svg

iconType

string

One of “regular”, “solid”, “light”, “thin”, “sharp-solid”, “duotone”, or “brands”

---

## Page: https://mintlify.com/docs/content/components/frames

Frames are very helpful if you want to center an image.

## 



Captions

You can add additional context to an image using the optional `caption` prop.

Yosemite National Park is visited by over 3.5 million people every year

## 



Props



caption

string

Optional caption text to show centered under your component.

    <Frame>
      <img src="/path/image.jpg" />
    </Frame>

---

## Page: https://mintlify.com/docs/content/components/code

## Basic Code Block

Use fenced code blocks by enclosing code in three backticks.

## Syntax Highlighting

Put the name of your programming language after the three backticks to get syntax highlighting.

We use Prism for syntax highlighting. Test Drive Prism lists all the languages supported.

## Names

Add a title after the programming language to set the name of your code example. The text can be anything as long as its all in one line.

Code Block Example

Code Block Example

## Line Highlighting

Highlight specific lines in your code blocks by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas.

Line Highlighting Example

## Expandable

If you have a long code block and `[expandable]` after your title to make it close and expand.

library.py

## Code Groups

Want to display multiple code examples in one code box? Check out the Code Group docs:

## Code Group

Read the reference for the Code Group component

Was this page helpful?

---

## Page: https://mintlify.com/docs/api-playground/openapi

## Add an OpenAPI specification file

To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI document in either JSON or YAML format that follows the OpenAPI specification. Your document must follow OpenAPI specification 3.0+.

## Auto-populate API pages

The fastest way to get started with OpenAPI is to add an `openapi` field to a tab in the `docs.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab.

**Example with Tabs:**

**Example with Groups:**

When using this option, the metadata for the generated pages will have the following default values:

*   `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.
    
*   `description`: The `description` field from the OpenAPI operation, if present.
    
*   `version`: The `version` value from the anchor or tab, if present.
    

There are some scenarios in which the default behavior isn’t sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page.

## Create MDX files for API pages

If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you’ll need an MDX page for each operation. Here is an example MDX OpenAPI page from MindsDB.

### Manually specify files

You can always create an MDX page manually, and reference the OpenAPI operation in the page’s metadata using the `openapi` field.

By using the OpenAPI reference, the name, description, parameters, responses, and the API playground will be automatically generated from the OpenAPI document.

If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have only one OpenAPI file - it will automatically detect your OpenAPI file.

If you want to reference an external OpenAPI file using this method, provide the file’s URL in the docs.json. See here for the correct format.

### Autogenerate files

For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper.

Our Mintlify scraper autogenerates MDX files for your OpenAPI endpoints.

Each generated page will correspond to an OpenAPI operation under the “paths” section of the OpenAPI schema. If your OpenAPI document is version 3.1+, the scraper will also generate pages for webhooks under the “webhooks” section of the OpenAPI schema.

Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files will populate in the working directory.

Learn more about our scraping package here.

The scraper will output an array of Navigation entries containing your OpenAPI MDX files. You can either append these entries to your existing Navigation, or reorder and add the files to your navigation manually.

## Create MDX files for OpenAPI schemas

Mintlify also allows you to create individual pages for any OpenAPI schema defined in an OpenAPI document’s `components.schemas` field:

---

## Page: https://mintlify.com/docs/api-playground/mdx/authentication

## Enabling Authentication

You can add an authentication method to your docs.json to enable it on every page or you can set it on a per-page basis.

The page’s authentication method will override docs.json if both are set.

### Bearer Token

    "api": {
        "mdx": {
          "auth": {
            "method": "bearer"
          }
        }
    }
    

### Basic Authentication

    "api": {
        "mdx": {
          "auth": {
            "method": "basic"
          }
        }
    }
    

### API Key

    "api": {
        "mdx": {
          "auth": {
            "method": "key",
            "name": "x-api-key"
          }
        }
    }
    

### None

The “none” authentication method is useful to disable authentication on a specific endpoint after setting a default in docs.json.

    ---
    title: "Your page title"
    authMethod: "none"
    ---

---

## Page: https://mintlify.com/docs/advanced/subpath/cloudflare

## Create Cloudflare Worker

Navigate to the `Workers & Pages > Create application > Create worker`. You should be presented with the following screen where you can create a new Cloudlfare worker.

### Add custom domain

Once the worker is created, click `Configure worker`. Navigate to the worker `Settings > Triggers`. Click on `Add Custom Domain` to add your desired domain into the list - we recommend you add both the version with and without `www.` prepended to the domain.

If you have trouble setting up a custom subdirectory, contact our support team and we’ll walk you through upgrading your hosting with us.

### Edit Worker Script

Click on `Edit Code` and add the following script into the worker’s code.

Click on `Deploy` and wait for the changes to propagate (it can take up to a few hours).

Was this page helpful?

---

## Page: https://mintlify.com/docs/_sites/mintlify/web-editor#editing-content

## Getting Started

Welcome! Follow the instructions below to learn how to deploy, update and supercharge your documentation with Mintlify.

### Creating the Repository

Mintlify docs are rendered from MDX files and configurations defined in our starter kit. We use GitHub to integrate your docs with your code, and make source control effortless. Onboard through the dashboard or clone our starter kit to get started.

### Updating the Content

Mintlify enables you to easily customize the style, structure, and content of your docs.

### Publishing

Congrats! You’ve set up your Mintlify Docs and it’s looking amazing! Need support or want to give some feedback? You can join our community or drop us an email at \[email protected\].

Was this page helpful?

---

## Page: https://mintlify.com/docs/content/components/callouts

### 



Note Callouts

This adds a note in the content

    <Note>This adds a note in the content</Note>
    

### 



Warning Callouts

This raises a warning to watch out for

    <Warning>This raises a warning to watch out for</Warning>
    

### 



Info Callouts

This draws attention to important information

    <Info>This draws attention to important information</Info>
    

### 



Tip Callouts

This suggests a helpful tip

    <Tip>This suggests a helpful tip</Tip>
    

### 



Check Callouts

This brings us a checked status

    <Check>This brings us a checked status</Check>

---

## Page: https://mintlify.com/docs/content/components/accordion-groups

Components

Group multiple accordions into a single display.

    <AccordionGroup>
      <Accordion title="FAQ without Icon">
        You can put other components inside Accordions.
    
        ```java HelloWorld.java
        class HelloWorld {
            public static void main(String[] args) {
                System.out.println("Hello, World!");
            }
        }
        ```
    
      </Accordion>
    
      <Accordion title="FAQ with Icon" icon="alien-8bit">
        Check out the [Accordion](/content/components/accordions) docs for all the supported props.
      </Accordion>
    
      <Accordion title="FAQ without Icon">
        Check out the [Accordion](/content/components/accordions) docs for all the supported props.
      </Accordion>
    </AccordionGroup>
    

Simply add `<AccordionGroup>` around your existing `<Accordion>` components.

You can put other components inside Accordions.

HelloWorld.java

    class HelloWorld {
        public static void main(String[] args) {
            System.out.println("Hello, World!");
        }
    }
    

Check out the Accordion docs for all the supported props.

Check out the Accordion docs for all the supported props.

    <AccordionGroup>
      <Accordion title="FAQ without Icon">
        You can put other components inside Accordions.
    
        ```java HelloWorld.java
        class HelloWorld {
            public static void main(String[] args) {
                System.out.println("Hello, World!");
            }
        }
        ```
    
      </Accordion>
    
      <Accordion title="FAQ with Icon" icon="alien-8bit">
        Check out the [Accordion](/content/components/accordions) docs for all the supported props.
      </Accordion>
    
      <Accordion title="FAQ without Icon">
        Check out the [Accordion](/content/components/accordions) docs for all the supported props.
      </Accordion>
    </AccordionGroup>
    

`AccordionGroup` does not have any props.

Was this page helpful?

---

## Page: https://mintlify.com/docs/content/components/cards

## Card Title

This is how you use a card with an icon and a link. Clicking on this card brings you to the Card Group page.

### Horizontal Card

Add a `horizontal` property to a card to make it horizontally displayed.

### Image Card

Add an `img` property to a card to display an image on the top of the card.

## Props

title

string

required

The title of the card

icon

string or svg

iconType

string

One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`

color

string

The color of the icon as a hex code

href

string

The url that clicking on the card would navigate the user to

horizontal

boolean

Makes the card more compact and horizontal

img

string

The url or local path to an image to display on the top of the card

Was this page helpful?

---

## Page: https://mintlify.com/docs/content/components/card-groups

Components

Show cards side by side in a grid format

    <CardGroup cols={2}>
      <Card title="First Card" icon="square-1">
        Neque porro quisquam est qui dolorem ipsum quia dolor sit amet
      </Card>
      <Card title="Second Card" icon="square-2">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit
      </Card>
      <Card title="Third Card" icon="square-3">
        Ut enim ad minim veniam, quis nostrud exercitation ullamco
      </Card>
      <Card title="Fourth Card" icon="square-4">
        Excepteur sint occaecat cupidatat non proident
      </Card>
    </CardGroup>
    

The `CardGroup` component lets you group multiple `Card` components together. It’s most often used to put multiple cards on the same column.

## First Card

Neque porro quisquam est qui dolorem ipsum quia dolor sit amet

## Second Card

Lorem ipsum dolor sit amet, consectetur adipiscing elit

## Third Card

Ut enim ad minim veniam, quis nostrud exercitation ullamco

## Fourth Card

Excepteur sint occaecat cupidatat non proident

    <CardGroup cols={2}>
      <Card title="First Card" icon="square-1">
        Neque porro quisquam est qui dolorem ipsum quia dolor sit amet
      </Card>
      <Card title="Second Card" icon="square-2">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit
      </Card>
      <Card title="Third Card" icon="square-3">
        Ut enim ad minim veniam, quis nostrud exercitation ullamco
      </Card>
      <Card title="Fourth Card" icon="square-4">
        Excepteur sint occaecat cupidatat non proident
      </Card>
    </CardGroup>
    

## Props

cols

default:2

The number of columns per row

Was this page helpful?

---

## Page: https://mintlify.com/docs/content/components/code-groups

Components

The CodeGroup component lets you combine code blocks in a display separated by tabs

    <CodeGroup>
    
    ```javascript helloWorld.js
    console.log("Hello World");
    ```
    
    ```python hello_world.py
    print('Hello World!')
    ```
    
    ```java HelloWorld.java
    class HelloWorld {
        public static void main(String[] args) {
            System.out.println("Hello, World!");
        }
    }
    ```
    
    </CodeGroup>
    

You will need to make Code Blocks then add the `<CodeGroup>` component around them. Every Code Block must have a filename because we use the names for the tab buttons.

See below for an example of the end result.

    console.log("Hello World");
    

    <CodeGroup>
    
    ```javascript helloWorld.js
    console.log("Hello World");
    ```
    
    ```python hello_world.py
    print('Hello World!')
    ```
    
    ```java HelloWorld.java
    class HelloWorld {
        public static void main(String[] args) {
            System.out.println("Hello, World!");
        }
    }
    ```
    
    </CodeGroup>
    

Was this page helpful?

    <CodeGroup>
    
    ```javascript helloWorld.js
    console.log("Hello World");
    ```
    
    ```python hello_world.py
    print('Hello World!')
    ```
    
    ```java HelloWorld.java
    class HelloWorld {
        public static void main(String[] args) {
            System.out.println("Hello, World!");
        }
    }
    ```
    
    </CodeGroup>

---

## Page: https://mintlify.com/docs/content/components/tabs

Components

Toggle content using the Tabs component

    <Tabs>
      <Tab title="First Tab">
        ☝️ Welcome to the content that you can only see inside the first Tab.
      </Tab>
      <Tab title="Second Tab">
        ✌️ Here's content that's only inside the second Tab.
      </Tab>
      <Tab title="Third Tab">
        💪 Here's content that's only inside the third Tab.
      </Tab>
    </Tabs>
    

You can add any number of tabs.

☝️ Welcome to the content that you can only see inside the first Tab.

    <Tabs>
      <Tab title="First Tab">
        ☝️ Welcome to the content that you can only see inside the first Tab.
      </Tab>
      <Tab title="Second Tab">
        ✌️ Here's content that's only inside the second Tab.
      </Tab>
      <Tab title="Third Tab">
        💪 Here's content that's only inside the third Tab.
      </Tab>
    </Tabs>
    

## Tab Props

title

string

required

The title of the tab. Short titles are easier to navigate.

Was this page helpful?

---

## Page: https://mintlify.com/docs/content/components/steps

Steps are the best way to display a series of actions of events to your users. You can add as many steps as desired.

1

2

3

## Steps Props

children

ReactElement<StepProps>\[\]

required

A list of `Step` components.

titleSize

string

default:"p"

The size of the step titles. One of `p`, `h2` and `h3`.

## Individual Step Props

children

string | ReactNode

required

The content of a step either as plain text, or components.

icon

string or svg

iconType

string

One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`

title

string

The title is the primary text for the step and shows up next to the indicator.

stepNumber

number

The number of the step.

titleSize

string

default:"p"

The size of the step titles. One of `p`, `h2` and `h3`.

Was this page helpful?

---

## Page: https://mintlify.com/docs/content/components/update

The `Update` component is used to keep track of changes and updates.

2024-10-12

v0.1.1

## Changelog

You can add anything here, like a screenshot, a code snippet, or a list of changes.

#### Features

*   Responsive design
*   Sticky section for each changelog

2024-10-11

v0.1.0

### How to use

    <Update label="2024-10-12" description="v0.1.1">
      This is how you use a changelog with a label 
      and a description.
    </Update>
    <Update label="2024-10-11" description="v0.1.0">
      This is how you use a changelog with a label 
      and a description.
    </Update>
    

You can use multiple `Update` components to create changelogs.

Each `label` creates an anchor and also shows up on the table of contents on the right.

## Props

label

string

required

Label in the changelog, on the sticky left side.

description

string

Description below the label in the Changelog preview.

tags

string\[\]

Tags for the changelog, will be show as filters in the right side panel

---

## Page: https://mintlify.com/docs/content/components/icons

    <Icon icon="check" size={32} />
    

## 



Inline Icons

The icon will be placed inline when used in a paragraph.

Inline Icon Example

    <Icon icon="check" iconType="solid" /> The documentation you want, effortlessly 
    

The documentation you want, effortlessly

## 



Props



icon

string

required

A Font Awesome icon



iconType

string

One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`



color

string

The color of the icon as a hex code (e.g., `#FF5733`)



size

number

The size of the icon in pixels

---

## Page: https://mintlify.com/docs/content/components/mermaid-diagrams

    ```mermaid
      flowchart LR
        subgraph subgraph1
            direction TB
            top1[top] --> bottom1[bottom]
        end
        subgraph subgraph2
            direction TB
            top2[top] --> bottom2[bottom]
        end
        %% ^ These subgraphs are identical, except for the links to them:
    
        %% Link *to* subgraph1: subgraph1 direction is maintained
        outside --> subgraph1
        %% Link *within* subgraph2:
        %% subgraph2 inherits the direction of the top-level graph (LR)
        outside ---> top2
    ```
    

Mermaid lets you create visual diagrams using text and code.

You can create the following using Mermaid diagrams:

*   Flowchart
*   Sequence diagram
*   Class diagram
*   State diagram
*   Entity relationship diagram
*   User journey
*   and more

For a complete list of diagrams supported by Mermaid, check out their website.

## Syntax for Mermaid diagrams

To create a flowchart, you can write the Mermaid flowchart inside a Mermaid code block.

    ```mermaid
    // Your mermaid code block here
    ```

---

## Page: https://mintlify.com/docs/content/components/tooltips

Components

Show a definition when you hover over text.

    <Tooltip tip="This is a tooltip!">Hover over me</Tooltip>
    

and see a tooltip in action

    <Tooltip tip="This is a tooltip!">Hover over me</Tooltip>
    

Was this page helpful?

Previous

UpdateKeep track of changes and updates

Next

---

## Page: https://mintlify.com/docs/content/components/params

`ParamField` components help define the parameters for your APIs or SDKs. Adding a ParamField will automatically add an API Playground.

param

string

required

An example of a parameter field

    <ParamField path="param" type="string">
      An example of a parameter field
    </ParamField>
    

## Props

query, path, body, or header

string

Whether it is a query, path, body, or header parameter followed by the name

type

string

Expected type of the parameter’s value

Supports `number`, `string`, `bool`, `object`.

Arrays can be defined using the `[]` suffix. For example `string[]`.

required

boolean

Indicate whether the parameter is required

deprecated

boolean

Indicate whether the parameter is deprecated

default

string

Default value used by the server if the request does not provide a value

initialValue

any

Value that will be used to initialize the playground

placeholder

string

Placeholder text for the input in the playground

children

string

Description of the parameter (markdown enabled)

---

## Page: https://mintlify.com/docs/content/components/responses

The `<ResponseField>` component is designed to define the return values of an API. Many docs also use `<ResponseField>` on pages when you need to list the types of something.

response

string

required

A response field example

    <ResponseField name="response" type="string" required>
      A response field example
    </ResponseField>
    

## Props

name

string

required

The name of the response value.

type

string

required

Expected type of the response value

default

string

The default value.

required

boolean

Show “required” beside the field name.

---

## Page: https://mintlify.com/docs/content/components/expandables

API Components

Toggle to display nested properties.

    <ResponseField name="user" type="User Object">
      <Expandable title="properties">
        <ResponseField name="full_name" type="string">
          The full name of the user
        </ResponseField>
    
        <ResponseField name="is_over_21" type="boolean">
          Whether the user is over 21 years old
        </ResponseField>
      </Expandable>
    </ResponseField>
    

user

User Object

full\_name

string

The full name of the user

is\_over\_21

boolean

Whether the user is over 21 years old

    <ResponseField name="user" type="User Object">
      <Expandable title="properties">
        <ResponseField name="full_name" type="string">
          The full name of the user
        </ResponseField>
    
        <ResponseField name="is_over_21" type="boolean">
          Whether the user is over 21 years old
        </ResponseField>
      </Expandable>
    </ResponseField>
    

## Props

title

string

The name of the object you are showing. Used to generate the “Show NAME” and “Hide NAME” text.

defaultOpen

boolean

default:"false"

Set to true to show the component as open when the page loads.

Was this page helpful?

---

## Page: https://mintlify.com/docs/content/components/sticky-examples

The `<RequestExample>` and `<ResponseExample>` stick code blocks to the top-right of a page even as you scroll. The components work on all pages even if you don’t use an API playground.

`<RequestExample>` and `<ResponseExample>` show up like regular code blocks on mobile.

## Request Example

The `<RequestExample>` component works similar to CodeGroup, but displays the request content on the right sidebar. Thus, you can put multiple code blocks inside `<RequestExample>`.

Please set a name on every code block you put inside RequestExample.

## Response Example

The `<ResponseExample>` component is the same as `<RequestExample>` but will show up underneath it.

Was this page helpful?

---

## Page: https://mintlify.com/docs/integrations/analytics/amplitude

Analytics

Add the following to your `docs.json` file to send analytics to Amplitude.

    "integrations": {
        "amplitude": {
            "apiKey": "required"
        }
    }
    

Was this page helpful?

Previous

Clearbit

Next

---

## Page: https://mintlify.com/docs/integrations/analytics/clearbit

Analytics

Add the following to your `docs.json` file to send analytics to Clearbit.

    "integrations": {
        "clearbit": {
            "publicApiKey": "required"
        }
    }
    

Was this page helpful?

Previous

Fathom

Next

---

## Page: https://mintlify.com/docs/integrations/analytics/fathom

Add the following to your `docs.json` file to send analytics to Fathom.

You can get the `siteId` from your script settings.

    "integrations": {
        "fathom": {
            "siteId": "required"
        }
    }

---

## Page: https://mintlify.com/docs/integrations/analytics/google-analytics

You will need to generate a new property to use with Mintlify. The data collected will go into the same project as your other Google Analytics data.

If you are using the old version of Google Analytics, Universal Analytics, you will still be able to generate a property. data is slightly different from UA data but still gets collected in the same project.

## How to Connect GA4 to Mintlify

### Create a Web Stream

You will need to create a web stream to get the Measurement ID to put into Mintlify.

Click the cog at the bottom left of the Google Analytics screen. Then click on Data Streams.

Create a Web Stream and put the URL of your Mintlify docs site as the stream URL.

Your Measurement ID looks like `G-XXXXXXX` and will show up under Stream Details immediately after you create the Web Stream.

### Put Measurement ID in docs.json

Add your Measurement ID to your `docs.json` file like so:

docs.json

### Wait

Google Analytics takes two to three days to show your data.

You can use the Google Analytics Debugger to check analytics are enabled correctly. The extension will log to your browser’s console every time GA4 makes a request.

Was this page helpful?

---

## Page: https://mintlify.com/docs/integrations/analytics/google-tag-manager

Add your tag ID to `docs.json` file and we’ll inject the Google Tag Manager script to all your pages.

You are responsible for setting up cookie consent banners with Google Tag Manager if you need them.

    "integrations": {
        "gtm": {
            "tagId": "required"
        }
    }

---

## Page: https://mintlify.com/docs/integrations/analytics/heap

Analytics

Add the following to your `docs.json` file to send analytics to Heap.

    "integrations": {
        "heap": {
            "appId": "required"
        }
    }
    

Was this page helpful?

Previous

HotJar

Next

---

## Page: https://mintlify.com/docs/integrations/analytics/hotjar

Add the following to your `docs.json` file to send analytics to HotJar.

Analytics options in docs.json

    "integrations": {
        "hotjar": {
            "hjid": "required",
            "hjsv": "required"
        }
    }

---

## Page: https://mintlify.com/docs/integrations/analytics/koala

Analytics

Add the following to your `docs.json` file to send analytics to Koala.

    "integrations": {
        "koala": {
            "publicApiKey": "required"
        }
    }
    

Was this page helpful?

Previous

LogRocket

Next

---

## Page: https://mintlify.com/docs/integrations/analytics/logrocket

Analytics

Add the following to your `docs.json` file to send analytics to LogRocket.

Analytics options in docs.json

    "integrations": {
        "logrocket": {
            "apiKey": "required"
        }
    }
    

Was this page helpful?

Previous

Mixpanel

Next

---

## Page: https://mintlify.com/docs/integrations/analytics/mixpanel

Analytics

Add the following to your `docs.json` file to send analytics to Mixpanel.

Analytics options in docs.json

    "integrations": {
        "mixpanel": {
            "projectToken": "required"
        }
    }
    

Was this page helpful?

Previous

Pirsch

Next

---

## Page: https://mintlify.com/docs/integrations/analytics/pirsch

Add the following to your `docs.json` file to send analytics to Pirsch.

You can get your site ID from Settings > Developer > Identification Code.

    "integrations": {
        "pirsch": {
            "id": "required"
        }
    }

---

## Page: https://mintlify.com/docs/integrations/analytics/plausible

Analytics

Add your site’s domain to `docs.json` to send analytics to Plausible.

Do not include `https://` for the domain or server.

    "integrations": {
        "plausible": {
            "domain": "required",
            "server": "optional"
        }
    }
    

Was this page helpful?

Previous

PostHog

Next

---

## Page: https://mintlify.com/docs/integrations/analytics/posthog

Add the following to your `docs.json` file to send analytics to PostHog.

You only need to include `apiHost` if you are self-hosting PostHog. We send events to `https://app.posthog.com` by default.

    "integrations": {
        "posthog": {
            "apiKey": "YOUR_POSTHOG_PROJECT_API_KEY",
            "apiHost": "optional"
        }
    }
    

  

Enabling PostHog analytics will disable the analytics on the Mintlify dashboard.

## Session Recordings

You need to add the URL for your docs website to Posthog’s “Authorized domains for recordings” before you can receive session recordings. The option to add your URL is in Posthog’s project settings.

---

## Page: https://mintlify.com/docs/integrations/analytics/segment

Analytics

Add your Segment write key to your `docs.json` file to send analytics to Segment.

    "integrations": {
        "segment": {
            "key": "required",
        }
    }
    

Was this page helpful?

Previous

SpeakeasyAutomate your SDK usage snippets in the API playground

Next

---

## Page: https://mintlify.com/docs/integrations/sdks/speakeasy

You can integrate Speakeasy-generated code snippets from your SDKs directly into your Mintlify API reference documentation. SDK usage snippets are shown in the interactive playground of your Mintlify-powered documentation.

## Speakeasy SDK Repository Changes

In your Speakeasy SDK repos, add the following to the `targets` section of your `.speakeasy/workflow.yaml` file to ensure code samples are automatically produced alongside SDK generations.

.speakeasy/workflow.yaml

Code samples will be generated in the form of an OpenAPI overlay file that will be used in the Mintlify docs repository.

## Mintlify Docs Repository Changes

The workflow files produced will automatically bundle your source OpenAPI spec and Speakeasy code samples into a single output file, `openapi.yaml`. Mintlify will use this output file when constructing your API reference.

### Interactive CLI Set Up

Run the following commands to set up the `.speakeasy/workflow.yaml` and `.github/workflows/sdk_generation.yaml` files through the interactive Speakeasy CLI.

Set up your source spec. The source spec is the OpenAPI spec that code samples will be generated for, and it’s often the same specification used to power Mintlify docs.

Add the overlay created by Speakeasy to inject code snippets into your spec.

Provide a name and path for the OpenAPI spec. This will be the final spec used by Mintlify.

Finally, Add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify repo under `Settings > Secrets & Variables > Actions`. Find the Speakeasy API key in the Speakeasy dashboard under the **API Keys** tab.

## Manual Set Up

Alternatively, you can manually set up the following files in your Mintlify docs repo.

.speakeasy/workflow.yaml

.speakeasy/workflows/sdk\_generation.yaml

Finally, make sure you add your `SPEAKEASY_API_KEY` as a repository secret to your Minlify repo under `Settings > Secrets & Variables > Actions`. Find the Speakeasy API key in the Speakeasy dashboard under the **API Keys** tab.

Was this page helpful?

---

## Page: https://mintlify.com/docs/integrations/sdks/stainless

If you use Mintlify’s OpenAPI support for your API reference documentation, add the following to your Stainless config:

openapi.stainless.yml

Configure the OpenAPI setup in your Mintlify docs. To integrate Stainless, modify the GitHub Action that uploads your OpenAPI spec to Stainless so that it pushes the Stainless-enhanced OpenAPI spec into your docs repo like so:

This assumes the following secrets have been uploaded to your GitHub Actions Secrets:

*   `secrets.STAINLESS_API_KEY`: Your Stainless API key.
*   `secrets.API_TOKEN_GITHUB`: A GitHub Personal Access Token with permissions to push to your docs repo.

Was this page helpful?

---

## Page: https://mintlify.com/docs/integrations/support/overview

## Intercom

## Front

## 



Enabling Support Integrations

You can integrate widgets onto your docs for customer support. Add the `integrations` field into your `docs.json` file with your respective app ID.

      "integrations": {
        "intercom": "APP_ID",
        "frontchat": "CHAT_ID"
      }
    

If you’d like to request a customer support integration, please let us know in our community.

---

## Page: https://mintlify.com/docs/integrations/support/intercom

Add the following to your `docs.json` file to add an Intercom widget.

    "integrations": {
          "intercom": {
                "appId": "APP_ID"
          }
    }

---

## Page: https://mintlify.com/docs/integrations/support/front

Support

Add the following to your `docs.json` file to add a Front Chat widget.

    "integrations": {
        "frontchat": "CHAT_ID"
    }
    

Was this page helpful?

Previous

Privacy IntegrationsIntegrate with a data privacy platform

Next

---

## Page: https://mintlify.com/docs/integrations/privacy/overview

## Enabling Data Privacy Integrations

You can add data privacy platforms onto your docs. Add the `integrations` field into your `docs.json` file with your respective scripts.

If you’d like to request a data privacy platform integration, please let us know in our community.

## Cookie Consent and Disabling Telemetry

If you need to check if a user has already consented to cookies for GDPR compliance, you can specify a local storage key and value under `cookies`:

If these values are set, local storage will be checked to see if the user has consented to cookies. If they have not, telemetry will be disabled.

If you’d like to disable telemetry for all users, you can add the following to your `docs.json` file:

Was this page helpful?

---

## Page: https://mintlify.com/docs/integrations/privacy/osano

Add the following to your `docs.json` file to add the Osano cookie consent manager.

    "integrations": {
        "osano": "SOURCE"
    }
    

The `SOURCE` can be found as the `src` value in the code snippet generated by Osano. It always starts with `https://cmp.osano.com/`.

Code snippet from Osano

    <script src="https://cmp.osano.com/placeholder/placeholder/osano.js"/>

---

## Page: https://mintlify.com/docs/navigation/pages

## Pages

If you don’t want any hierarchy, you can just define pages within your `navigation` field.

Each entry of the `pages` array must be a path to a file that exists within your repo. Note you do not need to append `.mdx` to the file paths.

    {
      "navigation": {
        "pages": [
          "overview",
          "quickstart",
          "advanced/components",
          "advanced/integrations"
        ]
      }
    }
    

## Groups

Groups allow you to group your pages. Groups can also be nested within each other.

    {
      "navigation": {
        "groups": [
          {
            "group": "Getting Started",
            "pages": [
              "quickstart",
              {
                "group": "Editing",
                "icon": "pen-paintbrush",
                "pages": ["development", "web-editor"]
              }
            ]
          },
          {
            "group": "Writing Content",
            "pages": ["writing-content/page", "writing-content/text"]
          }
        ]
      }
    }

---

## Page: https://mintlify.com/docs/navigation/divisions

Tabs help distinguish between different topics or sections of your documentation.

docs.json

## Anchors

Anchors are another way to section your content. They show up on top of your side navigation.

The configuration is very similar to the tab configuration. We highly recommend that you set an `icon` field as well. Valid icon values include all named Font Awesome and Lucide icons.

docs.json

## Dropdowns

Dropdowns show up in the same place as anchors, but are consolidated into a single dropdown. We also recommend that you set an icon for each dropdown item (from Font Awesome or Lucide).

docs.json

## Nested Hierarchy

You can use any combination of anchors, tabs, and dropdowns - either one can be nested within each other interchangeably.

Was this page helpful?

---

## Page: https://mintlify.com/docs/api-playground/mdx/configuration

MDX

Generate docs pages for your API endpoints using MDX

Mintlify allows you to define your API endpoints using a combination of `docs.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.

1

Configure your API

In your `docs.json` file, define your base URL and auth method:

     "api": {
      "mdx": {
        "server": "https://mintlify.com/api", // string array for multiple base URLs
        "auth": {
          "method": "key",
          "name": "x-api-key" // options: bearer, basic, key.
        }
      }
    }
    

If you would not like to show an API playground, you don’t need to include auth types. Hide the playground with the following field:

    "api": {
      "playground": {
        "display": "none"
      }
    }
    

Find a full list of API configurations here.

2

Create your endpoint pages

Each API endpoint page should have a corresponding MDX file. At the top of each file, define:

    ---
    title: 'Create new user'
    api: 'POST https://api.mintlify.com/user'
    ---
    

You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:

    https://api.example.com/v1/endpoint/{userId}
    

If you have `server` configured in docs.json, you can use relative paths like `/v1/endpoint`.

You can also override the globally-defined display mode for the API playground per page by adding `playground` at the top of the MDX file:

    ---
    title: 'Create new user'
    api: 'POST https://api.mintlify.com/user'
    playground: 'none'
    

3

Add your endpoints to your docs

Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs here.

Was this page helpful?

---

## Page: https://mintlify.com/docs/advanced/subpath/route53-cloudfront

## Create Cloudfront Distribution

Navigate to Cloudfront inside the AWS console and click on `Create distribution`

For the Origin domain, input `[SUBDOMAIN].mintlify.dev` where `[SUBDOMAIN]` is the project’s unique subdomain. Click on `Use: [SUBDOMAIN].mintlify.dev`

For **Cache key and origin requests**, select `Caching Optimized`.

And for **Web Application Firewall (WAF)**, enable security protections

The remaining settings should be default. Click `Create distribution`.

## Add Default Origin

After creating the distribution, navigate to the `Origins` tab.

We want to find a staging URL that mirrors where the main domain (example.com). This is highly variant depending on how your landing page is hosted.

Once you have the staging URL, ours for instance is mintlify-landing-page.vercel.app, create a new Origin and add it as the **Origin domain**.

By this point, you should have two Origins - one with `[SUBDOMAIN].mintlify.app` and another with with staging URL.

## Set Behaviors

Behaviors in Cloudfront enables control over the subpath logic. At a high level, we’re looking to create the following logic.

*   **If a user lands on /docs**, go to `[SUBDOMAIN].mintlify.dev`
*   **If a user lands on any other page**, go the current landing page

We’re going to create three behaviors by clicking on the `Create behavior` button.

### `/docs/*`

The first behavior should have a **Path pattern** of `/docs/*` with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`)

For **Cache policy**, select `CachingOptimized` and create behavior.

### `/docs`

The second behavior should be the same as the first one but with a **Path pattern** of `/docs` and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.

### `Default (*)`

Lastly, we’re going to edit the `Default (*)` behavior.

We’re going to change the default behavior’s **Origin and origin groups** to the staging URL (in our case `mintlify-landing-page.vercel.app`).

Click on `Save changes`.

## Preview Distribution

You can now test if your distribution is set up properly by going to the `General` tab and visiting the **Distribution domain name** URL.

All pages should be directing to your main landing page, but if you append `/docs` to the URL, you should see it going to the Mintlify documentation instance.

## Connecting it with Route53

Now, we’re going to bring the functionality of the Cloudfront distribution into your primary domain.

Navigate to Route53 inside the AWS console, and click into the `Hosted zone` for your primary domain. Click on `Create record`

Toggle `Alias` and then **Route traffic to** the `Alias to CloudFront distribution` option.

Click `Create records`.

And voila! You should be able to have your documentation served at `/docs` for your primary domain.

---

## Page: https://mintlify.com/docs/advanced/subpath/vercel

## 



vercel.json Configuration

To host your documentation at a custom subpath using Vercel, you need to add the following configuration to your `vercel.json` file.

    {
      "rewrites": [
        {
          "source": "/docs",
          "destination": "https://[subdomain].mintlify.dev/docs"
        },
        {
          "source": "/docs/:match*",
          "destination": "https://[subdomain].mintlify.dev/docs/:match*"
        }
      ]
    }
    

For more information, you can also refer to Vercel’s offical guide on rewrites: Project Configuration: Rewrites

---

## Page: https://mintlify.com/docs/settings/navigation

The `navigation` property controls the hierarchy of your documentation.

## Pages

If you don’t want any hierarchy, you can just define pages within your `navigation` field.

Each entry of the `pages` array must be a path to a file that exists within your repo. Note you do not need to append `.mdx` to the file paths.

## Groups

Groups allow you to group your pages. Groups can also be nested within each other.

## Tabs

Tabs help distinguish between different topics or sections of your documentation.

docs.json

## Anchors

Anchors are another way to section your content.

The configuration is very similar to the tab configuration.

docs.json

## Nested Hierarchy

You can use both anchors and tabs together - either one can be nested within each other interchangeably.

## Global Links

If you want to use tabs or anchors solely for the purpose of listing external links use the `navigation.global` property.

### Hidden Pages

MDX files not included in `docs.json` will not show up in the sidebar but are accessible by linking directly to them.

Hidden pages are not indexed for search within your docs by default. If you would like to override this behavior, you can set the `seo.indexing` attribute in your `docs.json` to `navigable`.

## Navbar

### Links

Add links to the topbar with the `links` field in the `docs.json` file.

The `links` field supports the following fields: `label`, `href`.

### Primary Button

Customize the primary button in the topbar using the `primary` field.

The `primary` field supports the following fields: `label`, `href`, `type`. For more information on the options for these fields, see the docs.json schema.

#### GitHub

You can also configure the CTA button to link directly to your GitHub repository. Use the `primary` field with the `type` set to `github`.

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/authentication

Authentication offers full privacy for all of your documentation content by requiring users to authenticate before viewing any content, such as:

*   Documentation page content
*   Images used in documentation pages
*   Search results
*   AI chat interactions

You can authenticate users through handshake methods such as:

*   Password
*   JWT
*   OAuth
*   Mintlify dashboard

Authentication is similar to our Personalization offering, but with guaranteed privacy. In addition to securing your documentation content, all features that are available via Personalization are also available via Authentication.

Check out our docs for more info on choosing Authentication vs Personalization.

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/partial-authentication

Partial Authentication allows you to authenticate users to view only certain pages.

You can authenticate users through handshake methods such as:

*   Password
*   JWT
*   OAuth
*   Mintlify dashboard

Partial Authentication shares all the same features as Authentication, but with the ability to allow unauthenticated users to view certain pages.

By default, all pages are protected. You can specify which pages should be publicly accessible by adding the `public` property to the page’s frontmatter.

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/personalization

Personalization refers to a suite of features that allow you to customize your documentation experience based on some information about the user. There are three major features of Personalization:

*   **Customize MDX content** with a user’s information, such as their name, plan, or title.
    
*   **Prefill API keys** in the API Playground for streamlined use.
    
*   **Selectively show pages** in the navigation based on a user’s groups.
    

## How to Use

### Customizing MDX Content

When writing content, you can use the `user` variable to access the information you have sent to your docs. Here’s a simple example:

Hello, !

This feature becomes even more powerful when paired with custom data about the user. Here’s a real world example that allows us to give specific instructions on how to access the Personalization feature based on the customer’s existing plan:

Personalization is an enterprise feature.

### Prefilling API Keys

If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground.

### Showing/Hiding Pages

By default, every page is visible to every user. If you want to restrict which pages are visible to your users, you can add a `groups` field in your page metadata. When determining which pages to show to the user, Mintlify will check which groups the user belongs to. If the user is not in any of the groups listed in the page metadata, the page will not be shown.

Here’s a table that displays whether a page is shown for different combinations of `groups` in User and page metadata:

|  | `groups` not in User | `groups: []` in User | `groups: ['admin']` in User |
| --- | --- | --- | --- |
| `groups` not in metadata | ✅ | ✅ | ✅ |
| `groups: []` in metadata | ❌ | ❌ | ❌ |
| `groups: ['admin']` in metadata | ❌ | ❌ | ✅ |

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/authentication-vs-personalization

Mintlify offers both Authentication and Personalization. For the most part, Authentication is just Personalization + privacy. However, there are some key differences that are important to be aware of, from most important to least:

### Security Guarantees

Authentication is a fully-fledged private documentation solution. Every aspect of your docs, including page content, images, search results, and AI chat features, are completely inaccessible to unauthenticated users.

Personalization, on the other hand, offers no security guarantees for your documentation content. All page content, images, search results, and AI chat features can be accessed by the public. Even if you are using the hidden pages feature of Personalization, a motivated attacker would still be able to access the content of a hidden page.

### Handshake Methods

Due to the difference in security requirements for Authentication and Personalization, different handshake methods are available for each. Both methods offer a JWT and OAuth Handshake, although the setup steps are slightly different.

Authentication offers two additional Handshake methods:

*   **Password Handshake**, which protects your website with a single configurable global password.
    
*   **Mintlify Auth Handshake**, which will allow users to view your documentation only if they have access to your dashboard.
    

Personalization offers one additional Handshake method:

*   **Shared Session Handshake**, a super simple method which only requires setting up a single endpoint that returns data for already-authenticated users.

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/sending-data

Depending on your Handshake method, your API will respond with either a raw JSON object or a signed JWT. The shape of the data is the same for both:

expiresAt

number

The time at which this information should expire, in **seconds since epoch**. If the user loads the page and the current time is after this value, the stored data will be deleted.

groups

string\[\]

A list of groups that the user belongs to. This will determine which pages should be shown to this user. If any of these groups is listed in the `groups` field of a page’s metadata, that page will be shown.

content

object

A bag of values that can be accessed from within MDX content using the `user` variable. For example, if you have supplied `{ firstName: 'Ronan' }` as your content field, you can use the following in your MDX: `Good morning, {user.firstName}!`

apiPlaygroundInputs

object

User-specific values that will be prefilled in the API playground if supplied. For example, if each of my customers makes requests at a specific subdomain, I can send `{ server: { subdomain: 'foo' } }` as my `apiPlaygroundInputs` field, and this value will be prefilled on any API page with this `subdomain` value.

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/authentication-setup/password

If you don’t have strict security requirements, or you don’t want to manage a database of documentation readers, you can use a set of shared passwords to protect your docs.

## Implementation

1

2

## Example

I want to set up authentication for my docs hosted at `docs.foo.com`. I don’t want to have to keep track of who can and cannot access the docs. My main use case for authentication is to prevent competitors from snooping - password sharing is secure enough for my team.

To set up authentication with Mintlify, I go to my Mintlify dashboard and add at least one password. I then share that password, along with the private docs URL, with potential customers.

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/authentication-setup/jwt

If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL.

## Implementation

1

2

3

## Example

I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs to be completely separate from my dashboard (or I don’t have a dashboard at all).

To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow for my users. At the end of this login flow, once I have verified the identity of the user, I create a JWT containing the user’s custom data according to Mintlify’s specification. I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the form `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`, and redirect the user.

I then go to the dashboard settings and enter `https://foo.com/docs-login` for the Login URL field.

Here’s what the code might look like:

## Redirecting Unauthenticated Users

When an unauthenticated user tries to access a specific page, Mintlify preserves their intended destination through a redirect flow:

1.  The user attempts to visit a certain page (e.g., `/quickstart`)
    
2.  Mintlify redirects them to your login URL and adds the (relative) original destination as a `redirect` query parameter
    

Example:

*   Original request: `https://docs.foo.com/quickstart`
    
*   Redirect to login: `https://foo.com/docs-login?redirect=%2Fquickstart`
    

After successful authentication, you can include this same `redirect` parameter in your JWT callback URL to send users to their intended destination: `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/authentication-setup/oauth

If you have an existing OAuth server, you can integrate with Mintlify for a seamless login experience.

## Implementation

1

2

3

## Example

I have an existing OAuth server that supports the Authorization Code flow. I want to set up authentication for my docs hosted at `foo.com/docs`.

To set up authentication with Mintlify, I create an endpoint `api.foo.com/docs/user-info` which requires an OAuth access token with the `docs-user-info` scope, and responds with the user’s custom data according to Mintlify’s specification.

I then go to the dashboard settings, navigate to the Authentication settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:

*   **Authorization URL**: `https://auth.foo.com/authorization`
*   **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
*   **Scopes**: `['docs-user-info']`
*   **Token URL**: `https://auth.foo.com/exchange`
*   **Info API URL**: `https://api.foo.com/docs/user-info`

Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings.

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/authentication-setup/mintlify

You can use Mintlify to authenticate and manage access to your documentation. Anyone that can access your dashboard will automatically be able to see your documentation.

This handshake method also enables private preview deployments, so that only Mintlify authenticated users will be able to access your preview deployments.

### Example

I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs to be internal, and the people that will be viewing my docs are the same people that contribute to my docs.

To set up authentication with Mintlify, I can go to my dashboard settings and enable Authentication with the Mintlify Auth Handshake.

I can then ensure that anyone that should be able to read the docs has been added as a user in my dashboard settings.

## Implementation

1

2

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/authentication-setup/choosing-a-handshake

Before your users can access personalized content, they must be authenticated. Mintlify supports four Authentication Handshake methods:

1.  **Password**: Configure a set of global passwords for your documentation site.
2.  **JWT**: Use your own login flow to authenticate your users via a JWT in the URL.
3.  **OAuth 2.0**: Integrate with your OAuth server to enable user login via the standard Authorization Code flow.
4.  **Mintlify Dashboard**: Allow all of your dashboard users to access your docs, zero configuration required.

## Prerequisites

*   Your security requirements allow for password sharing between documentation readers.

## Pros & Cons

Pros:

*   Super simple setup
*   No configuration required for adding new users - just share the password

Cons:

*   Difficult to revoke access to your docs without resetting the password
*   Lose personalization features, as there is no way to differentiate users with the same password

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/personalization-setup/oauth

If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience.

## Implementation

1

2

3

## Example

I have an existing OAuth server that supports the PKCE flow. I want to set up authentication for my docs hosted at `foo.com/docs`.

To set up authentication with Mintlify, I create an endpoint `api.foo.com/docs/user-info` which requires an OAuth access token with the `docs-user-info` scope, and responds with the user’s custom data according to Mintlify’s specification.

I then go to the dashboard settings, navigate to the Personalization settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:

*   **Authorization URL**: `https://auth.foo.com/authorization`
*   **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
*   **Scopes**: `['docs-user-info']`
*   **Token URL**: `https://auth.foo.com/exchange`
*   **Info API URL**: `https://api.foo.com/docs/user-info`

Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings.

Was this page helpful?

---

## Page: https://mintlify.com/docs/advanced/dashboard/sso

Use single sign-on to your dashboard via SAML and OIDC. If you use Okta or Google Workspace, we have provider-specific documentation for setting up SSO, but if you use another provider, please contact us!

## Okta

1

2

Configure integration

Enter the following:

*   Single sign-on URL (provided by Mintlify)
*   Audience URI (provided by Mintlify)
*   Name ID Format: `EmailAddress`
*   Attribute Statements:
    
    | Name | Name format | Value |
    | --- | --- | --- |
    | `firstName` | Basic | `user.firstName` |
    | `lastName` | Basic | `user.lastName` |
    

3

## Google Workspace

1

2

3

Configure integration

On the Service provider details page, enter the following:

*   ACS URL (provided by Mintlify)
*   Entity ID (provided by Mintlify)
*   Name ID format: `EMAIL`
*   Name ID: `Basic Information > Primary email`

On the next page, enter the following attribute statements:

| Google Directory Attribute | App Attribute |
| --- | --- |
| `First name` | `firstName` |
| `Last name` | `lastName` |

Once this step is complete and users are assigned to the application, let our team know and we’ll enable SSO for your account!

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/personalization-setup/jwt

If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to send user info to your docs via a JWT in the URL.

## Implementation

1

2

3

## Example

I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs to be completely separate from my dashboard (or I don’t have a dashboard at all).

To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow for my users. At the end of this login flow, once I have verified the identity of the user, I create a JWT containing the user’s custom data according to Mintlify’s specification. I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the form `https://docs.foo.com#{SIGNED_JWT}`, and redirect the user.

I then go to the dashboard settings and enter `https://foo.com/docs-login` for the Login URL field.

Here’s what the code might look like:

## Preserving Anchors

Post-login, if you’d like to redirect to a specific anchor on the page, you can use the following format to create the redirect URL: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`.

Example:

*   Original: `https://docs.foo.com/quickstart#step-one`
*   Redirect: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one`

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/personalization-setup/choosing-a-handshake

Before your users can access personalized content, they must be authenticated. Mintlify supports three Personalization Handshake methods:

1.  **Shared Session**: Utilize the same session token used by your dashboard to authenticate users.
2.  **JWT**: Use your own login flow to send user info to your docs via a JWT in the URL.
3.  **OAuth 2.0**: Integrate with your OAuth server to enable user login via the PKCE flow.

## Prerequisites

*   You have a dashboard or other user portal hosted at your domain.
*   Your users’ session credentials are stored as cookies.
*   You can create a new API endpoint at the same origin or a subdomain of your dashboard.
    *   If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com`
    *   If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com`
*   Your docs are hosted at the same domain as your dashboard.
    *   If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`
    *   If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`

## Pros & Cons

Pros:

*   Users that are logged into your dashboard are automatically logged into your docs
*   Your users’ sessions are persistent, meaning you can refresh data without requiring additional login
*   Minimal setup required

Cons:

*   Your docs will make a request to your backend, which may be undesirable
*   You must have a dashboard that uses session authentication
*   CORS configuration is usually required

Was this page helpful?

---

## Page: https://mintlify.com/docs/settings/authentication-personalization/personalization-setup/shared-session

This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience.

## Implementation

1

2

## Examples

### Dashboard at subdomain, docs at subdomain

I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `docs.foo.com`.

To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://docs.foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**.

I then go to the dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field.

### Dashboard at subdomain, docs at root

I have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. My dashboard API routes are hosted at `dash.foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`.

To set up authentication with Mintlify, I create another dashboard endpoint `dash.foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification. I then add `https://foo.com` to the `Access-Control-Allow-Origin` allow-list **for this route only**, and ensure my `Access-Control-Allow-Credentials` configuration is set to `true` **for this route only**.

I then go to the dashboard settings and enter `https://dash.foo.com/api/docs/user-info` for the API URL field.

### Dashboard at root, docs at root

I have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. My dashboard API routes are hosted at `foo.com/api`. I want to set up authentication for my docs hosted at `foo.com/docs`.

To set up authentication with Mintlify, I create another dashboard endpoint `foo.com/api/docs/user-info` which identifies the user using session auth, and responds with their custom data according to Mintlify’s specification.

I then go to the dashboard settings and enter `https://foo.com/api/docs/user-info` for the API URL field.

---

## Page: https://mintlify.com/docs/advanced/dashboard/permissions

The team member who created your initial docs will have update access to your docs, as long as they push to your documentation repo with the same GitHub account that was used while signing up for Mintlify.

If another editor attempts to update the docs while on the free plan, you will see a warning in your git commit check.

In the details of the git check warning, you’ll find the link to upgrade your plan. You can also upgrade your plan on the dashboard to enable unlimited editors to update your docs. Once you upgrade your plan, trigger a manual update or push another change to deploy your updates.

Learn more about our pricing here.

Was this page helpful?

---

## Page: https://mintlify.com/docs/advanced/mcp/quickstart

## Introduction

The MCP Generator is a CLI tool that generates an MCP server based on your company’s documentation & OpenAPI specification if available. It takes in your documentation and a OpenAPI spec and outputs an MCP server that can be used with any MCP client. The MCP Generator is delivered via npm package and generates an MCP server that can be used with any MCP client.

Mintlify enables you to create an MCP server that allows AI tools to interact with your docs in these key scenarios:

1.  **Docs Q&A**, similar to our AI Chat. This is automatically enabled for your docs, no setup required.
    
2.  **Real-time API querying**, if you have an OpenAPI spec, head to the `Mintlify Dashboard > Products > MCP Server` and hit the toggle to enable your OpenAPI spec.
    

## Install the MCP server

## Example installation with the Mintlify MCP server

To use the Mintlify MCP server you will need an API key from your Mintlify account. If you don’t have one, navigate to `Settings > API Keys > Chat API Key` and create a new key.

## Start the MCP server locally

1

2

3

## Use your server with Claude

Once you have the Claude Desktop App installed, follow these steps:

1

2

3

Was this page helpful?

---

## Page: https://mintlify.com/docs/advanced/mcp/generate

## Get started

Run `npm i @mintlify/mcp` to install the `@mintlify/mcp` CLI.

In the dashboard go to `MCP Server`, on this page toggle to see your unique installation command. This is the command to install your MCP Server with the `@mintlify/mcp` CLI.

Make sure to toggle OpenAPI access to allow the MCP server to access **all** endpoints in your OpenAPI spec.

## Start the MCP server locally

1

Install the server through the CLI

Run the following command to install the server:

    npx @mintlify/mcp add [your subdomain]
    

2

Add the authentication token if applicable

If your API requires an authentication token, tell your end-customer to get it and apply it when given this response: `> What is the Authorization (basic token)?` Otherwise, you can skip this step.

3

Start your MCP server

You can now run: `bash npm --prefix ~/.mcp/[your subdomain] start`

---

## Page: https://mintlify.com/docs/advanced/rest-api/overview#authentication

## Trigger Updates

You can leverage the REST API to programmatically trigger an update when desired.

## Authentication

You can generate an API key through the dashboard. The API key is associated with the entire org and can be used across multiple deployments.

## Admin API key

The Admin API key is used for the majority of the API. It is used to trigger updates via the Update endpoint.

## Chat API key

The Chat API allows you to embed the AI chat experience grounded in your docs and continually kept up to date into any application of your choosing.

Responses include citations so you can point your users to the right places they need to get help.

Now that you have an API key, check out our example for how to use the API for AI chat. You can also see a deployed version of this example at chat.mintlify.com.

Was this page helpful?

---

## Page: https://mintlify.com/docs/advanced/rest-api/update/trigger

##### Advanced

*   Custom Subdirectory
    
*   Auth & Personalization
    
*   Dashboard Access
    
*   Model Context Protocol
    
*   REST API
    
    *   Overview
        
    *   Updates
        
        *   POST
            
            Trigger an update
            
        *   GET
            
            Get the status of an update
            
    *   Chat API
        

*   Community
    
*   Get Started
    

Updates

Trigger an update after updating your OpenAPI document by calling this endpoint in a CI check.

POST

/

project

/

update

/

{projectId}

    curl --request POST \
      --url https://api.mintlify.com/v1/project/update/{projectId} \
      --header 'Authorization: Bearer <token>'

    {
      "statusId": "<string>"
    }

Authorization

string

header

required

Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.

projectId

string

required

The ID of the project to trigger an update on. Can be retrieved from your dashboard.

#### Response

202 - application/json

A successful response

statusId

string

The status id of the triggered updated.

Was this page helpful?

    curl --request POST \
      --url https://api.mintlify.com/v1/project/update/{projectId} \
      --header 'Authorization: Bearer <token>'

    {
      "statusId": "<string>"
    }

---

## Page: https://mintlify.com/docs/advanced/rest-api/update/status

GET

Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.

statusId

string

required

The status ID of a triggered update.

#### Response

200 - application/json

A successful response

\_id

string

The status id of the triggered updated.

projectId

string

The documentation project ID.

createdAt

string

An ISODate with the specified datetime in UTC

endedAt

string

An ISODate with the specified datetime in UTC

status

enum<string>

The status of the update.

Available options:

`queued`,

`in_progress`,

`success`,

`failure`

summary

string

Summary of the status of the update

logs

string\[\]

An array of logs.

subdomain

string

The subdomain of the docs being updated.

screenshot

string

A screenshot of the docs.

screenshotLight

string

A screenshot of the docs.

screenshotDark

string

A screenshot of the docs in dark mode.

author

string

The author of the update.

commit

object

The commit details

commit.sha

string

The SHA of the commit.

commit.ref

string

The ref of the commit.

commit.message

string

The commit message.

commit.filesChanged

object

Details on the changed files.

commit.filesChanged.added

string\[\]

New files added.

commit.filesChanged.modified

string\[\]

Existing files that were modified.

commit.filesChanged.removed

string\[\]

Files that were removed.

source

enum<string>

The source of the update trigger.

Available options:

`internal`,

`github-app-installation`,

`api`,

`github`,

`dashboard`

Was this page helpful?

---

## Page: https://mintlify.com/docs/advanced/rest-api/chat/create-topic

##### Advanced

*   Custom Subdirectory
    
*   Auth & Personalization
    
*   Dashboard Access
    
*   Model Context Protocol
    
*   REST API
    
    *   Overview
        
    *   Updates
        
    *   Chat API
        
        *   POST
            
            Create a chat topic
            
        *   POST
            
            Generate a message completion
            

*   Community
    
*   Get Started
    

Chat API

Creates a topic to manage message history for a given AI chat conversation.

POST

/

chat

/

topic

    curl --request POST \
      --url https://api-dsc.mintlify.com/v1/chat/topic \
      --header 'Authorization: Bearer <token>'

    {
      "topicId": "<string>"
    }

Authorization

string

header

required

Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.

#### Response

200 - application/json

Topic created successfully

topicId

string

The id of the created topic.

Was this page helpful?

    curl --request POST \
      --url https://api-dsc.mintlify.com/v1/chat/topic \
      --header 'Authorization: Bearer <token>'

    {
      "topicId": "<string>"
    }

---

## Page: https://mintlify.com/docs/advanced/rest-api/chat/generate-message

POST

Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.

#### Body

application/json

topicId

string

required

The topic ID to associate this message with

message

string

required

The user message to generate a completion for

#### Response

200 - text/plain

Topic created successfully

A text stream in the form `<response>||[chunks]`. The chunks are parts of your docs that most closely matched the user query. Each has the following format:

    { 
    	id: string;
    	link: string;
    	chunk_html: string;
    	metadata: {
    		title?: string
    	}
    } 
    

The links are relative links with your docs URL intended as the host. To get an absolute link to your docs, you can use the `X-Mintlify-Base-Url` header as the host and construct a fully-qualified URL.

Was this page helpful?