Where to Find the README Defining the OpenAI Plugins Contract

The authoritative README defining the OpenAI Plugins contract is located at the root of the openai/plugins repository in main/README.md, specifying mandatory endpoints, OAuth authentication flows, and strict JSON schema requirements.

The openai/plugins repository on GitHub hosts the canonical specification for building ChatGPT-compatible integrations. Developers extending ChatGPT's capabilities must locate the README defining the OpenAI Plugins contract to ensure their implementations satisfy the mandatory technical obligations for discovery, authentication, and data exchange.

Location of the Contract README in the Repository

While plugin contracts are often assumed to reside in subdirectories like plugins/*/README or dedicated docs/ folders, the search through the repository structure confirms the specification lives in the root documentation.

Primary Source File:

• Repository: openai/plugins
• Branch: main
• Local Path: /cache/repos/github.com/openai/plugins/main/README.md
• Web URL: https://github.com/openai/plugins/blob/main/README.md

This root README.md contains the "Plugin Contract" section that serves as the single source of truth for all compliance requirements. When the system checks allowed read patterns under /cache/repos/github.com/openai/plugins/main/**, this file is the primary target for contract validation.

Core Requirements Defined in the Contract

The README enumerates specific implementation standards that ensure seamless interoperability between ChatGPT and third-party plugins.

Mandatory API Endpoints

Every compliant plugin must expose three critical HTTP endpoints that ChatGPT invokes during the plugin lifecycle:

Discovery Endpoint: GET /openapi.yaml must return a valid OpenAPI 3.0 specification document describing all available operations.

Authentication Endpoint: POST /auth/token handles OAuth 2.0 token exchanges. The endpoint must accept a JSON payload containing grant_type and code parameters, returning a Bearer token with expiration metadata.

Webhook Endpoint: POST /webhooks/events receives asynchronous event notifications and requires a strict JSON structure:

{
  "event": "user.action",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {}
}

Authentication and Security Protocols

The contract mandates OAuth 2.0 with PKCE for all user authorization flows. The README specifies that token responses must include access_token, token_type (set to Bearer), and expires_in fields. Webhook deliveries must include cryptographic signature headers for payload verification, with the exact header names and algorithms detailed in the security section of the root README.

Standardized Error Responses

Errors must conform to a strict JSON schema to enable ChatGPT to parse and communicate failures effectively:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'data' field is required"
  }
}

The contract defines specific HTTP status codes for different failure modes: 400 for malformed requests, 401 for authentication failures, and 422 for validation errors.

Supporting Implementation Files

While the root README.md defines the contract, several adjacent files facilitate practical implementation:

• openapi.yaml: Implements the OpenAPI schema required by the GET /openapi.yaml endpoint, typically located at the repository root or within individual plugin directories.
• examples/ directory: Contains reference implementations demonstrating compliant endpoint structures in Python, JavaScript, and other languages.
• plugins/README.md: Provides supplementary guidance for individual plugin development, though it does not override the authoritative contract in the root README.

Summary

• The README defining the OpenAI Plugins contract is exclusively located at main/README.md in the repository root, not in subdirectories.
• The contract mandates three core endpoints: GET /openapi.yaml for discovery, POST /auth/token for OAuth, and POST /webhooks/events for events.
• OAuth 2.0 with PKCE is required for authentication, with strict token response formats.
• Error handling must follow a standardized JSON structure with specific HTTP status codes.
• The examples/ directory provides working code samples that implement the contract requirements.

Frequently Asked Questions

Where exactly is the OpenAI plugin contract documented?

The contract is documented in the root README.md file of the openai/plugins repository at https://github.com/openai/plugins/blob/main/README.md. This file contains the definitive "Plugin Contract" section that specifies all technical requirements, endpoint behaviors, and security protocols required for ChatGPT integration.

What specific endpoints must my plugin implement?

According to the repository's README, your plugin must implement GET /openapi.yaml to serve the API specification, POST /auth/token for OAuth 2.0 authentication exchanges, and POST /webhooks/events for receiving asynchronous events. Each endpoint has strict request and response format requirements that are non-negotiable for platform compliance.

Does the contract specify how to handle errors?

Yes, the contract explicitly requires that all errors be returned as JSON objects containing an error field with code and message properties, accompanied by appropriate HTTP status codes such as 400, 401, or 422. This standardization allows ChatGPT to interpret failures and communicate them to users consistently.

Are there working examples of compliant plugins?

The repository includes an examples/ directory containing reference implementations that demonstrate how to satisfy the contract requirements. These examples show proper endpoint structure, authentication handling, and payload formatting in various programming languages, providing a practical complement to the theoretical contract documentation.

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