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

<!-- agent-signals: reading_time_min: 4 · est_tokens: 1888 · updated: 2026-07-30 -->
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)

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

## Setup [#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 [#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 [#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 [#bearer-token]

<CodeGroup>
  <CodeBlockTabs defaultValue="docs.json" groupId="docs-json+page-metadata">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="docs.json">
        docs.json
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Page Metadata">
        Page Metadata
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="docs.json">
      ```json  
      "api": {
        "mdx": {
          "auth": {
            "method": "bearer"
          }
        }
      }
      ```
    </CodeBlockTab>

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

### Basic authentication [#basic-authentication]

<CodeGroup>
  <CodeBlockTabs defaultValue="docs.json" groupId="docs-json+page-metadata">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="docs.json">
        docs.json
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Page Metadata">
        Page Metadata
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="docs.json">
      ```json  
      "api": {
        "mdx": {
          "auth": {
            "method": "basic"
          }
        }
      }
      ```
    </CodeBlockTab>

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

### API key [#api-key]

<CodeGroup>
  <CodeBlockTabs defaultValue="docs.json" groupId="docs-json+page-metadata">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="docs.json">
        docs.json
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Page Metadata">
        Page Metadata
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

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

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

### None [#none]

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

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