# OpenAI Plugin Manifest File Structure: Complete Schema Guide

> Understand the OpenAI plugin manifest file structure. This guide details the complete schema for plugin name API endpoints authentication and metadata enabling ChatGPT discovery and invocation.

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

---

**An OpenAI plugin manifest file is a JSON descriptor located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) that defines the plugin's name, API endpoints, authentication method, and metadata required for ChatGPT to discover and invoke the plugin.**

The `openai/plugins` repository hosts the reference implementations for ChatGPT integrations, with each plugin defined by a standardized manifest. This JSON configuration acts as the contract between external APIs and the OpenAI platform, specifying exactly how the assistant should interact with third-party services. Every plugin in the repository follows the schema defined in the manifest to enable secure, automated function calling.

## Manifest File Location and Naming Convention

Every plugin in the `openai/plugins` repository stores its manifest at a fixed path within the plugin directory. The file must be named [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and placed inside a `.codex-plugin` subdirectory.

For example, the Zoom plugin's manifest is located at:
[`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json)

Other plugins follow the same pattern:
- [`plugins/vercel/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json)
- [`plugins/wix/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/wix/.codex-plugin/plugin.json)
- [`plugins/supabase/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/supabase/.codex-plugin/plugin.json)

Approximately 70 plugins in the repository adhere to this structure, making the manifest the authoritative source of truth for each integration.

## Required Manifest Schema Fields

The manifest defines nine standard fields that the OpenAI platform validates during submission and uses at runtime to generate assistant-side function calls.

### Core Metadata Fields

- **`name`**: Human-readable identifier of the plugin (e.g., `"zoom"`).
- **`description`**: Short text shown to users describing the plugin's capabilities.
- **`schema_version`**: Version of the manifest schema. Currently must be set to `"v1"`.

### API and Authentication Configuration

- **`api`**: Object specifying the OpenAPI specification or custom endpoints. Contains `type` (e.g., `"openapi"`) and `url` pointing to the specification file.
- **`auth`**: Object defining the authentication method. Valid types include `"none"`, `"oauth"`, `"api_key"`, and others. OAuth configurations include `client_url` and `token_url` fields.

### Branding and Legal Fields

- **`logo_url`**: URL of the plugin's logo displayed in the ChatGPT UI.
- **`contact_email`**: Support email address for the plugin.
- **`legal_info_url`**: Link to the plugin's terms of service and privacy policy.

### Optional Function Definitions

- **`functions`**: Optional array of function objects that map ChatGPT calls directly to specific plugin API endpoints. When provided, these enable the model to generate precise JSON requests matching the plugin's capabilities.

## Real-World Manifest Examples

### Minimal Plugin Configuration

The simplest valid manifest requires only the essential fields:

```json
{
  "schema_version": "v1",
  "name": "my-plugin",
  "description": "A simple example plugin",
  "api": {
    "type": "openapi",
    "url": "https://example.com/openapi.yaml"
  },
  "auth": {
    "type": "none"
  },
  "logo_url": "https://example.com/logo.png",
  "contact_email": "support@example.com",
  "legal_info_url": "https://example.com/terms"
}

```

### Production Example: Zoom Plugin

The Zoom plugin demonstrates a production-ready manifest with OAuth authentication:

```json
{
  "name": "zoom",
  "description": "Interact with Zoom meetings, recordings, and users",
  "api": {
    "type": "openapi",
    "url": "https://api.zoom.us/v2/openapi.yaml"
  },
  "auth": {
    "type": "oauth",
    "client_url": "https://zoom.us/oauth/authorize",
    "token_url": "https://zoom.us/oauth/token"
  },
  "logo_url": "https://example.com/zoom-logo.png",
  "contact_email": "support@zoom.us",
  "legal_info_url": "https://zoom.us/terms"
}

```

This file is located at [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json) in the repository.

## How the Manifest Is Used at Runtime

The OpenAI platform processes the manifest in three distinct phases:

1. **Submission**: When a developer registers a plugin, OpenAI reads the manifest to verify required fields, scopes, and authentication flow.
2. **Discovery**: The platform publishes the plugin's name, description, and logo to the ChatGPT UI, allowing users to enable the integration.
3. **Execution**: When a user requests an action covered by the manifest, the model generates a JSON request matching the `functions` definitions. The backend then calls the corresponding API endpoint defined in the `api` field.

## Programmatically Loading the Manifest

Developers can read and parse the manifest using standard file system operations. The following Node.js example demonstrates how to load a plugin's configuration dynamically:

```javascript
import { readFile } from 'node:fs/promises';

async function loadManifest(pluginPath) {
  const manifestPath = `${pluginPath}/.codex-plugin/plugin.json`;
  const raw = await readFile(manifestPath, 'utf8');
  return JSON.parse(raw);
}

// Example usage
const manifest = await loadManifest('plugins/zoom');
console.log(manifest.name);   // → "zoom"

```

This approach validates that the file exists at the expected path before parsing the JSON schema.

## Summary

- The OpenAI plugin manifest file is a JSON descriptor located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) within each plugin directory.
- **Required fields** include `name`, `description`, `api`, `auth`, `logo_url`, `contact_email`, `legal_info_url`, and `schema_version` (currently `"v1"`).
- The `functions` field is optional but enables precise mapping between ChatGPT calls and plugin endpoints.
- Authentication supports multiple types including `none`, `oauth`, and `api_key`, with OAuth requiring additional `client_url` and `token_url` fields.
- The manifest serves as the source of truth for plugin submission, discovery in the ChatGPT UI, and runtime execution of assistant function calls.

## Frequently Asked Questions

### What is the exact file path for an OpenAI plugin manifest?

The manifest must be located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) relative to the plugin root directory. For example, in the `openai/plugins` repository, the Zoom plugin manifest is stored at [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json).

### What authentication types does the manifest schema support?

The `auth.type` field accepts `"none"`, `"oauth"`, `"api_key"`, and other authentication methods. When using OAuth, you must also specify `client_url` and `token_url` fields to define the authorization and token exchange endpoints.

### Is the functions field required in the manifest file?

No, the `functions` field is optional. However, when provided, it explicitly maps ChatGPT function calls to specific plugin API endpoints, allowing the model to generate precise JSON requests that match the plugin's capabilities.

### How does ChatGPT use the manifest to call plugin APIs?

During execution, ChatGPT reads the manifest's `api` and `functions` definitions to generate structured JSON requests. When a user asks for an action covered by the plugin, the assistant constructs a request matching the manifest schema, which the OpenAI backend then routes to the appropriate API endpoint defined in the manifest.