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

> Explore the plugin.json manifest file to understand OpenAI plugin metadata authentication and API details enabling system display authentication and invocation.

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

---

**The [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json) file serves as the canonical manifest within the [openai/plugins](https://github.com/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`](https://github.com/openai/plugins/blob/main/openapi.yaml) or [`openapi.json`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugin.json) resides in the repository root, the ChatGPT system fetches the manifest at runtime from the [`/.well-known/ai-plugin.json`](https://github.com/openai/plugins/blob/main//.well-known/ai-plugin.json) endpoint. The following Flask implementation serves the file with the correct MIME type:

```python
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main//.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`](https://github.com/openai/plugins/blob/main//.well-known/ai-plugin.json) endpoint on your plugin's domain. While the source file is named [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/openapi.yaml) or [`openapi.json`](https://github.com/openai/plugins/blob/main/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.