What Information Does the OpenAI plugin.json Manifest File Contain?

The plugin.json manifest file contains the core descriptor fields—including metadata, authentication configuration, and API binding details—that enable the OpenAI system to display, authenticate, and invoke your plugin.

The plugin.json file serves as the canonical manifest within the openai/plugins repository, defining how the ChatGPT runtime discovers and interacts with external tools. According to the source tree, this JSON schema bridges human-facing UI elements with the machine-readable specifications required for model decision-making and API routing.

Core Metadata Fields

The manifest supplies identification and descriptive fields that control how the plugin appears to both users and the language model:

• schema_version: A string specifying the manifest schema version, currently "v1" as implemented in the repository.
• name_for_human: A user-friendly name displayed in the ChatGPT UI (e.g., "Google Drive").
• name_for_model: A concise, snake_case identifier that the model references when deciding to invoke the plugin (e.g., google_drive).
• description_for_human: A detailed explanation of the plugin's functionality for end users.
• description_for_model: A concise summary that the LLM uses to determine when to activate the plugin during conversations.

Authentication Configuration

The auth object describes how the plugin authenticates requests between the model, user, and your backend. The schema supports three distinct authentication types:

• type: Specifies the method as "none" for public APIs, "service_http" for API-key based authentication, or "oauth" for OAuth 2.0 flows.
• OAuth-specific fields: When the type is "oauth", the object requires client_id, client_secret, authorization_url, token_url, scopes, and instructions_url.
• Service HTTP fields: For "service_http", the configuration typically includes authentication headers or tokens without the full OAuth handshake.

This configuration enables the model to act on behalf of users while keeping credentials secure and outside the conversation context.

API Specification Binding

The api object links the manifest to its OpenAPI specification, defining how the ChatGPT system routes function calls to your endpoints:

• type: Always set to "openapi" to indicate the specification format.
• url: The absolute URL to the openapi.yaml or openapi.json file describing available endpoints, parameters, and responses.
• is_user_authenticated: A boolean flag indicating whether the API requires user-specific tokens, distinct from the plugin-level authentication.

Optional Branding and Legal Fields

Additional fields enhance presentation and compliance:

• logo_url: A HTTPS URL pointing to a square icon displayed in the ChatGPT UI.
• contact_email: A support address for users encountering issues with the plugin.
• legal_info_url: Link to terms of service and privacy policy documentation.
• homepage_url: The plugin's primary website or documentation landing page.

Example Manifest Structure

Below is a complete example demonstrating a fictional "Todoist" plugin configuration, as structured in the repository documentation:

{
  "schema_version": "v1",
  "name_for_human": "Todoist",
  "name_for_model": "todoist",
  "description_for_human": "Create, read, and update your Todoist tasks.",
  "description_for_model": "Allows management of Todoist tasks.",
  "auth": {
    "type": "oauth",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "authorization_url": "https://todoist.com/oauth/authorize",
    "token_url": "https://todoist.com/oauth/access_token",
    "scopes": ["data:read_write"],
    "instructions_url": "https://example.com/auth-instructions"
  },
  "api": {
    "type": "openapi",
    "url": "https://example.com/openapi.yaml",
    "is_user_authenticated": true
  },
  "logo_url": "https://example.com/logo.png",
  "contact_email": "support@example.com",
  "legal_info_url": "https://example.com/terms"
}

Serving the Manifest File

While plugin.json resides in the repository root, the ChatGPT system fetches the manifest at runtime from the /.well-known/ai-plugin.json endpoint. The following Flask implementation serves the file with the correct MIME type:

from flask import Flask, send_from_directory

app = Flask(__name__)

@app.route("/.well-known/ai-plugin.json")
def serve_manifest():
    # Serve the manifest from the repo root

    return send_from_directory(".", "plugin.json", mimetype="application/json")

This endpoint must return the JSON descriptor with Content-Type: application/json headers for successful discovery.

Summary

• The plugin.json manifest in the openai/plugins repository defines four categories of data: display metadata, authentication configuration, API binding, and legal/branding details.
• The auth object supports none, service_http, or oauth types, with OAuth requiring specific endpoint URLs and scope definitions.
• The api object connects to the OpenAPI specification via an absolute URL and indicates authentication requirements through the is_user_authenticated boolean.
• The manifest is served at the /.well-known/ai-plugin.json endpoint, enabling runtime discovery by the ChatGPT system while the source file remains at the repository root.

Frequently Asked Questions

What is the difference between name_for_human and name_for_model?

The name_for_human field provides a user-friendly display name shown in the ChatGPT UI, while name_for_model supplies a concise, snake_case identifier that the LLM uses internally when deciding whether to invoke your plugin. This separation ensures optimal presentation for users while giving the model a clear, consistent reference token that avoids spaces or special characters.

Does the plugin.json file support authentication methods other than OAuth?

Yes, according to the schema implemented in the openai/plugins repository, the auth.type field accepts three values: "none" for public APIs requiring no authentication, "service_http" for API-key or HTTP-based authentication schemes, and "oauth" for standard OAuth 2.0 flows. Each type requires different sub-fields within the auth object to properly configure the handshake and token management.

Where must the plugin.json file be hosted to work with ChatGPT?

The ChatGPT system expects to fetch the manifest from the /.well-known/ai-plugin.json endpoint on your plugin's domain. While the source file is named plugin.json in the repository root, you must serve it from the .well-known path with the application/json content type, as demonstrated in the Flask implementation example above.

What OpenAPI specification formats does the api.url field support?

The api.url field supports both YAML and JSON formats, typically referenced as openapi.yaml or openapi.json. The api.type field must be set to "openapi" regardless of the chosen format, and the URL must be absolute and publicly accessible so the ChatGPT system can retrieve and parse the endpoint definitions during plugin initialization.

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