> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create manual API pages

> 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 Example docs.json theme={null}
    "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 theme={null}
    "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 theme={null}
    ---
    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 theme={null}
    https://api.example.com/v1/endpoint/{userId}
    ```

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

    ```mdx theme={null}
    ---
    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 theme={null}
    <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 docs.json theme={null}
    "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 docs.json theme={null}
    "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 docs.json theme={null}
    {
      "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 docs.json theme={null}
  "api": {
    "mdx": {
      "auth": {
        "method": "bearer"
      }
    }
  }
  ```

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

### Basic authentication

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

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

### API key

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

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

### None

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

```mdx Page Metadata theme={null}
---
title: "Your page title"
authMethod: "none"
---
```


## Related topics

- [Pages](/docs/organize/pages.md)
- [Guides](/docs/guides/index.md)
- [Playground](/docs/api-playground/overview.md)