# Editor Permissions Source: https://mintlify.mintlify.review/advanced/dashboard/permissions Allow more members of your team to update your docs 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](https://dashboard.mintlify.com) 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](https://mintlify.com/pricing). # Single Sign-On (SSO) Source: https://mintlify.mintlify.review/advanced/dashboard/sso Customize how your team can login to your admin dashboard 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! SSO functionality is available on our Enterprise plan. [Contact us](https://mintlify.com/enterprise) to learn more! ## Okta Under `Applications`, click to create a new app integration using SAML 2.0. 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` | Once the application is set up, navigate to the sign-on tab and send us the metadata URL. We'll enable the connection from our side using this information. Under `Applications`, click to create a new app integration using OIDC. You should choose the `Web Application` application type. Select the authorization code grant type and enter the Redirect URI provided by Mintlify. Once the application is set up, navigate to the General tab and locate the client ID & client secret. Please securely provide us with these, along with your Okta instance URL (e.g. `.okta.com`). You can send these via a service like 1Password or SendSafely. ## Google Workspace Under `Web and mobile apps`, select `Add custom SAML app` from the `Add app` dropdown. ![](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/gsuite-add-custom-saml-app.png) Copy the provided SSO URL, Entity ID, and x509 certificate and send it to the Mintlify team. ![](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/gsuite-saml-metadata.png) 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` ![](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/gsuite-sp-details.png) 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! # Create a chat topic Source: https://mintlify.mintlify.review/advanced/rest-api/chat/create-topic POST /chat/topic Creates a topic to manage message history for a given AI chat conversation. # Generate a message completion Source: https://mintlify.mintlify.review/advanced/rest-api/chat/generate-message POST /chat/message Generate a completion in response to a user query # Overview Source: https://mintlify.mintlify.review/advanced/rest-api/overview ## Trigger Updates You can leverage the REST API to programmatically trigger an update when desired. While the primary use-case will be to trigger updates, we will be adding more and more functionality to the API overtime. Let us know what else you want to see in [our community](https://mintlify.com/community)! ## Authentication You can generate an API key through [the dashboard](https://dashboard.mintlify.com/settings/organization/api-keys). 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](/advanced/rest-api/update/trigger). ## 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. The Chat API token is a public token that can be referenced in your frontend code whereas the API key is a server-side token that should be kept secret. Now that you have an API key, check out our [example](https://github.com/mintlify/discovery-api-example) for how to use the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com). # Get the status of an update Source: https://mintlify.mintlify.review/advanced/rest-api/update/status GET /project/update-status/{statusId} # Trigger an update Source: https://mintlify.mintlify.review/advanced/rest-api/update/trigger POST /project/update/{projectId} Trigger an update after updating your OpenAPI document by calling this endpoint in a CI check. # Cloudflare Source: https://mintlify.mintlify.review/advanced/subpath/cloudflare Host documentation at a /docs subpath using Cloudflare Workers ## 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. Create a Cloudflare worker Keep in mind: If your DNS provider is Cloudflare you should not use proxying for the CNAME record ### 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. Cloudflare worker custom domain If you have trouble setting up a custom subdirectory, [contact our support team](mailto:sales@mintlify.com) 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. Cloudflare edit code Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and `CUSTOM_URL` with your website's base URL. ```javascript addEventListener("fetch", (event) => { event.respondWith(handleRequest(event.request)); }); async function handleRequest(request) { try { const urlObject = new URL(request.url); // If the request is to the docs subdirectory if (/^\/docs/.test(urlObject.pathname)) { // Then Proxy to Mintlify const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; const CUSTOM_URL = "[YOUR_DOMAIN]"; let url = new URL(request.url); url.hostname = DOCS_URL; let proxyRequest = new Request(url, request); proxyRequest.headers.set("Host", DOCS_URL); proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL); proxyRequest.headers.set("X-Forwarded-Proto", "https"); return await fetch(proxyRequest); } } catch (error) { // if no action found, play the regular request return await fetch(request); } } ``` Click on `Deploy` and wait for the changes to propagate (it can take up to a few hours). # AWS Route 53 and Cloudfront Source: https://mintlify.mintlify.review/advanced/subpath/route53-cloudfront Host documentation at a /docs subdirectory using AWS services ## Create Cloudfront Distribution Navigate to [Cloudfront](https://aws.amazon.com/cloudfront) inside the AWS console and click on `Create distribution` ![Cloudfront Create Distribution](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/create-distribution.png) For the Origin domain, input `[SUBDOMAIN].mintlify.dev` where `[SUBDOMAIN]` is the project's unique subdomain. Click on `Use: [SUBDOMAIN].mintlify.dev` ![Cloudfront Origin name](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/origin-name.png) For **Cache key and origin requests**, select `Caching Optimized`. ![Cloudfront Caching policy](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/caching-policy.png) And for **Web Application Firewall (WAF)**, enable security protections ![Cloudfront Caching policy](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/enable-security-protections.png) The remaining settings should be default. Click `Create distribution`. ## Add Default Origin After creating the distribution, navigate to the `Origins` tab. ![Cloudfront Origins](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/origins.png) We want to find a staging URL that mirrors where the main domain (example.com). This is highly variant depending on how your landing page is hosted. For instance, if your landing page is hosted on Webflow, you can use the Webflow's staging URL. It would look like `.webflow.io`. If you use Vercel, you use the `.vercel.app` domain available for every project. If you're unsure on how to get a staging URL for your landing page, [contact support](mailto:support@mintlify.com) and we'd be happy to help Once you have the staging URL, ours for instance is [mintlify-landing-page.vercel.app](https://mintlify-landing-page.vercel.app), create a new Origin and add it as the **Origin domain**. ![Cloudfront Default Origins](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/default-origin.png) 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`) ![Cloudfront Behavior 1](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/behavior-1.png) 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. ![Cloudfront Behavior 2](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/behavior-2.png) ### `Default (*)` Lastly, we're going to edit the `Default (*)` behavior. ![Cloudfront Behavior Default 1](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/default-behavior-1.png) 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`). ![Cloudfront Behavior Default 2](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/default-behavior-2.png) 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. ![Cloudfront Preview distribution](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/preview-distribution.png) 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. For this section, you can also refer to AWS's official guide on [Configuring Amazon Route 53 to route traffic to a CloudFront distribution](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-cloudfront-distribution.html#routing-to-cloudfront-distribution-config) Navigate to [Route53](https://aws.amazon.com/route53) inside the AWS console, and click into the `Hosted zone` for your primary domain. Click on `Create record` ![Route 53 create record](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/route53-create-record.png) Toggle `Alias` and then **Route traffic to** the `Alias to CloudFront distribution` option. ![Route 53 create record alias](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/cloudfront/create-record-alias.png) Click `Create records`. You may need to remove the existing A record if one currently exists. And voila! You should be able to have your documentation served at `/docs` for your primary domain. # Vercel Source: https://mintlify.mintlify.review/advanced/subpath/vercel Host documentation at a /docs subpath using 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. ```json { "rewrites": [ { "source": "/docs", "destination": "https://[subdomain].mintlify.dev/docs" }, { "source": "/docs/:match*", "destination": "https://[subdomain].mintlify.dev/docs/:match*" } ] } ``` For more information, you can also refer to Vercel's offical guide on rewrites: [Project Configuration: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) # Authentication Source: https://mintlify.mintlify.review/api-playground/mdx/authentication You can set authentication parameters to let users use their real API keys. ## 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 ```json docs.json "api": { "mdx": { "auth": { "method": "bearer" } } } ``` ```md Page Metadata --- title: "Your page title" authMethod: "bearer" --- ``` ### Basic Authentication ```json docs.json "api": { "mdx": { "auth": { "method": "basic" } } } ``` ```md Page Metadata --- title: "Your page title" authMethod: "basic" --- ``` ### API Key ```json docs.json "api": { "mdx": { "auth": { "method": "key", "name": "x-api-key" } } } ``` ```md Page Metadata --- title: "Your page title" authMethod: "key" --- ``` ### None The "none" authentication method is useful to disable authentication on a specific endpoint after setting a default in docs.json. ```md Page Metadata --- title: "Your page title" authMethod: "none" --- ``` # MDX Setup Source: https://mintlify.mintlify.review/api-playground/mdx/configuration 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 `` component. From the defined endpoints, we generate an API playground, request examples, and response examples. In your `docs.json` file, define your base URL and auth method: ```json "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: ```json "api": { "playground": { "display": "none" } } ``` Find a full list of API configurations [here](/settings/global#param-api). Each API endpoint page should have a corresponding MDX file. At the top of each file, define: ```md --- 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 `{}`: ```bash https://api.example.com/v1/endpoint/{userId} ``` If you have `server` configured in [docs.json](/settings/global), 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: ```md --- title: 'Create new user' api: 'POST https://api.mintlify.com/user' playground: 'none' ``` 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](/settings/navigation). # Advanced Features Source: https://mintlify.mintlify.review/api-playground/openapi/advanced-features Support for advanced OpenAPI features 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](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/), but essentially: * `oneOf` functions like an "exclusive-or" operator * `anyOf` functions like an "or" operator * `allOf` functions like an "and" operator The `oneOf` and `anyOf` keywords are treated the same. We have found that, when people use `oneOf`, they often *mean* `anyOf` - and there is often no meaningful difference to the user. The `not` keyword is not currently supported. ### 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`](https://swagger.io/docs/specification/components/). ```yaml org_with_users: allOf: - $ref: '#/components/schemas/Org' - type: object properties: users: type: array description: An array containing all users in the organization ... components: schemas: Org: type: object properties: id: type: string description: The ID of the organization ``` The ID of the organization An array containing all users in the organization ### Providing options with `oneOf` and `anyOf` When you use `oneOf` or `anyOf`, 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: ```yaml delivery_address: oneOf: - title: StreetAddress type: object properties: address_line_1: type: string description: The street address of the recipient ... - title: POBox type: object properties: box_number: type: string description: The number of the PO Box ... ```
The street address of the residence The number of the PO Box
## `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: The language of the code sample. The label for the sample. This is useful when providing multiple examples for a single endpoint. The source code of the sample. Here's an example of some code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK. ```yaml paths: /plants: get: ... x-codeSamples: - lang: bash label: List all unwatered plants source: | planter list -u - lang: javascript label: List all unwatered plants source: | const planter = require('planter'); planter.list({ unwatered: true }); - lang: bash label: List all potted plants source: | planter list -p - lang: javascript label: List all potted plants source: | const planter = require('planter'); planter.list({ potted: true }); ``` # OpenAPI Setup Source: https://mintlify.mintlify.review/api-playground/openapi/setup Reference OpenAPI endpoints in your docs pages ## 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](https://swagger.io/specification/). Your document must follow OpenAPI specification 3.0+. To validate your OpenAPI spec, use our [CLI](https://www.npmjs.com/package/mintlify) and run this command:
`mintlify openapi-check `
## 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:** ```json {5} "navigation": { "tabs": [ { "tab": "API Reference", "openapi": "https://petstore3.swagger.io/api/v3/openapi.json" } ] } ``` ![](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/autogeneration-with-tabs.png) **Example with Groups:** ```json {8-11} "navigation": { "tabs": [ { "tab": "API Reference", "groups": [ { "group": "Endpoints", "openapi": { "source": "/path/to/openapi-1.json", "directory": "api-reference" } } ] } ] } ``` 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](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx) from [MindsDB](https://docs.mindsdb.com/rest/databases/create-databases). ![](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/mindsdb.png) ### 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. ```md Example --- title: "Get users" openapi: "/path/to/openapi-1.json GET /users" --- ``` ```md Format --- title: "title of the page" openapi: openapi-file-path method path --- ```
The method and path must match the method and path specified in the OpenAPI document exactly. If the endpoint doesn't exist in the OpenAPI file, the page will be empty. ### 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](https://www.npmjs.com/package/@mintlify/scraping) autogenerates MDX files for your OpenAPI endpoints. Use the relative path to the OpenAPI document in your codebase. ```bash npx @mintlify/scraping@latest openapi-file ``` 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. ```bash npx @mintlify/scraping@latest openapi-file -o api-reference ``` Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping). The scraper will output an array of [Navigation entries](/settings/global#structure) 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. If your OpenAPI document is invalid, the files will not autogenerate. ## 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: ```md Example --- openapi-schema: OrderItem --- ``` ```md Format --- openapi-schema: "schema-key" --- ``` # Writing OpenAPI Source: https://mintlify.mintlify.review/api-playground/openapi/writing-openapi Use OpenAPI features to enhance your documentation ## Describing your API There are many great tools online for learning about and constructing OpenAPI documents. Here are our favorites: * [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/about/) for familiarizing yourself with the OpenAPI syntax * [OpenAPI v3.1.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) for all the details about the newest OpenAPI specification * [Swagger & OpenAPI Validator](https://apitools.dev/swagger-parser/online/) for debugging your OpenAPI document * [Swagger's Editor](https://editor.swagger.io/) for seeing examples in action Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1. For more information on the differences between v3.0 and v3.1, check out [OpenAPI's blog post](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0). ## 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](https://swagger.io/docs/specification/api-host-and-base-path/). 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](https://swagger.io/docs/specification/api-host-and-base-path/#:~:text=%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%20%2D%20southeastasia-,Overriding%20Servers,-The%20global%20servers) 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](https://swagger.io/docs/specification/authentication/basic-authentication/), [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/), and [API Keys](https://swagger.io/docs/specification/authentication/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](https://swagger.io/docs/specification/authentication/) 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](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for a given operation. # Playground Source: https://mintlify.mintlify.review/api-playground/overview GET /plants/{id} Enable users to interact with your API The API playground is an interactive environment to make requests and preview an API endpoint. Autogenerating API pages with OpenAPI will automatically generate API playground. Read more about using OpenAPI [here](/api-playground/openapi). # Troubleshooting Source: https://mintlify.mintlify.review/api-playground/troubleshooting Common issues with API References 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](https://apitools.dev/swagger-parser/online/) 2. Switch to the "Validate text" tab 3. Paste in your OpenAPI document 4. Click "Validate it!" If the text box that appears below has a green border, your document has passed validation. This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document passes validation here, there's a great chance the problem is elsewhere. Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification, you could encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) (under Edit > Convert to OpenAPI 3): 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: ```md get-user.mdx --- openapi: "GET /users/{id}/" --- ``` ```yaml 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: ```md 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.disableProxy` setting in the `docs.json`, as described [here](/settings/global#api-configurations). This will likely require you to configure CORS on your server, as these requests will now come directly from your users' browsers. # Product Updates Source: https://mintlify.mintlify.review/changelog/overview New updates and improvements ## New Configuration Schema `docs.json` We've introduced a new `docs.json` schema as a replacement for `mint.json`, to support better multi-level versioning, easier visual comprehension, and more consistent terminology. For more information on what's changed, [check out our blog](https://mintlify.com/blog/refactoring-mint-json-into-docs-json). Upgrade from `mint.json` to `docs.json` with the following steps: 1. Make sure your CLI is the latest version ``` npm i mintlify@latest -g ``` 2. In your docs repository, run ``` mintlify upgrade ``` 3. Delete your old mint.json file and push your changes ## CI Checks Automatically lint your docs to find broken links, discover spelling and grammar issues, or enforce writing styles with your own Vale config. Learn more in our [docs](settings/ci). ## .md support for LLMs All documentation pages are now automatically available as plain Markdown files—just append `.md` to the URL. This makes it easier for LLMs to ingest individual pages from your documentation. ## More Themes New pre-built themes to modify the look & feel of your docs. Configure via your [docs.json file](/settings/global). Now available: * Maple * Palm ## AI Assistant Improvements * New UI with dedicated chat page & pre-filled prompts * Stability improvements, e.g. bug fixes of editing the wrong file or no files at all * More robust knowledge for adding & editing components * Improved mint.json file editing ## Partial Authentication Customize access to any page or section of content depending on user permissions. Supports connecting with your own authentication system. ## Revamped API Playground We’ve overhauled the design and performance of the [API Playground](/api-playground/). Updates include: * Easier detail expansion for an overview of a field * More intuitive nested design, e.g. adding or deleting items * Faster response times ## Quality Improvements * Support for requiring authentication to access preview deployments ## Authentication Authentication screenshot Make docs private by setting up authentication via JWT, OAuth, or a universal password. With this privacy, you can create an internal knowledge base or prevent competitors from seeing your docs. ## AI Assistant AI Assistant You can now ask AI to make changes to your docs, with the context of all existing documentation. Type in a prompt and the assistant will propose changes by generating a pull request. ## GitLab Integration Upgrade We've improved our support for syncing with GitLab, such as enabling automated updates and preview deployments. Check out our [docs on GitLab](/settings/gitlab) to get started. ## Web Editor Web Editor We've revamped our web editor so that you can now update docs with a fully WYSIWYG experience, while syncing with markdown. Check out our [docs on getting started with Web Editor](/web-editor). ## /llms.txt support llms.txt support All docs instances are now automatically hosted at /llms.txt and /llms-full.txt so that LLMs can easily ingest your documentation. For more information, read the [docs on the new llms.txt standard.](https://llmstxt.org) ## Localization You can now localize your docs which operates similarly to versioning. Add a `locale` to a version and fixed content in Mintlify like "Was this page helpful?" will also match the locale. ### Quality Improvements * Return chat & search results based on the current version that the user is reading * Authenticate users with OAuth, in addition to JWT or Shared Session tokens. ## Changelogs Launched a new [Update component](/content/components/update) to make it easier to display and report updates (like this one) to your users. Changelog ## Code Line Highlighting You can now highlight lines of code in your docs to emphasize and bring attention to important parts by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas. ```javascript Line Highlighting Example {1,3-5} const greeting = "Hello, World!"; function sayHello() { console.log(greeting); } sayHello(); ``` ````md ```javascript Line Highlighting Example {1,3-5} const greeting = "Hello, World!"; function sayHello() { console.log(greeting); } sayHello(); ``` ```` ## Light mode code blocks Code blocks now have a light mode variant which can be enabled by adding the following to your `mint.json`: ```json "codeBlock": { "mode": "auto" } ``` ## Advanced Footer Advanced Footer You can now add more links to the standard footer. This upgrade provides more consistency between landing pages and docs, or greater customization if you want to spotlight specific pages like socials or status logs. ## Filter search based on the current user When personalization is enabled, search results are now filtered based on the current logged in user so that they only see the relevant content. ## Custom Prompts for AI Chat You can now customize the prompts for the AI chat. Please reach out to [support](mailto:sales@mintlify.com) if you'd like to customize the prompts. ## Dashboard Improvements * Added ability to change custom domain to be /docs directly through dashboard settings. * Consolidated the login and signup pages to decrease friction and confusion. * Implemented the discovery login flow so that users that are members of multiple organizations can now switch between them. * Added login with Google OAuth * Added ability to add new deployment through dashboard settings. ## Bug Fixes * Can now use leading slashes in navigation. * Can now edit CSS & JS files in the web editor. * Fixed `suggestEdit` not showing up even when enabled. * Fixed keyboard navigation for Search and Chat such that you can now use the up and down arrow keys to navigate the results. * Don't allow search engines to crawl user-auth protected pages. * Revalidate the cache when an org is deleted. * We now use the Scalar OpenAPI parser to parse OpenAPI definitions which improves the performance, fixes parsing issues, and surfaces better error messages. * Top-level descriptions are now supported in API reference pages autogenerated from OpenAPI definitions. * Add in-line-style support for icons * Fixed the pop-in of custom CSS in docs. * Properly show in-line code styling in conjunction with links. * Maintain scroll position when you click the back button in a browser. ## Custom Fonts Custom Fonts Personalize the font of your docs to your own font hosted on a CDN or by choosing from Google fonts to match your docs with your brand. ## Images in Card components Add an `img` property to a card to display an image on the top of the card. Learn more about it [here](/content/components/cards#image-card). ## Update Speed Performances Performance Improvements For large projects (\~3,000 files), the download step for docs updates is now \~440x faster - a 99.8% time reduction. Across the board, file downloads during updates are now \~5.5x faster - an 81.8% time reduction. ## SEO improvements SEO Improvements We've fixed both the mobile and desktop layout of our docs so that they are more SEO-friendly - including adding proper aria tags to navbar and toggle elements. ## Dashboard Improvements * App router migration in the dashboard. * Search analytics are now available in the dashboard. * Delete an org functionality has been added to the dashboard. * Shipped GitLab connection UI. * Fix incorrect analytics data. * Add-on's can now be directly purchased through the dashboard. ## Bug Fixes * Fixed a bug where the top bar would not stretch to the width of the screen when it's in custom mode and the sidebar layout is `sidenav`. * Fix relative positioning of the AI widget. ## More * **Troubleshooting for API pages**: API pages could be complicated so we listed common issues to help you sort them out quickly — [Read the docs](/api-playground/troubleshooting) ## OpenAPI Reference Pages * Endpoints defined by OpenAPI that are complex and recursive are now 98% smaller. * We now show [additionalProperties](https://swagger.io/docs/specification/data-models/dictionaries/) in OpenAPI pages. ## File Uploads in API Playground By default, API playground requests are proxied by Mintlify. Now you can use `disableProxy` to disable this behavior and support request types like file uploads. * [Learn more about API configurations](/settings/global#api-configurations) ## Mobile SEO improvements We've fixed the mobile layout of our docs so that they are more SEO-friendly - including adding proper aria tags to elements. ## Support Form We added a more detailed support form to the Mintlify dashboard. You can now submit a form to get in touch with us. ## Bug Fixes * Fixed a bug for the Segment integration functionality. * We now raise more granular error messages for GitHub permissions when interacting with the editor. * Fixed bugs where the navigation would not properly expand when a direct link was used. ## AI Widget AI Widget For `Pro` users, we introduced Mintlify Widget, an extension of your docs to answer your users' questions when and where they asked. You can add this AI-powered chatbot to any web page: your landing page, inside your product, or on your existing documentation pages. * [Read the blog announcement](https://mintlify.com/blog/widget) ## Pro Plan We also updated our pricing plans for better customizability and scale. * [Read the blog announcement](https://mintlify.com/blog/pro-plan) ## API Playground Code Example Sync When you browse API docs, the selected code example now syncs across your pages. ## Insights Currently in beta, this feature summarizes common user questions and patterns into easy-to-digest reports with AI-powered suggestions on how to improve your product. ## Launch Week Highlights * Themes: Customize your styling with pre-configured themes. Just add the theme Quill, Prism, or Venus to your `mint.json` file and it'll update your docs styling. * Search V2: directly query OpenAPI endpoint descriptions and titles to reach API Reference pages, remove hidden pages from search, and enjoy our updated searchbar UI. * Web Editor branching: create branches in our web editor without an IDE. * User Personalization: authenticate users with Shared Session or JWT so that you can show them customized content, such as pre-filling API keys or showing specific content for customers. * OepenAPI Automation Upgrades: to auto-populate API Playground pages, you can add an `openapi` field to an object in tabs or anchors arrays in the mint.json. ## Okta SSO We now support sign-on via Okta SAML and OIDC. ## Mintlify REST API Programmatically rigger updates to your documentation. ## Custom mode Add a configuration to the metadata to remove all elements except for the top bar. Example use cases: * Create a custom global landing page setup with custom components * Add full-screen videos or image galleries * Embed custom iFrame demo elements to add intractability to your docs Check out our [Custom Mode docs](/page#custom-mode). ## Mintlify MDX for VSCode Call snippets of our pre-built components an dcallouts without leaving VSCode. [Install the extension here](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets). ## Quality Improvements * Dashboard upgrades: view update logs to see what's changed and status of an update, toggle between Mintlify projects to manage deployments * Versioning with tabs fully supported * Wildcard redirects now supported * CLI Error Detection: we now show the position of invalid frontmatter when there are parsing issues during local development ## Launch Week Highlights * Preview Deployments: When you create a pull request, we'll generate a unique link that shows a live preview of what your docs look like in prod. You can share this link with teammates. * Snippets V2: We now support fully reusable components and variables for snippets. * Open-source MDX Engine: We've exposed two APIs—getCompiledMdx and MDXComponent—so you can access Mintlify markdown and code syntax highlighting. [Contributions to the project](https://github.com/mintlify/mdx) are welcome. * AI Chat Insights: Segment chat history by date and increase AI Chat quota from the dashboard, and see how often a specific query appears. # Code Blocks Source: https://mintlify.mintlify.review/code Display inline code and code blocks ## 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](https://www.markdownguide.org/extended-syntax/#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. ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` ````md ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` ```` Visit the [Code Block page](/content/components/code) for more detailed docs. # Accordion Groups Source: https://mintlify.mintlify.review/content/components/accordion-groups Group multiple accordions into a single display. Simply add `` around your existing `` components. You can put other components inside Accordions. ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` Check out the [Accordion](/content/components/accordions) docs for all the supported props. Check out the [Accordion](/content/components/accordions) docs for all the supported props. ````jsx Accordion Group Example You can put other components inside Accordions. ```java HelloWorld.java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` Check out the [Accordion](/content/components/accordions) docs for all the supported props. Check out the [Accordion](/content/components/accordions) docs for all the supported props. ```` `AccordionGroup` does not have any props. # Accordions Source: https://mintlify.mintlify.review/content/components/accordions A dropdown component to toggle content You can put any content in here. Check out [AccordionGroup](/content/components/accordion-groups) if you want to group multiple Accordions into a single display. ```jsx Accordion Example You can put any content in here. ``` ## Props Title in the Accordion preview. Detail below the title in the Accordion preview. Whether the Accordion is open by default. A [Font Awesome icon](https://fontawesome.com/icons) or SVG code One of "regular", "solid", "light", "thin", "sharp-solid", "duotone", or "brands" # Callout Boxes Source: https://mintlify.mintlify.review/content/components/callouts Use callouts to add eye-catching context to your content ### Note Callouts This adds a note in the content ```jsx This adds a note in the content ``` ### Warning Callouts This raises a warning to watch out for ```jsx This raises a warning to watch out for ``` ### Info Callouts This draws attention to important information ```jsx This draws attention to important information ``` ### Tip Callouts This suggests a helpful tip ```jsx This suggests a helpful tip ``` ### Check Callouts This brings us a checked status ```jsx This brings us a checked status ``` # Card Groups Source: https://mintlify.mintlify.review/content/components/card-groups Show cards side by side in a grid format The `CardGroup` component lets you group multiple `Card` components together. It's most often used to put multiple cards on the same column. Neque porro quisquam est qui dolorem ipsum quia dolor sit amet Lorem ipsum dolor sit amet, consectetur adipiscing elit Ut enim ad minim veniam, quis nostrud exercitation ullamco Excepteur sint occaecat cupidatat non proident ```jsx Card Group Example Neque porro quisquam est qui dolorem ipsum quia dolor sit amet Lorem ipsum dolor sit amet, consectetur adipiscing elit Ut enim ad minim veniam, quis nostrud exercitation ullamco Excepteur sint occaecat cupidatat non proident ``` ## Props The number of columns per row # Cards Source: https://mintlify.mintlify.review/content/components/cards Highlight main points or links with customizable icons This is how you use a card with an icon and a link. Clicking on this card brings you to the Card Group page. ```jsx Card Example This is how you use a card with an icon and a link. Clicking on this card brings you to the Card Group page. ``` ```jsx Image Card Example Here is an example of a card with an image ``` ### Horizontal Card Add a `horizontal` property to a card to make it horizontally displayed. Here is an example of a horizontal card ### Image Card Add an `img` property to a card to display an image on the top of the card. Here is an example of a card with an image ## Props The title of the card A [Font Awesome icon](https://fontawesome.com/icons) or SVG code in `icon={}` One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` The color of the icon as a hex code The url that clicking on the card would navigate the user to Makes the card more compact and horizontal The url or local path to an image to display on the top of the card # Code Blocks Source: https://mintlify.mintlify.review/content/components/code Display code with optional syntax highlighting ````md Code Block Example ```javascript Code Block Example const hello = "world"; ``` ```` ## Basic Code Block Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks. ``` helloWorld(); ``` ````md ``` helloWorld(); ``` ```` ## Syntax Highlighting Put the name of your programming language after the three backticks to get syntax highlighting. We use [Prism](https://prismjs.com/#supported-languages) for syntax highlighting. [Test Drive Prism](https://prismjs.com/test.html#language=markup) lists all the languages supported. ```java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` ````md ```java class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World!"); } } ``` ```` ## 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. ```javascript Code Block Example const hello = "world"; ``` ````md Code Block Example ```javascript Code Block Example const hello = "world"; ``` ```` ## 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. ```javascript Line Highlighting Example {1,3-5} const greeting = "Hello, World!"; function sayHello() { console.log(greeting); } sayHello(); ``` ````md ```javascript Line Highlighting Example {1,3-5} const greeting = "Hello, World!"; function sayHello() { console.log(greeting); } sayHello(); ``` ```` ## Expandable If you have a long code block and `[expandable]` after your title to make it close and expand. ```python library.py [expandable] from datetime import datetime, timedelta from typing import Dict, List, Optional from dataclasses import dataclass @dataclass class Book: title: str author: str isbn: str checked_out: bool = False due_date: Optional[datetime] = None class Library: def __init__(self): self.books: Dict[str, Book] = {} self.checkouts: Dict[str, List[str]] = {} # patron -> list of ISBNs def add_book(self, book: Book) -> None: if book.isbn in self.books: raise ValueError(f"Book with ISBN {book.isbn} already exists") self.books[book.isbn] = book def checkout_book(self, isbn: str, patron: str, days: int = 14) -> None: if patron not in self.checkouts: self.checkouts[patron] = [] book = self.books.get(isbn) if not book: raise ValueError("Book not found") if book.checked_out: raise ValueError("Book is already checked out") if len(self.checkouts[patron]) >= 3: raise ValueError("Patron has reached checkout limit") book.checked_out = True book.due_date = datetime.now() + timedelta(days=days) self.checkouts[patron].append(isbn) def return_book(self, isbn: str) -> float: book = self.books.get(isbn) if not book or not book.checked_out: raise ValueError("Book not found or not checked out") late_fee = 0.0 if datetime.now() > book.due_date: days_late = (datetime.now() - book.due_date).days late_fee = days_late * 0.50 book.checked_out = False book.due_date = None # Remove from patron's checkouts for patron, books in self.checkouts.items(): if isbn in books: books.remove(isbn) break return late_fee def search(self, query: str) -> List[Book]: query = query.lower() return [ book for book in self.books.values() if query in book.title.lower() or query in book.author.lower() ] def main(): library = Library() # Add some books books = [ Book("The Hobbit", "J.R.R. Tolkien", "978-0-261-10295-4"), Book("1984", "George Orwell", "978-0-452-28423-4"), ] for book in books: library.add_book(book) # Checkout and return example library.checkout_book("978-0-261-10295-4", "patron123") late_fee = library.return_book("978-0-261-10295-4") print(f"Late fee: ${late_fee:.2f}") if __name__ == "__main__": main() ``` ````md ```javascript Expandable Example [expandable] const greeting = "Hello, World!"; function sayHello() { console.log(greeting); } sayHello(); ``` ```` ## Code Groups Want to display multiple code examples in one code box? Check out the Code Group docs: Read the reference for the Code Group component # Code Groups Source: https://mintlify.mintlify.review/content/components/code-groups The CodeGroup component lets you combine code blocks in a display separated by tabs You will need to make [Code Blocks](/content/components/code) then add the `` 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. ```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!"); } } ``` ````md Code Group Example ```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!"); } } ``` ```` # Expandables Source: https://mintlify.mintlify.review/content/components/expandables Toggle to display nested properties. The full name of the user Whether the user is over 21 years old ```jsx Expandable Example The full name of the user Whether the user is over 21 years old ``` ## Props The name of the object you are showing. Used to generate the "Show NAME" and "Hide NAME" text. Set to true to show the component as open when the page loads. # Frames Source: https://mintlify.mintlify.review/content/components/frames Use the Frame component to wrap images or other components in a container. 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. ## Props Optional caption text to show centered under your component. ```jsx Frame ``` ```jsx Frame with Captions ``` # Icons Source: https://mintlify.mintlify.review/content/components/icons Use [Font Awesome](https://fontawesome.com/icons) icons anywhere in the doc ```jsx Icon Example ``` ## Inline Icons The icon will be placed inline when used in a paragraph. ```markdown Inline Icon Example The documentation you want, effortlessly ``` The documentation you want, effortlessly ## Props A [Font Awesome](https://fontawesome.com/icons) icon One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` The color of the icon as a hex code (e.g., `#FF5733`) The size of the icon in pixels # Mermaid Diagrams Source: https://mintlify.mintlify.review/content/components/mermaid-diagrams Display diagrams using Mermaid ````md Mermaid Flowchart Example ```mermaid flowchart LR subgraph subgraph1 direction TB top1[top] --> bottom1[bottom] end subgraph subgraph2 direction TB top2[top] --> bottom2[bottom] end %% ^ These subgraphs are identical, except for the links to them: %% Link *to* subgraph1: subgraph1 direction is maintained outside --> subgraph1 %% Link *within* subgraph2: %% subgraph2 inherits the direction of the top-level graph (LR) outside ---> top2 ``` ```` [Mermaid](https://mermaid.js.org/) lets you create visual diagrams using text and code. ```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 ``` 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](https://mermaid.js.org/). ## Syntax for Mermaid diagrams To create a flowchart, you can write the Mermaid flowchart inside a Mermaid code block. ````md ```mermaid // Your mermaid code block here ``` ```` # Parameter Fields Source: https://mintlify.mintlify.review/content/components/params Set path, query, and body parameters `ParamField` components help define the parameters for your APIs or SDKs. Adding a ParamField will automatically add an [API Playground](/api-playground/overview). An example of a parameter field ```jsx Path Example An example of a parameter field ``` ```jsx Query Example The filtering command used to sort through the users ``` ```jsx Body Example The age of the user. Cannot be less than 0 ``` ## Props Whether it is a query, path, body, or header parameter followed by the name Expected type of the parameter's value Supports `number`, `string`, `bool`, `object`. Arrays can be defined using the `[]` suffix. For example `string[]`. Indicate whether the parameter is required Indicate whether the parameter is deprecated Default value used by the server if the request does not provide a value Value that will be used to initialize the playground Placeholder text for the input in the playground Description of the parameter (markdown enabled) # Response Fields Source: https://mintlify.mintlify.review/content/components/responses Display API response values The `` component is designed to define the return values of an API. Many docs also use `` on pages when you need to list the types of something. A response field example ```jsx ResponseField Example A response field example ``` ## Props The name of the response value. Expected type of the response value The default value. Show "required" beside the field name. # Steps Source: https://mintlify.mintlify.review/content/components/steps Sequence content using the Steps component Steps are the best way to display a series of actions of events to your users. You can add as many steps as desired. These are instructions or content that only pertain to the first step. These are instructions or content that only pertain to the second step. These are instructions or content that only pertain to the third step. ```jsx Steps Example These are instructions or content that only pertain to the first step. These are instructions or content that only pertain to the second step. These are instructions or content that only pertain to the third step. ``` ## Steps Props A list of `Step` components. The size of the step titles. One of `p`, `h2` and `h3`. ## Individual Step Props The content of a step either as plain text, or components. A [Font Awesome icon](https://fontawesome.com/icons) or SVG code in `icon={}` One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` The title is the primary text for the step and shows up next to the indicator. The number of the step. The size of the step titles. One of `p`, `h2` and `h3`. # Sidebar Code Examples Source: https://mintlify.mintlify.review/content/components/sticky-examples Display code blocks at the top-right of the page on desktop devices The `` and `` 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. `` and `` show up like regular code blocks on mobile. ## Request Example The `` component works similar to [CodeGroup](/content/components/code-groups), but displays the request content on the right sidebar. Thus, you can put multiple code blocks inside ``. Please set a name on every code block you put inside RequestExample. ````md RequestExample Example ```bash Request curl --request POST \ --url https://dog-api.kinduff.com/api/facts ``` ```` ## Response Example The `` component is the same as `` but will show up underneath it. ````md ResponseExample Example ```json Response { "status": "success" } ``` ```` # Tabs Source: https://mintlify.mintlify.review/content/components/tabs Toggle content using the Tabs component You can add any number of tabs. ☝️ Welcome to the content that you can only see inside the first Tab. ✌️ Here's content that's only inside the second Tab. 💪 Here's content that's only inside the third Tab. ```jsx Tabs Example ☝️ Welcome to the content that you can only see inside the first Tab. ✌️ Here's content that's only inside the second Tab. 💪 Here's content that's only inside the third Tab. ``` ## Tab Props The title of the tab. Short titles are easier to navigate. # Tooltips Source: https://mintlify.mintlify.review/content/components/tooltips Show a definition when you hover over text. Hover over me and see a tooltip in action ```jsx Tooltip Example Hover over me ``` # Update Source: https://mintlify.mintlify.review/content/components/update Keep track of changes and updates The `Update` component is used to keep track of changes and updates. ## 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 ### How to use ```md This is how you use a changelog with a label and a description. This is how you use a changelog with a label and a description. ``` 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 in the changelog, on the sticky left side. Description below the label in the Changelog preview. # Local Development Source: https://mintlify.mintlify.review/development Preview changes locally to update your docs **Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. **Step 1**: Install the Mintlify CLI: ```bash npm npm i -g mintlify ``` ```bash yarn yarn global add mintlify ``` ```bash pnpm pnpm add -g mintlify ``` **Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command: ```bash mintlify dev ``` Alternatively, if you do not want to install the CLI globally you can use a run script available: ```bash npm npx mintlify dev ``` ```bash yarn yarn dlx mintlify dev ``` ```bash pnpm pnpm dlx mintlify dev ``` Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information. 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: ```bash mintlify dev --port 3333 ``` If you attempt to run on a port that's already in use, it will use the next available port: ```md Port 3000 is already in use. Trying 3001 instead. ``` ## 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: ```bash npm npm i -g mintlify@latest ``` ```bash yarn yarn global upgrade mintlify ``` ```bash pnpm pnpm up --global mintlify ``` ## Validating Links The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: ```bash mintlify broken-links ``` ## 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](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. ## Troubleshooting This may be due to an outdated version of node. Try the following: 1. Remove the currently-installed version of mintlify: `npm remove -g mintlify` 2. Upgrade to Node v19 or higher. 3. Reinstall mintlify: `npm install -g mintlify` Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. # Images, Videos, and Embeds Source: https://mintlify.mintlify.review/image-embeds Add image, video, and other HTML elements Mintlify supports files up to 5 MB. To use larger files, consider a storage service like Cloudinary and embed in your documentation using the URL. ## Image ### Using Markdown The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code ```md ![title](/path/image.jpg) ``` Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/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. ```html ``` ### Disable Image Zoom To disable the default zoom on click for images, add the noZoom property to image embeds. ```html ``` ### 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. ```html ``` ### Dark Mode To use separate images for light and dark mode, use Tailwind CSS to hide and show images. ```html ``` ### Related For more information, we recommend the following sections: Read the reference for the Frame component ## Videos ``` For other videos, use: ```html ``` To autoplay the video, use: ```html ``` Since Mintlify needs to adhere to the JSX syntax, double word attributes will need to be written in camelCase: autoPlay, playsInline. ## iFrames Loads another HTML page within the document. ```html ``` Although not required, we recommend adding the `alt` and `title` attributes to images for better SEO and accessability. Learn more at [image SEO](https://yoast.com/image-seo-alt-tag-and-title-tag-optimization/). # Amplitude Source: https://mintlify.mintlify.review/integrations/analytics/amplitude Add the following to your `docs.json` file to send analytics to Amplitude. ```json Analytics options in docs.json "integrations": { "amplitude": { "apiKey": "required" } } ``` ```json Example "integrations": { "amplitude": { "apiKey": "76bb138bf3fbf58186XXX00000" } } ``` # Clearbit Source: https://mintlify.mintlify.review/integrations/analytics/clearbit Add the following to your `docs.json` file to send analytics to Clearbit. ```json Analytics options in docs.json integrations: { "clearbit": { "publicApiKey": "required" } } ``` ```json Example integrations: { "clearbit": { "publicApiKey": "pk_1a1882" } } ``` # Fathom Source: https://mintlify.mintlify.review/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. ```json Analytics options in docs.json integrations: { "fathom": { "siteId": "required" } } ``` ```json Example integrations: { "fathom": { "siteId": "YSVMSDAY" } } ``` # Google Analytics 4 Source: https://mintlify.mintlify.review/integrations/analytics/google-analytics You will need to generate a new GA4 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 GA4 property. GA4 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. ![](https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/ga4-web-streams.png) 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: ```json docs.json integrations: { "ga4": { "measurementId": "G-XXXXXXX" } } ``` ### Wait Google Analytics takes two to three days to show your data. You can use the [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna?hl=en) to check analytics are enabled correctly. The extension will log to your browser's console every time GA4 makes a request. Preview links have analytics turned off. # Google Tag Manager Source: https://mintlify.mintlify.review/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. ```json Analytics options in docs.json integrations: { "gtm": { "tagId": "required" } } ``` ```json Example integrations: { "gtm": { "tagId": "GTM-MGBL4PW" } } ``` # Heap Source: https://mintlify.mintlify.review/integrations/analytics/heap Add the following to your `docs.json` file to send analytics to Heap. ```json Analytics options in docs.json integrations: { "heap": { "appId": "required" } } ``` ```json Example integrations: { "heap": { "appId": "1234567890" } } ``` # HotJar Source: https://mintlify.mintlify.review/integrations/analytics/hotjar Add the following to your `docs.json` file to send analytics to HotJar. ```json Analytics options in docs.json integrations: { "hotjar": { "hjid": "required", "hjsv": "required" } } ``` # Koala Source: https://mintlify.mintlify.review/integrations/analytics/koala Add the following to your `docs.json` file to send analytics to Koala. ```json Analytics options in docs.json integrations: { "koala": { "publicApiKey": "required" } } ``` ```json Example integrations: { "koala": { "publicApiKey": "pk_1a1882" } } ``` # LogRocket Source: https://mintlify.mintlify.review/integrations/analytics/logrocket Add the following to your `docs.json` file to send analytics to LogRocket. ```json Analytics options in docs.json integrations: { "logrocket": { "apiKey": "required" } } ``` # Mixpanel Source: https://mintlify.mintlify.review/integrations/analytics/mixpanel Add the following to your `docs.json` file to send analytics to Mixpanel. ```json Analytics options in docs.json integrations: { "mixpanel": { "projectToken": "required" } } ``` # Analytics Integrations Source: https://mintlify.mintlify.review/integrations/analytics/overview Integrate with an analytics platform to track events Automatically send data about your documentation engagement to your third party analytics provider. ## All Integrations } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> } /> ## Enabling Analytics 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. ```json Analytics options in docs.json 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" }, } ``` ```json Google Analytics 4 Example integrations: { "ga4": { "measurementId": "G-XXXXXXX" } } ``` ## FAQ * `expandable_open` * `expandable_close` * `accordion_open` * `accordion_close` * `header_nav_item_click` * `cta_click` * `scroll_to_bottom` * `search_close` * `api_playground_call` * `search_result_click` * `chat_enter` * `chat_followup` * `chat_completed` * `code_block_copy` * `chat_shared` * `thumb_vote` * `powered_by_mintlify_click` * `ai_chat_citation_click` * `ai_chat_feedback_positive_click` * `ai_chat_feedback_negative_click` * `pageview` # Pirsch Source: https://mintlify.mintlify.review/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. ```json Analytics options in docs.json integrations: { "pirsch": { "id": "required" } } ``` ```json Example integrations: { "pirsch": { "id": "8Kw7OKxBfswOjnKGZa7P9Day8JmVYwTp" } } ``` # Plausible Source: https://mintlify.mintlify.review/integrations/analytics/plausible Add your site's domain to `docs.json` to send analytics to Plausible. Do not include `https://` for the domain or server. ```json Analytics options in docs.json integrations: { "plausible": { "domain": "required", "server": "optional" } } ``` ```json Example integrations: { "plausible": { "domain": "docs.domain.com" } } ``` # PostHog Source: https://mintlify.mintlify.review/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. ```json Analytics options in docs.json integrations: { "posthog": { "apiKey": "required", "apiHost": "optional" } } ``` ```json Example integrations: { "posthog": { "apiKey": "phc_TXdpocbYTeZVm5VJmMzHTMrCofBQu3e0kN7HGMNGTVW" } } ```
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. # Segment Source: https://mintlify.mintlify.review/integrations/analytics/segment Add your Segment write key to your `docs.json` file to send analytics to Segment. ```json Analytics options in docs.json integrations: { "segment": { "key": "required", } } ``` ```json Example integrations: { "segment": { "key": "nqJxiRG15Y6M594P8Sb8ESEciU3VC2" } } ``` # Osano Source: https://mintlify.mintlify.review/integrations/privacy/osano Add the following to your `docs.json` file to add the [Osano](https://www.osano.com/) cookie consent manager. ```json Integration options in docs.json "integrations": { "osano": "SOURCE" } ``` ```json Example "integrations": { "osano": "https://cmp.osano.com/2sUB2dqwqdkks/8dqwd-dwd86£-4a9b/osano.js" } ``` The `SOURCE` can be found as the `src` value in the code snippet generated by Osano. It always starts with `https://cmp.osano.com/`. ```html Code snippet from Osano