# Where to Find the README Defining the OpenAI Plugins Contract

> Locate the official OpenAI Plugins contract README in the openai plugins repository. Discover mandatory endpoints, OAuth flows, and JSON schema rules.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: getting-started
- Published: 2026-09-12

---

**The authoritative README defining the OpenAI Plugins contract is located at the root of the `openai/plugins` repository in [`main/README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main//cache/repos/github.com/openai/plugins/main/README.md)
- **Web URL:** `https://github.com/openai/plugins/blob/main/README.md`

This root [`README.md`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/README.md) defines the contract, several adjacent files facilitate practical implementation:

- **[`openapi.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.