MDX Setup

Generate docs pages for your API endpoints using MDX

Mintlify allows you to define your API endpoints using a combination of mint.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 mint.json file, define your base URL and auth method:

   {
     "api": {
       "baseUrl": "https://mintlify.com/api", // string array for multiple base URLs
       "auth": {
         "method": "bearer" // 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": {
         "mode": "hide"
       }
     }
   }
   

   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 baseUrl configured in mint.json, you can use relative paths like /v1/endpoint.

3. Add your endpoints to your docs

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