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

An OpenAI plugin manifest (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 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 files that illustrate these fields in production contexts.

OAuth-Protected Service

In plugins/figma/.codex-plugin/plugin.json, the manifest implements OAuth authentication with complete metadata:

{
  "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 pattern demonstrates the minimal configuration for public APIs requiring no authentication:

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

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