> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.manicule.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://mintlify.manicule.dev/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://mintlify.manicule.dev/api/mcp.
> Every agent surface: https://mintlify.manicule.dev/.well-known/llms-manifest.json

# Create manual API pages (/api-playground/mdx-setup)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1500 · updated: 2026-07-31 -->
Related: [API playground overview](/api-playground/overview.md), [OpenAPI setup](/api-playground/openapi-setup.md), [Complex data types](/api-playground/complex-data-types.md), [Add SDK examples](/api-playground/adding-sdk-examples.md), [Manage page visibility](/api-playground/managing-page-visibility.md), [Multiple responses](/api-playground/multiple-responses.md)

> Create API reference pages manually with MDX files when you need full control over layout for small APIs, prototypes, or custom docs.

You can manually define API endpoints in individual MDX pages. This approach is useful for small APIs or prototyping.

## Setup

<Steps>
  <Step title="Configure your API settings">
    In your `docs.json` file, define your base URL and authentication method.

    ```json title="Example docs.json"
    "api": {
      "mdx": {
        "server": "https://api.acme.com/",
        "auth": {
          "method": "key",
          "name": "x-api-key"
        }
      }
    }
    ```

    If you want to hide the API playground, set the `display` field to `none`. You don't need to include an authentication method if you hide the playground.

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

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

  <Step title="Create your endpoint pages">
    Create an MDX file for each endpoint. Define the `title` and `api` in the frontmatter:

    ```mdx
    ---
    title: 'Create new user'
    api: 'POST /v1/users'
    ---
    ```

    The `api` frontmatter field accepts either a full URL or a relative path:

    * **Full URL** like `POST https://api.acme.com/v1/users`. The `server` field in `docs.json` is ignored for that endpoint.
    * **Relative path** like `POST /v1/users`. Requires a `server` field in `docs.json`. The server URL is prepended to the path.

    Specify path parameters by wrapping them in `{}`:

    ```bash
    https://api.example.com/v1/endpoint/{userId}
    ```

    To override the global playground display mode for a specific page, add `playground` to the frontmatter:

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

    Options:

    * `playground: 'interactive'` - Display the interactive playground (default)
    * `playground: 'simple'` - Display a copyable endpoint with no playground
    * `playground: 'none'` - Hide the playground entirely
  </Step>

  <Step title="Add parameters and responses">
    Use [parameter and response fields](/components/fields) to document your endpoint's parameters and return values.

    ```mdx
    <ParamField path="userId" type="string" required>
      Unique identifier for the user
    </ParamField>

    <ParamField body="email" type="string" required>
      User's email address
    </ParamField>

    <ResponseField name="id" type="string" required>
      Unique identifier for the newly created user
    </ResponseField>

    <ResponseField name="email" type="string" required>
      User's email address
    </ResponseField>
    ```
  </Step>

  <Step title="Add your endpoints to your docs">
    Add your endpoint pages to the navigation by updating the `pages` field in your `docs.json`:

    ```json title="docs.json"
    "navigation": {
      "tabs": [
        {
          "tab": "API Reference",
          "groups": [
            {
              "group": "Users",
              "pages": [
                "api-reference/users/create-user",
                "api-reference/users/get-user",
                "api-reference/users/update-user"
              ]
            },
            {
              "group": "Orders",
              "pages": [
                "api-reference/orders/create-order",
                "api-reference/orders/list-orders"
              ]
            }
          ]
        }
      ]
    }
    ```

    Each page path corresponds to an MDX file in your docs repository. For example, `api-reference/users/create-user.mdx`. Learn more about structuring your docs in [Navigation](/organize/navigation).

    ### Using OpenAPI endpoints in navigation

    If you have an OpenAPI specification, you can reference endpoints directly in your navigation without creating individual MDX files. Reference specific endpoints by including the OpenAPI file path and the endpoint:

    ```json title="docs.json"
    "navigation": {
      "pages": [
        "introduction",
        "/path/to/users-openapi.json POST /users",
        "/path/to/orders-openapi.json GET /orders"
      ]
    }
    ```

    You can also set a default OpenAPI spec for a navigation group and reference endpoints by method and path:

    ```json title="docs.json"
    {
      "group": "API reference",
      "openapi": "/path/to/openapi-v1.json",
      "pages": [
        "overview",
        "authentication",
        "GET /users",
        "POST /users",
        {
          "group": "Orders",
          "openapi": "/path/to/openapi-v2.json",
          "pages": [
            "GET /orders",
            "POST /orders"
          ]
        }
      ]
    }
    ```

    For more details on OpenAPI integration, see [OpenAPI setup](/api-playground/openapi-setup).
  </Step>
</Steps>

## Enable authentication

You can set authentication globally in `docs.json` or override it on individual pages using the `authMethod` field in frontmatter. A page-specific method overrides the global setting.

### Bearer token

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

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

### Basic authentication

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

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

### API key

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

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

### None

To disable authentication on a specific page, set `authMethod` to `none`:

```mdx title="Page Metadata"
---
title: "Your page title"
authMethod: "none"
---
```