What Is a Plugin Manifest File and What Does It Contain?

A plugin manifest file is a static JSON descriptor that tells the OpenAI runtime how to discover, authenticate, and communicate with a plugin.

In the openai/plugins repository, every plugin ships with a manifest located at plugins/<name>/.codex-plugin/plugin.json. This file acts as the contract between the platform and the plugin, defining available endpoints, required permissions, and presentation metadata.

Location and Naming Convention

Each plugin directory contains a hidden .codex-plugin folder that houses the manifest. The file is always named plugin.json. For example, the Notion plugin’s manifest lives at:

plugins/notion/.codex-plugin/plugin.json

The runtime scans these paths at startup to build an internal registry of available capabilities.

Core Schema and Required Fields

The manifest follows a strict schema that divides configuration into identity, API definition, security, and metadata blocks.

Identity and Versioning

• name: Human-readable identifier (e.g., "Notion").
• description: Concise summary of functionality.
• version: Semantic version string (e.g., "0.1.0").
• author: Entity responsible for maintenance.

API Specification

• api:
  • url: Base URL for all plugin endpoints.
  • openapi: Relative path or URL to the OpenAPI specification that defines valid routes and request schemas.

Authentication and Security

• auth:
  • type: Protocol such as oauth, api_key, or none.
  • client_id, scopes: OAuth-specific fields defining token exchange URLs and permission scopes.
  • headers: Custom headers required for every request.

Presentation and Compliance

• logo_url: HTTPS URL to a square icon displayed in UI listings.
• contacts: Array of support objects containing email or URLs for troubleshooting.
• privacy_policy_url and terms_of_service_url: Links to legal documents governing data handling.
• capabilities: Optional array of flags such as "file_upload" or "streaming" that enable platform features.
• settings: Plugin-specific configuration keys that users can override at runtime.

Runtime Behavior and Caching

The platform treats the manifest as immutable configuration. It reads the file once during startup, validates the JSON schema, and caches the parsed object in memory. Because the runtime does not poll for changes, updating a manifest requires:

1. Committing the modified plugin.json.
2. Bumping the version field to trigger a cache invalidation.
3. Restarting the plugin service to reload the registry.

Loading and Registering Manifests Programmatically

You can inspect a manifest locally using standard JSON parsing libraries.

import json
from pathlib import Path

# Load the Notion plugin manifest

manifest_path = Path("plugins/notion/.codex-plugin/plugin.json")
manifest = json.loads(manifest_path.read_text())

# Extract routing and auth details

print(f"Plugin: {manifest['name']} v{manifest['version']}")
print(f"API Base: {manifest['api']['url']}")
print(f"Auth Type: {manifest['auth']['type']}")

To register a plugin with the OpenAI runtime, provide the raw GitHub URL to the manifest:

POST https://api.openai.com/v1/plugins/register
Content-Type: application/json

{
  "manifest_url": "https://raw.githubusercontent.com/openai/plugins/main/plugins/notion/.codex-plugin/plugin.json"
}

Real-World Manifest Locations in openai/plugins

The following table maps popular plugins to their manifest paths within the repository:

Plugin	Manifest Path
Notion	plugins/notion/.codex-plugin/plugin.json
Zotero	plugins/zotero/.codex-plugin/plugin.json
MagicPath	plugins/magicpath/.codex-plugin/plugin.json
Life-Science-Research	plugins/life-science-research/.codex-plugin/plugin.json

These files exemplify the full schema described above and serve as authoritative references when building custom plugins.

Summary

• A plugin manifest file is a JSON configuration stored at plugins/<name>/.codex-plugin/plugin.json in the openai/plugins repository.
• It defines the plugin’s identity, API endpoints, authentication flow, and legal metadata.
• The runtime reads the manifest once at startup and caches it; changes require a version bump and service restart.
• You can programmatically load manifests using standard HTTP or file-system JSON parsers.
• Concrete examples are available in the Notion, Zotero, and MagicPath plugin directories.

Frequently Asked Questions

What file format does the plugin manifest use?

The manifest is a UTF-8 encoded JSON file. It must be valid JSON and follow the schema expected by the OpenAI runtime, including required top-level keys such as name, api, and auth.

Where is the manifest located in the openai/plugins repository?

Each plugin stores its manifest inside a hidden .codex-plugin directory within its respective folder. The full path follows the pattern plugins/<plugin-name>/.codex-plugin/plugin.json, as seen in plugins/notion/.codex-plugin/plugin.json.

How does authentication work in the plugin manifest?

The auth block specifies the security protocol. For OAuth 2.0, it includes type: "oauth", token endpoint URLs, client_id, and required scopes. For simple API keys, it may specify type: "api_key" and a custom header name. The runtime uses this configuration to manage token refresh and request signing.

What happens when I update a manifest file?

Because the platform caches the manifest at startup, updates are not picked up dynamically. You must increment the version field in plugin.json and redeploy the plugin to force the runtime to reload the configuration from disk.

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