# What Information Is Included in the Interface Block of plugin.json?

> Learn what information goes into the interface block of plugin.json. Discover display names, descriptions, branding, legal links, and more to define your plugin's UI and functionality.

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

---

**The `interface` block in a Codex plugin's [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file contains all user-facing metadata—including display names, descriptions, branding assets, legal URLs, capabilities, and starter prompts—that defines how the plugin appears and functions in the Codex UI.**

The `openai/plugins` repository defines the structure for Codex plugins, where each plugin’s [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file serves as the configuration manifest. According to the repository’s reference specification ([`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md)), the **`interface` block** acts as the definitive source for UI-related metadata, controlling everything from the plugin’s visual identity to its interactive capabilities as displayed to end users.

## Core Metadata and Identity Fields

The `interface` block begins with essential descriptive fields that establish the plugin’s identity within the Codex ecosystem. These fields determine how users discover and recognize the plugin in marketplace listings and search results.

- **`displayName`**: A human-readable title shown as the plugin’s primary label.
- **`shortDescription`**: A brief subtitle used in compact card views and search results.
- **`longDescription`**: A detailed explanation displayed on the plugin’s dedicated detail page.
- **`developerName`**: The name of the organization or individual author publishing the plugin.
- **`category`**: A high-level classification bucket (e.g., **Productivity**, **Communication**) that groups related plugins together.

## Legal Documentation and External Links

Every plugin must provide references to its external presence and legal compliance documentation. The `interface` block includes three specific URL fields for this purpose:

- **`websiteURL`**: The public-facing website for the plugin or its developer.
- **`privacyPolicyURL`**: A direct link to the plugin’s privacy policy documentation.
- **`termsOfServiceURL`**: The URL pointing to the plugin’s terms of service agreement.

## Functional Capabilities and Starter Prompts

Beyond visual presentation, the `interface` block declares what the plugin can do and how users can initially interact with it.

**Capabilities** are defined in the **`capabilities`** array, which accepts string values such as `Interactive`, `Read`, and `Write`. These values signal to the Codex system which operational modes the plugin supports.

**Starter prompts** are configured through the **`defaultPrompt`** field, an array of strings that provides users with contextual invocation examples. According to the specification in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md), this array accepts up to three prompts, each limited to 128 characters, appearing in the composer or UX context to guide user interaction.

## Visual Assets and Branding Configuration

The `interface` block controls the complete visual presentation of the plugin through asset paths and color specifications. All paths are relative to the plugin root directory.

- **`brandColor`**: A hex color code defining the plugin card background.
- **`brandColorDark`** (optional): A hex color for dark mode variants.
- **`composerIcon`**: The relative path to an SVG or image file displayed within the Codex composer interface.
- **`logo`**: The path to the primary logo asset shown on the plugin card.
- **`logoDark`** (optional): The path to a dark-mode variant of the logo.
- **`screenshots`**: An array of relative paths to PNG screenshot files (maximum three) displayed in the plugin details view.

## Real-World Example from the Zoom Plugin

The Zoom plugin implementation at [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json) demonstrates a fully populated `interface` block. This configuration illustrates proper field usage including dark mode variants and multiple starter prompts:

```json
{
  "interface": {
    "displayName": "Zoom",
    "shortDescription": "Smart meeting insights from Zoom",
    "longDescription": "Zoom connects Codex to Zoom meeting context through the Zoom app connector …",
    "developerName": "Zoom",
    "category": "Communication",
    "capabilities": ["Interactive", "Read", "Write"],
    "websiteURL": "https://zoom.us",
    "privacyPolicyURL": "https://zoom.us/privacy",
    "termsOfServiceURL": "https://www.zoom.com/en/trust/terms/",
    "defaultPrompt": [
      "Search my recent Zoom meetings for the discussion about pricing.",
      "Run /plan-zoom-product for a Zoom integration idea."
    ],
    "brandColor": "#0B5CFF",
    "brandColorDark": "#0B5CFF",
    "composerIcon": "./assets/composer-icon.svg",
    "logo": "./assets/logo.jpg",
    "logoDark": "./assets/logo-dark.jpg",
    "screenshots": [
      "./assets/screenshot-1.png",
      "./assets/screenshot-2.png",
      "./assets/screenshot-3.png",
      "./assets/screenshot-4.png"
    ]
  }
}

```

## Repository Structure and File Locations

In the `openai/plugins` repository, every plugin follows a consistent file structure where the `interface` block resides within [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) files located at `plugins/<plugin-name>/.codex-plugin/plugin.json`. Key implementations demonstrating this pattern include:

- **Zoom**: [[`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json)](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json)
- **Vercel**: [[`plugins/vercel/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json)](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json)
- **Slack**: [[`plugins/slack/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/slack/.codex-plugin/plugin.json)](https://github.com/openai/plugins/blob/main/plugins/slack/.codex-plugin/plugin.json)
- **Google Drive**: [[`plugins/google-drive/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/google-drive/.codex-plugin/plugin.json)](https://github.com/openai/plugins/blob/main/plugins/google-drive/.codex-plugin/plugin.json)

## Summary

- The **`interface` block** serves as the centralized container for all user-facing metadata in Codex plugins.
- It includes **identity fields** (`displayName`, `description` variants, `developerName`, `category`), **legal URLs** (`privacyPolicyURL`, `termsOfServiceURL`), and **functional declarations** (`capabilities`).
- **Visual branding** is controlled through `brandColor`, `logo` paths, `composerIcon`, and up to three **screenshots**.
- **Starter prompts** (`defaultPrompt`) support up to three strings of 128 characters each to guide initial user interaction.
- All plugins in the `openai/plugins` repository store this configuration in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) within their respective plugin directories.

## Frequently Asked Questions

### What is the maximum number of starter prompts allowed in the defaultPrompt field?

The `defaultPrompt` array accepts a maximum of three strings. Each prompt must not exceed 128 characters in length, as enforced by the specification in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md).

### Does the interface block support dark mode branding?

Yes. The `interface` block includes optional fields for dark mode variants: **`logoDark`** specifies an alternative logo path, and **`brandColorDark`** defines a separate hex color code for dark mode presentation.

### What file types are required for screenshot assets?

The `screenshots` field expects PNG image files. The specification limits the array to a maximum of three screenshot paths, allowing plugins to showcase their UI without overwhelming the detail view.

### Is the interface block required for all Codex plugins?

Yes. As implemented in the `openai/plugins` repository, the `interface` object is a mandatory component of every [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest. It provides the essential metadata required for the Codex system to render the plugin in the UI and categorize it correctly within the plugin marketplace.