What Is the Difference Between marketplace.json and apimarketplace.json in OpenAI Plugins

While marketplace.json provides the static, human‑readable catalog that powers the visual plugin storefront in the Codex UI, apimarketplace.json defines the machine‑readable JSON schema that validates API requests and enforces the programmatic contract for external services.

Both files reside in the .agents/plugins directory of the OpenAI Plugins repository, yet they serve distinct architectural roles in the Codex ecosystem. Understanding the difference between these two configurations is critical for developers integrating with the OpenAI marketplace or contributing new plugins.

What Is marketplace.json?

Located at .agents/plugins/marketplace.json, this file functions as the static catalog for the Codex Plugin Marketplace storefront. It contains human‑readable metadata that describes every available plugin, including display names, descriptions, icon URLs, category groupings, and the default ordering used in the UI.

The Codex frontend—specifically the ChatGPT “Plugins” pane and related marketplace interfaces—reads this file to render the list of available plugins. When a user browses categories or views plugin details in the UI, the application is consuming the structured data defined in marketplace.json. This separation allows product teams to update visual presentation, categories, or marketing copy without modifying the underlying API contracts.

What Is apimarketplace.json?

Found at .agents/plugins/apimarketplace.json, this file defines the machine‑readable API contract for the marketplace. Rather than describing how plugins look to users, it specifies the JSON schema for the REST endpoints that expose plugin metadata, versioning information, and health‑check endpoints.

The server‑side API layer—particularly the Codex /v1/plugins endpoint—consumes this file to validate incoming requests, generate OpenAPI specifications, and enforce version compatibility. External services and the OpenAI runtime use this schema to ensure that plugin payloads conform to the expected structure before processing. By isolating the API schema into apimarketplace.json, the engineering team can evolve backend validation rules and endpoint contracts independently of the frontend user experience.

Key Architectural Differences

• marketplace.json focuses on presentation: it dictates what users see in the marketplace UI, including visual hierarchy and categorization.
• apimarketplace.json focuses on validation: it provides the formal schema that programmatic clients use to interact with the /v1/plugins endpoint and related APIs.
• Decoupled evolution: Changes to icons or category labels in marketplace.json never risk breaking API integrations that depend on the stable schema defined in apimarketplace.json.

How Each File Is Consumed

The following examples demonstrate how client code interacts with each configuration.

Loading the UI Catalog

Frontend applications fetch marketplace.json to populate the plugin list:

// Fetch the marketplace catalog for rendering the plugin list
import fetch from 'node-fetch';

async function loadMarketplace() {
  const resp = await fetch(
    'https://raw.githubusercontent.com/openai/plugins/main/.agents/plugins/marketplace.json'
  );
  const catalog = await resp.json();   // → array of plugin entries
  return catalog;
}

Validating Against the API Schema

Backend services use apimarketplace.json to validate plugin payloads before processing:

# Validate a plugin payload against the API schema

import json, jsonschema, urllib.request

def get_schema():
    with urllib.request.urlopen(
        'https://raw.githubusercontent.com/openai/plugins/main/.agents/plugins/apimarketplace.json'
    ) as f:
        return json.load(f)

def validate_plugin(payload):
    schema = get_schema()
    jsonschema.validate(instance=payload, schema=schema)

# `payload` is the JSON body you’d POST to /v1/plugins

Summary

• marketplace.json lives in .agents/plugins/ and powers the visual Codex Plugin Marketplace UI with human‑readable metadata like names, icons, and categories.
• apimarketplace.json resides in the same directory but defines the JSON schema for REST API validation, versioning, and health checks consumed by the /v1/plugins endpoint.
• Keeping these files separate ensures that UI updates never destabilize programmatic integrations and that API contracts remain stable while the storefront evolves.

Frequently Asked Questions

Can I use marketplace.json to validate API payloads?

No. The marketplace.json file lacks the strict JSON schema definitions required for API validation. You must use apimarketplace.json to validate payloads against the expected structure for the /v1/plugins endpoint and related REST interfaces.

Why are these files kept separate instead of combined?

The separation enforces a clean boundary between presentation and contract. The OpenAI team can update visual metadata, categories, or icon URLs in marketplace.json without risking breaking changes to external services that depend on the stable schema defined in apimarketplace.json.

Which file should I modify when adding a new plugin to the marketplace?

You typically update marketplace.json to include the plugin’s display metadata, categories, and ordering for the UI. However, if the new plugin introduces new API fields or structure, you must also ensure apimarketplace.json reflects any schema changes required by the backend.

Does apimarketplace.json define the actual plugin endpoints?

No. apimarketplace.json defines the schema for the marketplace API itself—the endpoints that list and manage plugins, such as /v1/plugins. Individual plugin endpoints (the ones each plugin exposes to ChatGPT or Codex) are defined in their respective plugin.json or OpenAPI specifications within each plugin’s directory.

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