What Is the Manifest File for an OpenAI Plugin? Structure, Examples, and Usage

The manifest file for an OpenAI plugin is a JSON descriptor located at .codex-plugin/plugin.json that defines the plugin's metadata, API endpoints, authentication method, and optional function mappings, enabling the OpenAI platform to load the plugin and allowing ChatGPT to invoke its capabilities securely.

The openai/plugins repository contains the official collection of Codex plugins, each configured through a standardized manifest file. This JSON file serves as the authoritative source of truth that tells the OpenAI platform how to validate, display, and execute plugin functionality.

Understanding the OpenAI Plugin Manifest Structure

The manifest file follows a strict schema (currently version "v1") that the OpenAI platform validates during plugin submission and uses at runtime to generate assistant-side function calls.

Required Core Fields

Every manifest must include these fields:

• name: Human-readable identifier of the plugin (e.g., "zoom").
• description: Short text shown to users in the ChatGPT UI.
• api: Object specifying the API type (openapi) and URL to the OpenAPI specification.
• auth: Authentication configuration with type (none, oauth, api_key, etc.).
• logo_url: URL of the plugin's logo for display in the interface.
• contact_email: Support email address for the plugin.
• legal_info_url: Link to terms of service and privacy policy.
• schema_version: Version of the manifest schema (currently "v1").

Optional Function Definitions

The optional functions field contains function objects that map ChatGPT calls directly to the plugin's API endpoints. When present, these definitions allow the model to generate structured JSON requests that match the plugin's API contract, enabling secure and precise execution of plugin capabilities.

Where the Manifest File Lives in the Repository

In the openai/plugins repository, every plugin stores its manifest at a standardized location:

<plugin-directory>/.codex-plugin/plugin.json

For example, the Zoom plugin's manifest is located at plugins/zoom/.codex-plugin/plugin.json, while the Vercel plugin uses plugins/vercel/.codex-plugin/plugin.json. This consistent structure across approximately 70 plugins in the repository allows automated tools to discover and load plugin configurations programmatically.

How the Manifest Is Used by the Platform

The OpenAI platform interacts with the manifest file in three distinct phases:

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

OpenAI Plugin Manifest Examples

Minimal Manifest Configuration

The following JSON represents the smallest valid manifest for a plugin with no authentication:

{
  "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": "[email protected]",
  "legal_info_url": "https://example.com/terms"
}

Real-World Zoom Plugin Manifest

The Zoom plugin demonstrates OAuth authentication and production-ready configuration:

{
  "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": "[email protected]",
  "legal_info_url": "https://zoom.us/terms"
}

This manifest is located at plugins/zoom/.codex-plugin/plugin.json in the repository.

Loading the Manifest Programmatically

You can load and parse the manifest file using standard filesystem operations. Here is a Node.js example that reads the manifest from the Zoom plugin directory:

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"

Summary

• The manifest file is a JSON descriptor at .codex-plugin/plugin.json that defines plugin metadata, API specifications, and authentication methods.
• The current schema_version is "v1", which validates fields including name, description, api, auth, logo_url, contact_email, and legal_info_url.
• The functions field optionally maps ChatGPT calls to specific plugin API endpoints.
• OpenAI uses the manifest during submission, discovery, and execution phases to validate, display, and run plugins.
• All plugins in the openai/plugins repository follow the <plugin>/.codex-plugin/plugin.json path convention.

Frequently Asked Questions

What schema version does the OpenAI plugin manifest use?

The OpenAI plugin manifest currently uses schema version "v1", as specified in the schema_version field. This version validates required fields such as name, description, api, auth, logo_url, contact_email, and legal_info_url.

Where should I place the manifest file in my OpenAI plugin directory structure?

You must place the manifest file at .codex-plugin/plugin.json within your plugin's root directory. For example, if your plugin is named "my-plugin", the full path would be my-plugin/.codex-plugin/plugin.json. This convention is used by all plugins in the openai/plugins repository.

How does authentication configuration work in the OpenAI plugin manifest?

The auth field specifies the authentication type, which can be none, oauth, api_key, or other supported methods. For OAuth authentication, you must include additional fields such as client_url and token_url to define the authorization and token endpoints, as demonstrated in the Zoom plugin manifest.

Can I define custom function mappings in the OpenAI plugin manifest?

Yes, the optional functions field allows you to define function objects that map ChatGPT calls to your plugin's API endpoints. These definitions enable the model to generate structured JSON requests that match your API contract, allowing ChatGPT to invoke your plugin's capabilities securely and precisely.

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