Skip to main content
You can manually define API endpoints in individual MDX pages. This approach is useful for small APIs, prototyping, or when you need granular control over individual endpoint documentation.

​
Setup

1

Configure your API settings

In your docs.json file, define your base URL and authentication method.
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.
"api": {
  "playground": {
    "display": "none"
  }
}
Find a full list of API configurations in Settings.
2

Create your endpoint pages

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
3

Add parameters and responses

Use parameter and response fields to document your endpoint’s parameters and return values.
<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>
4

Add your endpoints to your docs

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

​
Authentication methods

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

"api": {
  "mdx": {
    "auth": {
      "method": "bearer"
    }
  }
}

​
Basic authentication

"api": {
  "mdx": {
    "auth": {
      "method": "basic"
    }
  }
}

​
API key

"api": {
  "mdx": {
    "auth": {
      "method": "key",
      "name": "x-api-key"
    }
  }
}

​
None

To disable authentication on a specific page, set authMethod to none:
Page Metadata
---
title: "Your page title"
authMethod: "none"
---

​
Mix with OpenAPI endpoints

If you have an OpenAPI specification, you can reference endpoints directly in your navigation without creating individual MDX files. This allows you to mix manually created pages with auto-generated ones.

​
Reference OpenAPI endpoints in navigation

Reference specific endpoints by including the OpenAPI file path and the endpoint:
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:
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.

​
Advanced examples

​
Path parameters

Document path parameters using the ParamField component with the path attribute: 
---
title: 'Get user by ID'
api: 'GET /v1/users/{userId}'
---

<ParamField path="userId" type="string" required>
  The unique identifier of the user to retrieve
</ParamField>

​
Query parameters

Document query parameters using the ParamField component with the query attribute: 
---
title: 'List users'
api: 'GET /v1/users'
---

<ParamField query="limit" type="number" default={10}>
  Maximum number of users to return
</ParamField>

<ParamField query="offset" type="number" default={0}>
  Number of users to skip before returning results
</ParamField>

​
Request body parameters

Document request body parameters using the ParamField component with the body attribute: 
---
title: 'Create user'
api: 'POST /v1/users'
---

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

<ParamField body="name" type="string" required>
  User's full name
</ParamField>

<ParamField body="role" type="string" default="user">
  User's role in the system. Can be `user` or `admin`.
</ParamField>

​
Response examples

Document response fields using the ResponseField component: 
---
title: 'Create user'
api: 'POST /v1/users'
---

## Response

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

<ResponseField name="createdAt" type="timestamp" required>
  ISO 8601 timestamp of when the user was created
</ResponseField>

​
When to use MDX vs OpenAPI

Use MDX when:
  • You have a small API with few endpoints
  • You need maximum control over individual page layout and content
  • You’re prototyping or experimenting with API documentation
  • You want to add extensive custom content alongside API documentation
Use OpenAPI when:
  • You have a large API with many endpoints
  • You want to auto-generate documentation from your API specification
  • You want to keep your API documentation in sync with your API implementation
  • You prefer maintaining a single source of truth for your API
You can also combine both approaches - use OpenAPI for most endpoints and create custom MDX pages for specific endpoints that need special treatment.

Build docs developers (and LLMs) love

Get started for freeTalk to us