MDX setup

Generate docs pages for your API endpoints using MDX

You can manually define API endpoints in individual MDX files rather than using an OpenAPI specification. This method provides flexibility for custom content, but we recommend generating API documentation from an OpenAPI specification file for most projects because it is more maintainable and feature-rich. However, creating MDX pages for an API can be useful to document small APIs, prototyping, or when you want more control over where API endpoints are in the navigation.

To generate pages for API endpoints using MDX, configure your API settings in docs.json, create individual MDX files for each endpoint, and use components like <ParamFields /> to define parameters. From these definitions, Mintlify generates interactive API playgrounds, 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 want to hide the API playground, use the display field. You do not need to include an auth method if you hide the playground.

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

   Find a full list of API configurations in Settings.

2. Create your endpoint pages

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

   ---
   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 a server field configured in docs.json, you can use relative paths like /v1/endpoint.

   You can override the globally-defined display mode for the API playground for a page by adding playground to the frontmatter:

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

   • playground: 'interactive' - Display the interactive playground.
   • playground: 'simple' - Display a copyable endpoint with no playground.
   • playground: 'none' - Hide the playground.
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 in Navigation.

Enabling authentication

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

A page’s authentication method will override a global method if both are set.

Bearer token

docs.json

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

Basic authentication

docs.json

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

API key

docs.json

"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.

Page Metadata

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