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

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

​
Using OpenAPI endpoints in navigation

If you have an OpenAPI specification, you can reference endpoints directly in your navigation without creating individual MDX files.
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.

​
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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us