Understanding the Split Between marketplace.json and api_marketplace.json in OpenAI Plugins

The OpenAI Plugins repository maintains two separate manifest files—marketplace.json and api_marketplace.json—to isolate presentation-layer metadata consumed by the web UI from machine-readable API contracts used by the backend runtime, enabling independent versioning, caching, and update cycles.

The OpenAI Plugins repository stores plugin manifests in the hidden .agents/plugins directory. While both files describe the same plugin ecosystem, they serve fundamentally different architectural purposes. This separation of concerns prevents UI changes from breaking API contracts and allows each component to evolve at its own velocity.

The Two Manifest Files: Presentation vs. API Contracts

The repository maintains dual manifests under .agents/plugins/ to satisfy distinct consumer requirements within the plugin ecosystem.

marketplace.json: UI-Facing Metadata

Located at .agents/plugins/marketplace.json, this file serves the Marketplace UI—the web portal where developers discover, install, and manage plugins. It contains human-readable metadata including:

• Plugin titles and descriptions
• Icon URLs and branding assets
• Categories and tags for discovery
• Screenshot references and marketing copy

This file optimizes for developer experience and visual presentation, updating whenever marketing assets change, such as new screenshots or tagline revisions.

api_marketplace.json: Runtime API Contracts

Located at .agents/plugins/api_marketplace.json, this file serves the Plugin runtime API that the OpenAI server uses to resolve plugin capabilities. It contains machine-readable definitions including:

• Endpoint URLs and routing information
• OpenAPI schema specifications
• Authentication flow descriptors
• Versioned API contracts and protocol definitions

Updates to this file occur only when functional contracts change, such as new endpoints or altered request/response schemas.

Why the Repository Maintains Both Files

The split between these manifests addresses specific operational and architectural requirements in the OpenAI plugin system.

Separation of Concerns

Keeping UI-centric data separate from API contracts avoids unnecessary churn in the runtime system when only visual assets change. The presentation layer can iterate on branding and discoverability features without risking stability in the backend services that execute plugin functionality.

Independent Caching and Performance

The marketplace front-end caches its manifest independently of the backend API. Since marketplace.json contains static assets and descriptive text, it can be cached aggressively by CDN edge nodes. Conversely, api_marketplace.json may require stricter cache controls or immediate propagation when security-critical API contracts change.

Versioning and Stability Guarantees

The API-centric file can be versioned and validated independently of UI assets. This ensures that downstream services—including the GPT model’s plugin discovery system—receive a stable, schema-validated definition even while the marketplace interface undergoes cosmetic updates. The runtime system depends on precise structural guarantees that would be compromised if mixed with frequently changing presentation data.

Working with Both Files in Practice

When integrating with the OpenAI plugin ecosystem, you must target the appropriate manifest based on your use case. The following Python example demonstrates fetching and parsing both files to retrieve complementary information about a specific plugin:

import json
import requests

# Load the marketplace UI manifest (used by the web portal)

ui_url = "https://raw.githubusercontent.com/openai/plugins/main/.agents/plugins/marketplace.json"
ui_manifest = json.loads(requests.get(ui_url).text)

# Load the API contract manifest (used by the OpenAI server)

api_url = "https://raw.githubusercontent.com/openai/plugins/main/.agents/plugins/api_marketplace.json"
api_manifest = json.loads(requests.get(api_url).text)

# Example: retrieve the human-friendly description of a plugin

def get_plugin_description(plugin_id: str) -> str:
    for plugin in ui_manifest["plugins"]:
        if plugin["id"] == plugin_id:
            return plugin["description"]
    raise ValueError("Plugin not found")

# Example: retrieve the OpenAPI spec URL for the same plugin

def get_plugin_openapi_url(plugin_id: str) -> str:
    for plugin in api_manifest["plugins"]:
        if plugin["id"] == plugin_id:
            return plugin["openapi"]
    raise ValueError("Plugin not found")

When building tools that interact with the plugin repository, reference marketplace.json for display purposes and api_marketplace.json for functional integration or runtime validation.

Summary

• Dual manifests serve distinct consumers: .agents/plugins/marketplace.json feeds the web UI while .agents/plugins/api_marketplace.json feeds the backend runtime.
• Separation prevents functional breakage: UI updates cannot accidentally alter API contracts that the GPT model depends upon.
• Independent update cycles: Marketing metadata changes frequently without requiring runtime redeployments, while API contracts change only when functional specifications evolve.
• Caching optimization: Each manifest can leverage appropriate cache strategies based on its content volatility and consumer requirements.

Frequently Asked Questions

Why doesn't OpenAI merge these into a single manifest file?

Merging the files would couple presentation concerns with functional contracts, forcing unnecessary runtime updates when only marketing assets change. The split enables the UI team to iterate on discoverability features—such as adding screenshots or reorganizing categories—without triggering validation pipelines or cache invalidation in the critical path of the GPT model's plugin execution system.

Which manifest should I use when building a plugin browser or directory?

Use marketplace.json for any interface displaying plugins to humans. This file contains the titles, descriptions, icons, and categorization metadata necessary for browse-and-discover functionality. Only consume api_marketplace.json if you are implementing a runtime client that needs to resolve endpoints, validate OpenAPI schemas, or handle authentication flows programmatically.

How frequently do these files update relative to each other?

marketplace.json updates whenever plugin marketing materials change—potentially multiple times per day as developers refine their plugin listings. api_marketplace.json updates only when the functional contract changes, such as adding new endpoints, modifying request schemas, or updating authentication mechanisms. This decoupled cadence prevents UI iteration from destabilizing production API integrations.

Do both files contain identical plugin ID references?

Yes, both manifests reference the same plugin identifiers, allowing you to correlate entries between the presentation layer and the API layer. However, the schemas diverge significantly: marketplace.json emphasizes visual and descriptive fields, while api_marketplace.json contains technical specifications required for actual plugin invocation.

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