MDX Setup

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.