# OpenAPI Schema for OpenAI Plugins: Complete Structure and Required Extensions

> Discover the complete OpenAPI schema for OpenAI plugins. Learn about required fields and essential x OpenAI extensions like x openai api type for ChatGPT integration.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: api-reference
- Published: 2026-07-12

---

**OpenAI plugins require a valid OpenAPI 3.0 specification that includes standard fields like `openapi`, `info`, and `paths`, plus OpenAI-specific extensions such as `x-openai-api-type` and `x-openai-description` to enable ChatGPT to discover and invoke API endpoints.**

When building a plugin for the OpenAI ecosystem, the OpenAPI specification serves as the foundational contract between your API and ChatGPT. According to the `openai/plugins` repository, every plugin must expose a valid OpenAPI 3.0 document that defines available operations, authentication schemes, and request schemas, augmented with proprietary extensions that help the model understand how to invoke each endpoint.

## Required Core Schema Fields

The OpenAPI document must conform to the OpenAPI 3.0 specification with these mandatory top-level fields:

- **openapi**: Must be the string `"3.0.0"` or any later 3.x version.
- **info**: An object containing `title`, `description`, and `version` metadata.
- **paths**: A required object mapping HTTP paths to operation objects, where each operation must include:
  - `operationId` (unique string identifier)
  - `description` (human-readable explanation)
  - `responses` (at least a `200` response definition)

Optional standard fields include `servers` (base URL array), `components` (reusable schemas), and `security` (global authentication requirements).

## OpenAI-Specific Extensions

To integrate with ChatGPT, the specification must include custom extensions within operation objects:

- **x-openai-api-type**: Indicates the endpoint category, such as `"function"` for callable operations.
- **x-openai-description**: A concise description displayed to users when the model suggests using the plugin.
- **x-openai-parameters**: Optional mapping that connects API parameters to the plugin UI.

For endpoints that will be invoked as function calls from ChatGPT, the operation must contain `x-openai-api-type: "function"` and define the request body schema under `requestBody.content.application/json.schema`.

## Authentication Requirements

The OpenAPI spec must reference security schemes that match the plugin's authentication configuration. For example, if using API key authentication, the spec should define:

```yaml
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
security:
  - ApiKeyAuth: []

```

The security scheme defined here must align with the `auth` configuration specified in the plugin manifest.

## Complete OpenAPI Example

Below is a minimal specification from the repository that satisfies OpenAI plugin requirements:

```yaml
openapi: 3.0.0
info:
  title: Example Search Plugin
  description: Provides search capabilities over a custom knowledge base.
  version: "1.0"
servers:
  - url: https://api.example.com/v1
paths:
  /search:
    post:
      operationId: search
      x-openai-api-type: function
      x-openai-description: "Searches the knowledge base."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: "Search query"
              required:
                - query
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: string
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
security:
  - ApiKeyAuth: []

```

## Implementation Examples from the Repository

The `openai/plugins` repository contains several reference implementations demonstrating how to structure and reference OpenAPI specifications:

- **Zoom Plugin**: The file [`plugins/zoom/skills/rest-api/references/openapi.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/openapi.md) demonstrates how a plugin consumes external OpenAPI specifications to generate client code.
- **Vercel Firewall**: In [`plugins/vercel/skills/vercel-firewall/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-firewall/SKILL.md), the plugin embeds an inline `$schema` reference to a Vercel-provided OpenAPI JSON document.
- **Replay QA API**: The [`plugins/replayio/skills/replay-qa-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/replayio/skills/replay-qa-api/SKILL.md) file illustrates linking to an external [`openapi.json`](https://github.com/openai/plugins/blob/main/openapi.json) file hosted elsewhere.
- **Cloudflare Workers**: Found in [`plugins/cloudflare/skills/cloudflare/references/workers/frameworks.md`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/skills/cloudflare/references/workers/frameworks.md), this example shows using the `@hono/zod-openapi` library to dynamically serve an OpenAPI spec at [`/openapi.json`](https://github.com/openai/plugins/blob/main//openapi.json).

## Summary

- OpenAI plugins require a valid **OpenAPI 3.0** specification as the API contract.
- Required fields include `openapi`, `info`, and `paths`, with each operation needing an `operationId` and `description`.
- **OpenAI-specific extensions** (`x-openai-api-type`, `x-openai-description`) are mandatory for ChatGPT integration.
- Authentication schemes defined in the spec must align with the plugin's security configuration.
- Real-world examples in the `openai/plugins` repository demonstrate both inline and externally referenced specifications.

## Frequently Asked Questions

### What version of OpenAPI does OpenAI require for plugins?

OpenAI plugins require **OpenAPI 3.0.0** or any later 3.x version. Specifications using OpenAPI 2.0 (Swagger) are not supported and must be upgraded to version 3.0 or higher to ensure compatibility with the ChatGPT plugin system.

### Where does the OpenAPI specification file live in a plugin project?

The specification can be hosted externally and referenced via URL in the plugin manifest, or served dynamically from an endpoint like [`/openapi.json`](https://github.com/openai/plugins/blob/main//openapi.json). As shown in [`plugins/vercel/skills/vercel-firewall/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-firewall/SKILL.md), some plugins embed the schema inline, while others like the Replay QA plugin link to external [`openapi.json`](https://github.com/openai/plugins/blob/main/openapi.json) files.

### What is the purpose of the x-openai-api-type extension?

The `x-openai-api-type` extension identifies the endpoint category to ChatGPT. When set to `"function"`, it indicates that the endpoint can be invoked as a function call by the model, enabling the plugin to perform actions or retrieve data based on the conversation context.

### Does the OpenAPI spec need to include every possible endpoint of my API?

No. The specification should only include the endpoints you want to expose to ChatGPT. According to patterns in the repository, you should define a focused subset of operations that are safe and useful for conversational AI interactions, rather than exposing your entire API surface.