OpenAI Plugin Manifest File Structure: Complete Schema Guide

An OpenAI plugin manifest file is a JSON descriptor located at .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 and placed inside a .codex-plugin subdirectory.

For example, the Zoom plugin's manifest is located at: plugins/zoom/.codex-plugin/plugin.json

Other plugins follow the same pattern:

• plugins/vercel/.codex-plugin/plugin.json
• plugins/wix/.codex-plugin/plugin.json
• 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:

{
  "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"
}

Production Example: Zoom Plugin

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

{
  "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 file is located at 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:

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 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 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.

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.

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