OpenAPI Schema for OpenAI Plugins: Complete Structure and Required Extensions

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:

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:

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 demonstrates how a plugin consumes external OpenAPI specifications to generate client code.
• Vercel Firewall: In 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 file illustrates linking to an external openapi.json file hosted elsewhere.
• Cloudflare Workers: Found in 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.

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. As shown in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}