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

> Discover what a plugin manifest file is and what it contains. Learn how this JSON descriptor guides OpenAI's runtime for plugin discovery, authentication, and communication.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: documentation
- Published: 2026-09-10

---

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

```python
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:

```http
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`](https://github.com/openai/plugins/blob/main/plugins/notion/.codex-plugin/plugin.json) |
| **Zotero** | [`plugins/zotero/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zotero/.codex-plugin/plugin.json) |
| **MagicPath** | [`plugins/magicpath/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/magicpath/.codex-plugin/plugin.json) |
| **Life-Science-Research** | [`plugins/life-science-research/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json) and redeploy the plugin to force the runtime to reload the configuration from disk.