Create manual API pages

In your docs.json file, define your base URL and authentication method.

"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.

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

Find a full list of API configurations in Settings.

Create an MDX file for each endpoint. Define the title and api in the frontmatter:

---
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 {}:

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

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

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

Use parameter and response fields to document your endpoint's parameters and return values. To show request and response code samples in the right sidebar, wrap them in <RequestExample> and <ResponseExample> components.

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

Add your endpoint pages to the navigation by updating the pages field in your 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.

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:

"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:

{
  "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.