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

> Understand the difference between marketplace.json and apimarketplace.json in OpenAI Plugins. Learn how these files power the plugin storefront and validate API requests for external services.

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

---

**While [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) provides the static, human‑readable catalog that powers the visual plugin storefront in the Codex UI, [`apimarketplace.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/apimarketplace.json), the engineering team can evolve backend validation rules and endpoint contracts independently of the frontend user experience.

## Key Architectural Differences

- **[`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json)** focuses on *presentation*: it dictates what users see in the marketplace UI, including visual hierarchy and categorization.
- **[`apimarketplace.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/marketplace.json) never risk breaking API integrations that depend on the stable schema defined in [`apimarketplace.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/marketplace.json) to populate the plugin list:

```javascript
// 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`](https://github.com/openai/plugins/blob/main/apimarketplace.json) to validate plugin payloads before processing:

```python

# 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/marketplace.json) file lacks the strict JSON schema definitions required for API validation. You must use [`apimarketplace.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/marketplace.json) without risking breaking changes to external services that depend on the stable schema defined in [`apimarketplace.json`](https://github.com/openai/plugins/blob/main/apimarketplace.json).

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

You typically update [`marketplace.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/apimarketplace.json) reflects any schema changes required by the backend.

### Does apimarketplace.json define the actual plugin endpoints?

No. [`apimarketplace.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json) or OpenAPI specifications within each plugin’s directory.