How the Two-Tier Marketplace Model Works in the OpenAI Plugins Repository

The OpenAI Plugins repository implements a two-tier marketplace architecture that separates the user-facing curated plugin catalog from the API-driven developer catalog, defined in .agents/plugins/marketplace.json and .agents/plugins/api_marketplace.json respectively.

This repository hosts the official plugin definitions for OpenAI's ecosystem, organizing tools into two distinct discovery layers. The two-tier marketplace model allows OpenAI to maintain separate product experiences for end-users browsing ChatGPT and developers programmatically accessing the API.

Understanding the Two-Tier Architecture

The architecture splits plugin distribution into complementary tiers: one optimized for UI-based discovery and another for programmatic integration.

Tier 1: The Curated Plugin Marketplace

The first tier serves as the user-facing catalog that appears in the ChatGPT interface. According to the source code, this tier is defined in .agents/plugins/marketplace.json and contains plugins marked with installation: "AVAILABLE", making them visible for one-click installation.

Plugins in this tier typically enforce authentication: "ON_INSTALL", requiring users to complete OAuth or API key setup once during installation rather than per-request. This creates a frictionless experience where authenticated sessions persist across conversations.

Tier 2: The API Marketplace

The second tier targets developers calling the OpenAI API with the plugins parameter. Defined in .agents/plugins/api_marketplace.json, this catalog may expose plugins with authentication: "ON_USE", requiring credentials on every API call.

This tier supports product-specific filtering through the policy.products field (e.g., CODEX), allowing the API to serve contextually relevant tools based on the calling application. While sharing the underlying plugin definitions with Tier 1, this catalog prioritizes flexibility over UI presentation.

Shared Schema and Policy Configuration

Both JSON files follow an identical schema that defines marketplace behavior:

• name – The unique marketplace identifier
• interface.displayName – Human-readable label shown in discovery surfaces
• plugins – Array of plugin objects containing:
  • name – Internal plugin identifier
  • source – Either local (referencing ./plugins/<plugin>) or a remote Git URL
  • policy – Controls installation availability and authentication mode
  • category – Logical grouping such as Productivity or Developer Tools

Because both tiers reference the same underlying plugin directories under ./plugins/, updates to any plugin's code, manifest, or policy propagate immediately to both catalogs, ensuring consistency across consumption methods.

Practical Implementation

You can query both marketplace tiers programmatically to inspect available plugins and their policies.

Querying the Curated Marketplace

import json
import urllib.request

url = "https://raw.githubusercontent.com/openai/plugins/main/.agents/plugins/marketplace.json"
data = json.load(urllib.request.urlopen(url))

print("Curated Marketplace – Plugins:")
for p in data["plugins"]:
    auth_mode = p['policy']['authentication']
    print(f"- {p['name']} (Category: {p['category']}, Auth: {auth_mode})")

Filtering the API Marketplace by Product

const https = require('https');

https.get('https://raw.githubusercontent.com/openai/plugins/main/.agents/plugins/api_marketplace.json', (res) => {
  let raw = '';
  res.on('data', chunk => raw += chunk);
  res.on('end', () => {
    const market = JSON.parse(raw);
    const codexPlugins = market.plugins.filter(p =>
      p.policy.products?.includes('CODEX')
    );
    console.log('CODEX-enabled plugins:');
    codexPlugins.forEach(p => console.log(`- ${p.name}`));
  });
});

Key Source Files and Roles

File	Role
.agents/plugins/marketplace.json	Defines the curated catalog for ChatGPT UI consumption
.agents/plugins/api_marketplace.json	Defines the API-driven catalog for programmatic access
plugins/<name>/.codex-plugin/plugin.json	Individual plugin manifests containing OpenAPI specs and authentication flows

Summary

• The two-tier marketplace model separates user-facing discovery from developer API access while maintaining a single source of truth for plugin definitions.
• Tier 1 (.agents/plugins/marketplace.json) targets ChatGPT users with installation: "AVAILABLE" and typically uses authentication: "ON_INSTALL".
• Tier 2 (.agents/plugins/api_marketplace.json) targets API developers, supports authentication: "ON_USE", and filters via policy.products.
• Both tiers share a common schema and reference identical plugin source directories, ensuring synchronized updates across all consumption surfaces.

Frequently Asked Questions

What is the difference between the curated marketplace and the API marketplace?

The curated marketplace (.agents/plugins/marketplace.json) serves the ChatGPT UI where users browse and install plugins manually. The API marketplace (.agents/plugins/api_marketplace.json) serves programmatic clients that request plugins via the OpenAI API, often filtered by product type such as CODEX.

How does authentication differ between the two tiers?

The curated tier typically uses authentication: "ON_INSTALL", requiring users to authenticate once during setup and maintaining the session across conversations. The API tier may use authentication: "ON_USE", requiring fresh credentials on every API call, though both tiers support either mode depending on the specific plugin policy.

Where are the marketplace configurations stored in the repository?

Both configurations reside in the .agents/plugins/ directory at the repository root. The user-facing catalog lives in marketplace.json while the developer catalog lives in api_marketplace.json.

Can a plugin exist in both tiers simultaneously?

Yes. Because both JSON files reference the same underlying plugin directories under ./plugins/, a single plugin definition can appear in both the curated and API marketplaces. The plugin's policy fields determine its availability and authentication requirements in each context.

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