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

> Discover the OpenAI plugins two-tier marketplace model. Learn how it separates user-facing catalogs from developer API catalogs for efficient plugin discovery.

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

---

**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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) and [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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

```python
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

```javascript
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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) | Defines the **curated** catalog for ChatGPT UI consumption |
| [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)) targets ChatGPT users with `installation: "AVAILABLE"` and typically uses `authentication: "ON_INSTALL"`.
- **Tier 2** ([`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)) serves the ChatGPT UI where users browse and install plugins manually. The API marketplace ([`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/marketplace.json) while the developer catalog lives in [`api_marketplace.json`](https://github.com/openai/plugins/blob/main/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.