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

# OpenAPI setup

> Generate interactive API documentation from OpenAPI specification files with automatic endpoint pages, request builders, and navigation.

OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0 and 3.1 documents to generate interactive API documentation and keep it up to date.

## Add an OpenAPI specification file

To document your endpoints with OpenAPI, you need one or more valid OpenAPI specifications in either JSON or YAML format that follow the [OpenAPI specification 3.0 or 3.1](https://swagger.io/specification/).

Add OpenAPI specifications to your documentation repository or host them online where you can access the specifications by URL. Mintlify serves specifications stored in your repository as [downloadable files](/docs/create/files) at their path on your docs domain. For example, `https://your-domain/docs/openapi.json`.

Reference any number of OpenAPI specifications in the navigation element of your `docs.json` to create pages for your API endpoints. Each specification file generates its own set of endpoints.

<CodeGroup>
  ```json Single specification theme={null}
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": "openapi.json"
      }
    ]
  }
  ```

  ```json Multiple specifications theme={null}
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": [
          "openapi/v1.json",
          "openapi/v2.json"
        ]
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  Mintlify supports `$ref` for **internal references only** within a single OpenAPI document. Mintlify does not support external references.
</Note>

### Use a localhost specification

During local development, you can generate an OpenAPI document from a service running on your machine and reference its localhost URL:

```json theme={null}
"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "openapi": "http://localhost:8000/openapi.json"
    }
  ]
}
```

Pass `--local-schema` to allow the CLI to fetch the specification over HTTP:

```bash theme={null}
mint dev --local-schema
```

To validate the same configuration without starting a preview, run `mint validate --local-schema`. Production deployments require OpenAPI URLs to use HTTPS.

### Describe your API

Use the following resources to learn about and construct your OpenAPI specification.

* [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/v3_0/basic-structure/) to learn the OpenAPI syntax.
* [The OpenAPI specification Markdown sources](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) to reference details of the latest OpenAPI specification.
* [Swagger Editor](https://editor.swagger.io/) to edit, validate, and debug your OpenAPI document.
* [The Mint CLI](https://www.npmjs.com/package/mint) to validate your OpenAPI document with the command: `mint validate`.

<Note>
  Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1. For more information on the differences between v3.0 and v3.1, see [Migrating from OpenAPI 3.0 to 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) in the OpenAPI blog.
</Note>

### Specify the base URL for your API

To enable the API playground, add a `servers` field to your OpenAPI specification with your API's base URL.

```json theme={null}
{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}
```

In an OpenAPI specification, paths like `/users/{id}` or `/` identify different API endpoints. The base URL defines where clients append these paths. For more information on how to configure the `servers` field, see [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) in the OpenAPI documentation.

The API playground uses these server URLs to determine where to send requests. If you specify multiple servers, a dropdown allows users to toggle between servers. If you do not specify a server, the API playground uses simple mode since it cannot send requests without a base URL.

If your API has endpoints that exist at different URLs, you can [override the `servers` field](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) for a given path or operation.

### Configure file uploads

For OpenAPI 3.1 specifications, define a file upload as a string schema with a binary `contentMediaType`. The API playground recognizes the field as a file input and sends it as part of a `multipart/form-data` request.

Use this configuration when an endpoint accepts a file inside a multipart request. You can also use `contentEncoding` to describe how the file content encodes. A `contentEncoding` value without a binary `contentMediaType` remains a text field. For base64-encoded files, set `contentEncoding` to `base64` or `base64url`. The API playground treats either value as a base64 file. For other values or no value, the API playground uses binary file handling.

```json theme={null}
{
  "paths": {
    "/imports": {
      "post": {
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "contentMediaType": "application/octet-stream"
                  }
                },
                "required": ["file"]
              }
            }
          }
        }
      }
    }
  }
}
```

You can use binary media types such as `application/octet-stream`, images, audio, video, PDFs, and archives. The API playground does not treat structured media types such as `application/json` as file uploads. The older `format: "binary"` and `format: "base64"` values remain supported.

### Specify authentication

To enable authentication in your API documentation and playground, configure the `securitySchemes` and `security` fields in your OpenAPI specification. The API descriptions and API playground add authentication fields based on the security configurations in your OpenAPI specification.

<Steps>
  <Step title="Define your authentication method.">
    Add a `securitySchemes` field to define how users authenticate.

    This example shows a configuration for bearer authentication.

    ```json theme={null}
    {
      "components": {
        "securitySchemes": {
          "bearerAuth": {
            "type": "http",
            "scheme": "bearer"
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Apply authentication to your endpoints.">
    Add a `security` field to require authentication.

    ```json theme={null}
    {
      "security": [
        {
          "bearerAuth": []
        }
      ]
    }
    ```
  </Step>
</Steps>

Common authentication types include:

* [API Keys](https://swagger.io/docs/specification/authentication/api-keys/): For header, query, or cookie-based keys.
* [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/): For JWT or OAuth tokens.
* [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/): For username and password.

If different endpoints within your API require different authentication methods, you can [override the `security` field](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for a given operation.

For more information on defining and applying authentication, see [Authentication](https://swagger.io/docs/specification/authentication/) in the OpenAPI documentation.

#### Set default values for security schemes

Use the `x-default` extension on a security scheme to pre-fill the authentication field in the API playground. This is useful for providing placeholder values or test credentials that help users get started quickly.

```json {6} theme={null}
{
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "x-default": "your-api-key-here"
      }
    }
  }
}
```

The `x-default` extension supports `apiKey` and `http` bearer security scheme types. The value appears as the default input in the playground's authentication fields. Prefill for security schemes is unconditional and does not require any additional configuration.

Use `x-default` on other schema properties in your OpenAPI specification to set a default value in the API playground without affecting the `default` field in the schema definition. Unlike security schemes, prefill for non-security-scheme properties only takes effect when you set [`api.examples.prefill`](/docs/organize/settings-api) to `true` in your [`docs.json`](/docs/api-playground/overview#example-configuration).

## Transform your spec with overlays

Use [OpenAPI Overlays](https://spec.openapis.org/overlay/v1.1.0.html) to modify an OpenAPI specification without editing its source file. Overlays are separate JSON or YAML files that describe an ordered list of changes, which is useful when a specification is generated by another tool or maintained by another team. Common uses include renaming paths, replacing server URLs, and removing internal endpoints.

Overlays apply after a specification is parsed and before it is validated, so generated endpoint pages, navigation, `openapi` frontmatter references, and `mint validate` all use the transformed document. Overlay Specification versions 1.0 and 1.1 are supported.

### Create an overlay document

An overlay document has an `overlay` version, an `info` object with a `title` and `version`, and an `actions` array. Each action selects nodes with a `target` [RFC 9535 JSONPath](https://www.rfc-editor.org/rfc/rfc9535) expression and applies one modifier:

* `update`: Merges a value into each targeted node. Objects merge recursively, arrays append the value, and primitives are replaced.
* `remove`: Deletes each targeted node when set to `true`.
* `copy`: Copies the node selected by another JSONPath expression into each targeted node. Requires Overlay 1.1.

```yaml docs-overlay.yaml theme={null}
overlay: 1.1.0
info:
  title: Docs adjustments
  version: 1.0.0
extends: ./openapi.json
actions:
  - target: $.info.description
    update: "The public API for Example, Inc."
  - target: $.paths['/internal-metrics']
    remove: true
```

The optional `extends` field links an overlay to a specification for [auto-discovery](#auto-discover-overlays). Set it to a path relative to the overlay file, or to the exact URL your `docs.json` uses for a hosted specification.

### Reference overlays in your docs.json

List overlays with the object form of the `openapi` field, which works anywhere `openapi` is accepted, including inside arrays. Overlays apply in the order you list them.

```json {6-9} theme={null}
"navigation": {
  "tabs": [
    {
      "tab": "API reference",
      "openapi": {
        "source": "openapi.json",
        "overlays": [
          "overlays/rename-paths.yaml",
          "https://example.com/overlays/servers.yaml"
        ]
      }
    }
  ]
}
```

Overlay paths must point to files inside your docs repository, and overlay URLs must use `https`. Referencing the same specification with different `overlays` lists in different places fails the build.

### Auto-discover overlays

Any JSON or YAML file in your repository with a top-level `overlay` key is treated as an overlay document. If its `extends` field resolves to one of your specifications, the overlay applies to that specification automatically. Auto-discovered overlays apply in alphabetical order of their file paths. Overlays without an `extends` field never apply automatically.

An explicit `overlays` list replaces auto-discovery for that specification. Set `"overlays": []` to disable all overlays for a specification, including auto-discovered ones.

Explicit and auto-discovered overlays fail differently. If an explicit overlay fails to load or apply, the specification fails validation and the deployment reports a spec error. If an auto-discovered overlay fails, it is skipped and the specification publishes without it.

### Rename a path

The Overlay Specification has no move action. To rename a path, create the new path with `update`, copy the existing path item into it with `copy`, then delete the old path with `remove`.

```yaml rename-overlay.yaml theme={null}
overlay: 1.1.0
info:
  title: Move accounts under credit
  version: 1.0.0
extends: ./openapi.json
actions:
  - target: $.paths
    update:
      /credit/accounts: {}
  - target: $.paths['/credit/accounts']
    copy: $.paths['/accounts']
  - target: $.paths['/accounts']
    remove: true
```

Reference the transformed specification everywhere in your docs. For example, page frontmatter must use the post-overlay path: `openapi: "POST /credit/accounts"`.

In `mint dev`, editing or deleting an overlay file rebuilds the affected specifications. `mint validate` and `mint openapi-check` validate the transformed document, so errors reference your specification after overlays apply.

## Let visitors download your spec

Opt into a "Download API spec" entry in the [page context menu](/docs/organize/settings-structure#contextual) by adding `"download-spec"` to `contextual.options` in your `docs.json`:

```json theme={null}
"contextual": {
  "options": ["copy", "download-spec", "chatgpt", "claude"]
}
```

When enabled, clicking the option downloads your OpenAPI spec directly. Deployments with multiple specs receive them bundled as `api-specs.zip`. On deployments behind `auth` or `userAuth`, only authenticated readers can download the spec.

<Warning>
  The downloaded OpenAPI spec is unfiltered and does not respect [authentication groups](/docs/deploy/authentication-setup). Any authenticated reader who can open the contextual menu receives the full spec, including endpoints and schemas that would otherwise be hidden from their group. Do not enable `download-spec` on an authenticated site if your OpenAPI spec contains endpoints or fields you consider sensitive.
</Warning>

## Customize your endpoint pages

Customize your endpoint pages by adding the `x-mint` extension to your OpenAPI specification. The `x-mint` extension gives you additional control over how your API documentation generates and displays.

### Metadata

Override the default metadata for generated API pages by adding `x-mint: metadata` to any operation. You can use any metadata field that would be valid in MDX frontmatter except for `openapi`.

```json {7-14} theme={null}
{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "description": "Retrieve a list of users",
        "x-mint": {
          "metadata": {
            "title": "List all users",
            "sidebarTitle": "List users",
            "description": "Fetch paginated user data with filtering options",
            "og:title": "Display a list of users"
          }
        },
        "parameters": [
          {
            // Parameter configuration
          }
        ]
      }
    }
  }
}
```

You can also control playground display per endpoint using the `playground` and `groups` metadata fields:

```json {7-11} theme={null}
{
  "paths": {
    "/admin/users": {
      "post": {
        "summary": "Create admin user",
        "x-mint": {
          "metadata": {
            "playground": "auth",
            "groups": ["admin"],
            "public": true
          }
        }
      }
    }
  }
}
```

This configuration makes the page publicly visible while restricting the interactive playground to authenticated users in the `admin` group.

### Content

Add content before the auto-generated API documentation using `x-mint: content`. The `x-mint: content` extension supports all Mintlify MDX components and formatting.

```json {6-8} theme={null}
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "content": "## Prerequisites\n\nThis endpoint requires admin privileges and has rate limiting.\n\n<Note>User emails must be unique across the system.</Note>"
        },
        "parameters": [
          {
            // Parameter configuration
          }
        ]
      }
    }
  }
}
```

### href

Set the URL of the autogenerated endpoint page using `x-mint: href`. When `x-mint: href` is present, the generated API page uses the specified URL instead of the default autogenerated URL.

```json {6-8, 14-16} theme={null}
{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "Legacy endpoint",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    },
    "/documented-elsewhere": {
      "post": {
        "summary": "Special endpoint",
        "x-mint": {
          "href": "/guides/special-endpoint-guide"
        }
      }
    }
  }
}
```

### Collapse playground fields

Collapse object-type fields in the API playground by default using `x-mint: playground` with `expand: false` on any operation. Request sections like Authorization, Headers, Query, Path, and Body always stay expanded, and so does the top-level body object. Object fields nested within them start collapsed, so readers expand only the fields they want to interact with. If `expand` is not set, object fields are expanded by default.

```json {6-10} theme={null}
{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "x-mint": {
          "playground": {
            "expand": false
          }
        }
      }
    }
  }
}
```

### Parameter pills

Annotate parameters in the API reference and playground with custom pill labels using `x-mint.pre` and `x-mint.post` on any schema. Pills defined with `x-mint.pre` render before the parameter name, and pills defined with `x-mint.post` render after it, alongside Mintlify's built-in pills like `required`, `read-only`, and `write-only`.

Both fields accept an array of strings. Each string becomes its own pill.

```json {7-10} theme={null}
{
  "components": {
    "schemas": {
      "User": {
        "properties": {
          "email": {
            "type": "string",
            "x-mint": {
              "pre": ["PII"],
              "post": ["indexed", "unique"]
            }
          }
        }
      }
    }
  }
}
```

To surface arbitrary OpenAPI spec fields as pills across every parameter without editing each schema, configure [`api.params.post`](/docs/organize/settings-api#api-params) in your `docs.json`. List the field keys you want to display, and Mintlify reads each value from the schema and renders matching pills automatically.

```json theme={null}
{
  "api": {
    "params": {
      "post": ["nullable", "x-internal"]
    }
  }
}
```

With this configuration, a property like `{ "type": "string", "nullable": true, "x-internal": "admin" }` renders `nullable` and `admin` pills next to its name. Post pills appear in this order: built-in pills (`read-only`, `write-only`), then `api.params.post` config-driven pills, then per-property `x-mint.post` pills.

### Group display names

Set a custom display name for a tag's navigation group using the `x-group` extension on a tag object. By default, Mintlify uses the tag `name` as both the navigation group label and the URL path segment. The `x-group` extension overrides the group label while keeping the tag name for the URL.

This is useful when you want a human-readable group name that differs from the tag used in your API paths.

```json {4-9} theme={null}
{
  "tags": [
    {
      "name": "user-management",
      "description": "Endpoints for managing users",
      "x-group": "User Management"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "tags": ["user-management"],
        "summary": "List users"
      }
    }
  }
}
```

In this example, the navigation group displays as "User Management" but the generated page URL still uses the `user-management` tag name as its path segment.

## Auto-populate API pages

Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.

The `openapi` field accepts either a path in your docs repo or a URL to a hosted OpenAPI document. Hosted specs must be reachable from the public internet.

<Tip>
  When you use a URL for your OpenAPI spec, changes to the spec don't trigger a Git push, so your docs won't redeploy automatically. To keep your docs in sync, call the [Trigger deployment](/docs/api/update/trigger) API endpoint in the same CI action that generates or updates your spec. This way your docs update automatically without needing to manually trigger a deployment from the dashboard.
</Tip>

Generated endpoint pages have these default metadata values:

* `title`: The operation's `summary` field, if present. If there is no `summary`, Mintlify generates the title from the HTTP method and endpoint.
* `description`: The operation's `description` field, if present.
* `version`: The `version` value from the parent anchor or tab, if present.
* `deprecated`: The operation's `deprecated` field. If `true`, a deprecated label appears next to the endpoint title in the side navigation and on the endpoint page.

<Tip>
  To exclude specific endpoints from your auto-generated API pages, add the [x-hidden](/docs/api-playground/managing-page-visibility#x-hidden) property to the operation in your OpenAPI spec.
</Tip>

There are two approaches for adding endpoint pages into your documentation:

1. **Dedicated API sections**: Reference OpenAPI specs in navigation elements for dedicated API sections.
2. **Selective endpoints**: Reference specific endpoints in your navigation alongside other pages.

### Dedicated API sections

Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. All endpoints in the specification appear in the generated section.

```json {5} theme={null}
"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}
```

To organize multiple OpenAPI specifications in separate sections of your documentation, assign each specification to a different group in your navigation hierarchy. Each group can reference its own OpenAPI specification.

```json {8-11, 15-18} theme={null}
"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users API",
          "openapi": {
            "source": "/path/to/users-openapi.json",
            "directory": "users-api-reference"
          }
        },
        {
          "group": "Admin API",
          "openapi": {
            "source": "/path/to/admin-openapi.json",
            "directory": "admin-api-reference"
          }
        }
      ]
    }
  ]
}
```

<Note>
  The `directory` field is optional and specifies where Mintlify stores generated API pages in your docs repo. If not specified, it defaults to the `api-reference` directory of your repo.
</Note>

### Selective endpoints

When you want more control over where endpoints appear in your documentation, you can reference specific endpoints in your navigation. This approach lets you generate pages for API endpoints alongside other content. You can also use this approach to mix endpoints from different OpenAPI specifications.

#### Set a default OpenAPI spec

Configure a default OpenAPI specification for a navigation element. Then reference specific endpoints in the `pages` field.

```json {12, 15-16} theme={null}
"navigation": {
  "tabs": [
    {
      "tab": "Getting started",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "api-overview",
        "GET /users",
        "POST /users",
        "guides/authentication"
      ]
    }
  ]
}
```

Any page entry matching the format `METHOD /path` generates an API page for that endpoint using the default OpenAPI specification.

#### OpenAPI spec inheritance

Child navigation elements inherit their parent's OpenAPI specification unless they define their own.

```json {3, 7-8, 11, 13-14} 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"
      ]
    }
  ]
}
```

#### Individual endpoints

Reference specific endpoints without setting a default OpenAPI specification by including the file path. You can reference endpoints from multiple OpenAPI specifications in the same documentation section.

```json {5-6} theme={null}
"navigation": {
  "pages": [
    "introduction",
    "user-guides",
    "/path/to/users-openapi.json POST /users",
    "/path/to/orders-openapi.json GET /orders"
  ]
}
```

This approach is useful when you need individual endpoints from different specifications, only want to include select endpoints, or want to include endpoints alongside other types of documentation.

## Create MDX pages from your OpenAPI specification

For more granular control over individual endpoint pages, create MDX pages from your OpenAPI specification. This lets you customize page metadata, content, and reorder or exclude pages in your navigation while still using the auto-generated parameters and responses.

There are two ways to document your OpenAPI specification with individual MDX pages:

* Document endpoints with the `openapi` field in the frontmatter.
* Document data models with the `openapi-schema` field in the frontmatter.

### Document endpoints

Create a page for each endpoint and specify which OpenAPI operation to display using the `openapi` field in the frontmatter.

<CodeGroup>
  ```mdx Example theme={null}
  ---
  title: "Get users"
  description: "Returns all plants from the system that the user has access to"
  openapi: "/path/to/openapi-1.json GET /users"
  deprecated: true
  version: "1.0"
  ---
  ```

  ```mdx Format theme={null}
  ---
  title: "title of the page"
  description: "description of the page"
  openapi: openapi-file-path method path
  deprecated: boolean (not required)
  version: "version-string" (not required)
  ---
  ```
</CodeGroup>

The method and path must exactly match your OpenAPI spec. If you have multiple OpenAPI specifications, include the path to the correct specification in your reference. You can also reference external OpenAPI URLs in `docs.json`.

<Warning>
  **Always specify the OpenAPI file path when you have multiple OpenAPI specifications in your repository.**

  Mintlify uploads every OpenAPI specification in your docs repository, even if it isn't referenced in `docs.json`. When an MDX page uses `openapi: "METHOD /path"` without a file path, Mintlify searches every uploaded specification for a matching operation. If more than one spec contains the same method and path, the first match wins based on alphabetical filename order, which may not be the spec you expect.

  To avoid ambiguity, do one of the following:

  * Include the spec file path in the frontmatter: `openapi: "path/to/correct-openapi.json POST /v1/endpoint"`.
  * Use [automatic page generation](#auto-populate-api-pages) by referencing the OpenAPI file in `docs.json`, which always maps endpoints to the correct spec.
  * Remove the conflicting path from the other specification.
  * Delete OpenAPI files that are no longer needed from your repository.
</Warning>

#### Autogenerate endpoint pages

To autogenerate MDX files from your OpenAPI specification, use the Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping).

```bash theme={null}
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o <folder-name>
```

<Tip>
  Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files populate in the working directory.
</Tip>

### Document data models

Create a page for each data structure defined in your OpenAPI specification's `components.schemas` using the `openapi-schema` field in the frontmatter.

<CodeGroup>
  ```mdx Example theme={null}
  ---
  openapi-schema: OrderItem
  ---
  ```

  ```mdx Format theme={null}
  ---
  openapi-schema: "openapi-file-path schema-key"
  ---
  ```
</CodeGroup>

If you have schemas with the same name in multiple files, specify the OpenAPI file:

<CodeGroup>
  ```mdx Example theme={null}
  ---
  openapi-schema: en-schema.json OrderItem
  ---
  ```

  ```mdx Format theme={null}
  ---
  openapi-schema: "path-to-schema-file schema-key"
  ---
  ```
</CodeGroup>

## Webhooks

Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. OpenAPI 3.1+ documents support webhooks.

Add a `webhooks` field to your OpenAPI document alongside the `paths` field.

For more information on defining webhooks, see [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks) in the OpenAPI documentation.

To create an MDX page for a webhook (OpenAPI 3.1+), use `webhook` instead of an HTTP method:

```mdx theme={null}
---
title: "Order updated webhook"
description: "Triggered when an order is updated"
openapi: "openapi.json webhook orderUpdated"
---
```

The webhook name must exactly match the key in your OpenAPI spec's `webhooks` field.

## Callbacks

Callbacks describe out-of-band requests that your API sends to a URL provided by the caller, such as event notifications tied to a specific operation. When an OpenAPI operation defines `callbacks`, Mintlify renders them on the endpoint page in a collapsible section between the request body and response sections. Each callback shows its HTTP method and expression, and reuses the same body and response components as the parent operation.

For more information on defining callbacks, see [Callbacks](https://spec.openapis.org/oas/v3.1.0#callback-object) in the OpenAPI documentation.

Define callbacks on the operation in your OpenAPI spec:

```yaml theme={null}
paths:
  /subscribe:
    post:
      summary: Subscribe to events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callbackUrl:
                  type: string
                  format: uri
      responses:
        "201":
          description: Subscription created
      callbacks:
        orderUpdated:
          "{$request.body#/callbackUrl}":
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        orderId:
                          type: string
                        status:
                          type: string
              responses:
                "200":
                  description: Callback received
```


## Related topics

- [API playground overview](/docs/api-playground/overview.md)
- [Navigation](/docs/organize/navigation.md)
- [Migrate from another platform](/docs/migration/manual.md)