# OpenAI Plugin Manifest File: Complete Guide to Key Fields and Schema

> Master the OpenAI plugin manifest with our guide. Understand crucial fields like schema_version name_for_human description_for_human auth and api for seamless ChatGPT integration.

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

---

**An OpenAI plugin manifest ([`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)) requires seven core fields—`schema_version`, `name_for_human`, `name_for_model`, `description_for_human`, `description_for_model`, `auth`, and `api`—to define the plugin's identity, capabilities, and authentication model for ChatGPT integration.**

The `openai/plugins` repository hosts reference implementations demonstrating how to structure ChatGPT plugins. At the heart of every plugin sits the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest file, which serves as the contract between your API and the ChatGPT platform, describing exactly how the model should discover, authenticate, and interact with your service.

## Required Fields in the OpenAI Plugin Manifest

### Schema Version and Identity

The `schema_version` field declares which manifest specification version the plugin targets, typically `"v1"`. The `name_for_human` field provides the user-facing display name rendered in the ChatGPT UI, while `name_for_model` supplies a concise, machine-readable identifier (camelCase or snake_case) that the LLM references during function calling.

### Descriptions for Human and Model

The `description_for_human` field offers a brief, user-facing explanation of functionality, whereas `description_for_model` provides crucial machine-readable instructions that guide the AI on when and how to invoke your plugin's capabilities. This distinction ensures both users and the language model understand the plugin's purpose.

### Authentication and API Configuration

The `auth` object defines the security model through its `type` property, supporting four values: `"none"`, `"service_http"`, `"user_http"`, or `"oauth"`. OAuth configurations require additional fields including `client_id`, `authorization_url`, and `token_url`. The `api` field must contain a `type` (always `"openapi"`) and a `url` pointing to your OpenAPI specification.

## Optional Metadata Fields

Beyond the required schema, optional fields enhance discoverability and compliance. The `logo_url` specifies an HTTPS path to a 512x512 icon displayed in the UI. The `contact_email` provides a support address for plugin authors, and `legal_info_url` links to terms of service or privacy policies required for marketplace distribution.

## Real-World Examples from the OpenAI Plugins Repository

The `openai/plugins` repository contains canonical implementations in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) files that illustrate these fields in production contexts.

### OAuth-Protected Service

In [`plugins/figma/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.codex-plugin/plugin.json), the manifest implements OAuth authentication with complete metadata:

```json
{
  "schema_version": "v1",
  "name_for_human": "Figma Design Assistant",
  "name_for_model": "figma",
  "description_for_human": "Create and edit Figma designs from ChatGPT.",
  "description_for_model": "Allows the model to add components, frames, and assets to a Figma file.",
  "auth": {
    "type": "oauth",
    "client_id": "YOUR_CLIENT_ID",
    "authorization_url": "https://www.figma.com/oauth",
    "token_url": "https://www.figma.com/api/token"
  },
  "api": { "type": "openapi", "url": "https://raw.githubusercontent.com/openai/plugins/main/plugins/figma/openapi.yaml" },
  "logo_url": "https://raw.githubusercontent.com/openai/plugins/main/plugins/figma/assets/app-icon.png",
  "contact_email": "support@figma.com",
  "legal_info_url": "https://www.figma.com/legal"
}

```

### No Authentication

The [`plugins/mem/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/mem/.codex-plugin/plugin.json) pattern demonstrates the minimal configuration for public APIs requiring no authentication:

```json
{
  "schema_version": "v1",
  "name_for_human": "Simple Weather",
  "name_for_model": "weather",
  "description_for_human": "Get current weather information.",
  "description_for_model": "Provides real-time weather data for a given city.",
  "auth": { "type": "none" },
  "api": { "type": "openapi", "url": "https://example.com/openapi.yaml" }
}

```

### Service HTTP Authentication

According to the source analysis, [`plugins/notion/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/notion/.codex-plugin/plugin.json) illustrates the `service_http` authentication type, where the plugin includes a static API key in request headers for backend-to-backend communication.

## Summary

- An OpenAI plugin manifest requires `schema_version`, `name_for_human`, `name_for_model`, `description_for_human`, `description_for_model`, `auth`, and `api` fields to function
- The `auth` field supports four types: `none`, `oauth`, `service_http`, and `user_http`, with OAuth requiring additional endpoint URLs
- The `api` field must specify `type: "openapi"` and provide a valid URL to the OpenAPI specification document
- Optional fields like `logo_url`, `contact_email`, and `legal_info_url` improve user trust and platform compliance
- Reference implementations in `openai/plugins` demonstrate proper field usage across different authentication patterns

## Frequently Asked Questions

### What is the difference between name_for_human and name_for_model?

The `name_for_human` field provides the display name shown in the ChatGPT UI, while `name_for_model` supplies a concise, machine-readable identifier that the LLM uses to reference the plugin during conversation and function calling.

### Does the OpenAI plugin manifest support authentication methods other than OAuth?

Yes, according to the `openai/plugins` source code, the `auth` field accepts four types: `"none"` for public APIs, `"service_http"` for static API keys, `"user_http"` for per-user credentials, and `"oauth"` for full OAuth 2.0 flows.

### Where must the OpenAPI specification URL point in the manifest?

The `api.url` field must provide an absolute HTTPS URL pointing to your OpenAPI specification file, typically hosted at [`/.well-known/openapi.yaml`](https://github.com/openai/plugins/blob/main//.well-known/openapi.yaml) or similar public endpoints accessible to the ChatGPT platform.

### Are logo_url and contact_email required fields in plugin.json?

No, these are optional metadata fields. However, including `logo_url`, `contact_email`, and `legal_info_url` is recommended as they improve user trust and are often required for publication in the ChatGPT plugin store.