Difference Between marketplace.json and api_marketplace.json in OpenAI Plugins

The marketplace.json file configures the default plugin marketplace for standard Codex users, while api_marketplace.json provides a dedicated marketplace specifically for users authenticating with an API key.

The OpenAI Plugins repository employs two distinct marketplace configuration files to manage plugin discovery based on authentication contexts. Understanding the difference between marketplace.json and api_marketplace.json is essential for developers who need to customize plugin availability for different user segments within the OpenAI ecosystem.

File Locations and Primary Purpose

Standard User Marketplace (marketplace.json)

Located at .agents/plugins/marketplace.json, this file defines the default marketplace that enumerates all available plugins for typical Codex users. It points to the standard plugins/ directory and serves as the primary configuration file that most developers edit when adding, removing, or reordering plugins for general use.

API Key Authenticated Marketplace (api_marketplace.json)

Found at .agents/plugins/api_marketplace.json, this configuration file creates a separate marketplace entry point specifically for users who sign in using an API key. According to the OpenAI Plugins source code, this separation allows administrators to present a curated subset of plugins or implement different policies tailored specifically to API-key-authenticated sessions without affecting the general user base.

Structural Consistency and Functional Differences

Both configuration files share an identical JSON schema structure, including fields for name, interface, and the plugins array. However, they function as independent entry points in the plugin discovery system. While .agents/plugins/marketplace.json typically contains the complete plugin catalog, .agents/plugins/api_marketplace.json enables selective plugin exposure, allowing API key users to access restricted or experimental plugins that may not appear in the default marketplace.

Loading Configuration Files in Practice

When building administrative tools or custom clients around these configuration files, you must target the correct file path based on the user's authentication context.

Loading the default marketplace for standard users:

import fs from 'fs';
import path from 'path';

const marketplacePath = path.resolve(
  process.env.HOME,
  '.agents',
  'plugins',
  'marketplace.json'
);
const marketplace = JSON.parse(fs.readFileSync(marketplacePath, 'utf-8'));
console.log('Default plugins:', marketplace.plugins.map(p => p.name));

Loading the API-key-specific marketplace:

import fs from 'fs';
import path from 'path';

const apiMarketplacePath = path.resolve(
  process.env.HOME,
  '.agents',
  'plugins',
  'api_marketplace.json'
);
const apiMarketplace = JSON.parse(fs.readFileSync(apiMarketplacePath, 'utf-8'));
console.log('API-key plugins:', apiMarketplace.plugins.map(p => p.name));

Summary

• .agents/plugins/marketplace.json serves as the default marketplace configuration for regular Codex users
• .agents/plugins/api_marketplace.json provides a separate marketplace entry point exclusively for API key authenticated users
• Both files utilize the identical JSON schema but maintain independent plugin lists
• API key authentication workflows can present curated plugin subsets without modifying the default marketplace available to standard users

Frequently Asked Questions

Can I use the same plugins in both marketplace.json and api_marketplace.json?

Yes, both files support identical plugin entries and schema structures. You can duplicate configurations across both files or create entirely distinct catalogs depending on your requirements for standard versus API-key-authenticated users.

What happens if api_marketplace.json is missing from the directory?

If the API-specific marketplace file does not exist at .agents/plugins/api_marketplace.json, the system behavior depends on your specific implementation. Typically, the application may fall back to default marketplace settings or require manual creation of the file to enable API-key-specific plugin discovery workflows.

Do I need to restart services after editing these configuration files?

Changes to either marketplace.json or api_marketplace.json typically require a reload of the plugin discovery service or a full application restart to take effect. These files are generally read at initialization rather than polled continuously during runtime.

Are the schema requirements different between the two marketplace files?

No, both configuration files follow the exact same JSON schema requirements. The structure includes identical fields such as name, interface, and the plugins array, ensuring consistency across both standard and API-key marketplace configurations in the OpenAI Plugins repository.

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