> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-nick-eng-3707-update-chat-endpoints-to-single-assi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 API documentation projects as it's more maintainable and feature-rich. However, MDX can be useful for documenting small APIs, prototyping, or when you want to feature API endpoints alongside other content.

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.

<Steps>
  <Step title="Configure your API">
    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 want to hide the API playground, use the `display` field. You do not need to include an auth method if you hide the playground.

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

    Find a full list of API configurations in [Settings](/settings#api-configurations).
  </Step>

  <Step title="Create your endpoint pages">
    Each API endpoint page should have a corresponding `MDX` file. At the top of each file, define `title` and `api`:

    ```mdx
    ---
    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}
    ```

    <Note>
      If you have a `server` field configured in `docs.json`, you can use relative paths like `/v1/endpoint`.
    </Note>

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

    ```mdx
    ---
    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.
  </Step>

  <Step title="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](/navigation).
  </Step>
</Steps>

## 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

<CodeGroup>
  ```json docs.json
  "api": {
      "mdx": {
        "auth": {
          "method": "bearer"
        }
      }
  }
  ```

  ```mdx Page Metadata
  ---
  title: "Your page title"
  authMethod: "bearer"
  ---
  ```
</CodeGroup>

### Basic authentication

<CodeGroup>
  ```json docs.json
  "api": {
      "mdx": {
        "auth": {
          "method": "basic"
        }
      }
  }
  ```

  ```mdx Page Metadata
  ---
  title: "Your page title"
  authMethod: "basic"
  ---
  ```
</CodeGroup>

### API key

<CodeGroup>
  ```json docs.json
  "api": {
      "mdx": {
        "auth": {
          "method": "key",
          "name": "x-api-key"
        }
      }
  }
  ```

  ```mdx Page Metadata
  ---
  title: "Your page title"
  authMethod: "key"
  ---
  ```
</CodeGroup>

### None

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

<CodeGroup>
  ```mdx Page Metadata
  ---
  title: "Your page title"
  authMethod: "none"
  ---
  ```
</CodeGroup>