Skip to main content
You can manually define API endpoints in individual 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.
"api": {
  "mdx": {
    "server": "https://mintlify.com/api",
    "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 https://api.mintlify.com/user'
---
Specify path parameters by wrapping them in {}:
https://api.example.com/v1/endpoint/{userId}
If you have a server field configured in docs.json, you can use relative paths like /v1/endpoint.
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. Learn more about structuring your docs in Navigation.

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