OpenAI Plugin Listing Success Criteria: 7 Requirements for Marketplace Approval

A plugin must satisfy technical requirements (valid manifest, OpenAPI spec, authentication), policy standards (brand safety, privacy), and stability criteria (functional tests) to be listed in the OpenAI Plugin Marketplace.

The openai/plugins repository defines the infrastructure and validation rules governing the OpenAI Plugin Marketplace. Meeting the success criteria for a plugin to be listed requires satisfying both mandatory technical specifications defined in the manifest structure and internal policy reviews enforced during submission.

Technical Requirements for Plugin Listing

Manifest Presence and Structure (plugin.json)

Every plugin must contain a .codex-plugin/plugin.json file located at plugins/<plugin_name>/.codex-plugin/plugin.json. This manifest serves as the single source of truth for the plugin's metadata and capabilities.

The file must include these required fields:

• schema_version – Currently v1
• name_for_human – User-facing display name
• name_for_model – Machine-readable identifier
• description_for_human – Marketplace listing description
• description_for_model – Context for the AI model
• auth – Authentication configuration object
• api – OpenAPI specification reference
• logo_url – Icon for marketplace display
• contact_email – Support contact

{
  "schema_version": "v1",
  "name_for_human": "My Example Plugin",
  "name_for_model": "my_example_plugin",
  "description_for_human": "A simple example plugin that returns greeting messages.",
  "description_for_model": "Provides a /greet endpoint that returns a friendly greeting.",
  "auth": {
    "type": "none"
  },
  "api": {
    "type": "openapi",
    "url": "openapi.yaml"
  },
  "logo_url": "https://example.com/logo.png",
  "contact_email": "[email protected]"
}

This minimal configuration satisfies the Manifest Presence, OpenAPI Specification, and Human-Readable Metadata criteria.

OpenAPI Specification Compliance

The api.url field in plugin.json must point to a valid OpenAPI document, either as inline JSON/YAML or an external URL. The specification must be syntactically correct and enumerate all supported endpoints with proper response schemas.

openapi: 3.0.1
info:
  title: Greeting API
  version: "1.0"
paths:
  /greet:
    get:
      summary: Return a greeting
      responses:
        '200':
          description: A friendly greeting
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

The OpenAPI document must reside at the path specified in the manifest, typically plugins/<plugin_name>/openapi.yaml or openapi.json.

Authentication Declaration Standards

The manifest must explicitly declare the authentication method via the auth.type field. Acceptable values include none, service_http, or oauth.

For OAuth implementations, the manifest must specify additional parameters:

{
  "auth": {
    "type": "oauth",
    "client_id": "YOUR_CLIENT_ID",
    "authorization_url": "https://auth.example.com/authorize",
    "scopes": ["read", "write"]
  }
}

This declaration satisfies the Authentication Declaration criterion required for marketplace approval.

Policy and Safety Requirements

Brand Safety and Content Review

According to the repository's security guidelines enforced during marketplace submission, plugin code must not expose secrets or hardcoded credentials. The implementation must pass OpenAI's internal brand-safety review, which prohibits disallowed content and requires proper rate-limiting mechanisms.

Privacy and Data Handling

Plugins must comply with the marketplace contract defined in .agents/plugins/marketplace.json. This requires publishing a privacy policy, handling user data transparently, and refraining from using prohibited APIs. The contact_email field in the manifest establishes accountability for data handling practices.

Testing and Stability Standards

Plugins must include functional tests, typically located in plugins/<plugin_name>/tests/, that verify each endpoint behaves according to the OpenAPI contract. A stable build must pass all continuous integration checks before the submission review process begins.

The repository structure implies that untested plugins or those failing CI validation will not advance to the public marketplace.

Verification Checklist

Before submitting for review, verify your plugin satisfies all success criteria:

1. Manifest validation – plugin.json exists at .codex-plugin/plugin.json with all required fields
2. OpenAPI integrity – The specification file is syntactically valid and referenced correctly
3. Authentication configuration – Auth type is declared and OAuth parameters are complete (if applicable)
4. Metadata completeness – Human-readable name, description, and logo URL are present
5. Security audit – No exposed secrets, proper rate limiting implemented
6. Test coverage – Functional tests exist in tests/ and pass CI checks
7. Policy compliance – Privacy policy published and marketplace rules satisfied

When all seven items are satisfied, the plugin can be submitted for review. The review process validates each criterion against the source code and manifest before adding the plugin to the public marketplace.

Summary

• Manifest requirement: Every plugin must include a complete plugin.json at plugins/<name>/.codex-plugin/plugin.json with metadata, auth, and API references.
• OpenAPI contract: The specification must be valid and accurately describe all endpoints.
• Authentication: Explicit declaration of auth type (none, service_http, or oauth) with required scopes for OAuth.
• Safety review: Code must pass brand-safety checks with no exposed secrets and proper rate limiting.
• Testing: Functional tests in plugins/<name>/tests/ must verify OpenAPI compliance and pass CI.
• Policy compliance: Privacy policy publication and adherence to .agents/plugins/marketplace.json rules are mandatory.

Frequently Asked Questions

What happens if my plugin.json is missing required fields?

The plugin will fail the initial automated validation. The README.md in the openai/plugins repository explicitly states that each plugin must contain the mandatory manifest fields including name_for_human, description_for_model, and auth. Missing fields prevent the plugin from entering the review queue.

Can I use external URLs for my OpenAPI specification?

Yes. The api.url field in plugin.json accepts either relative paths (e.g., openapi.yaml) or absolute URLs. However, the specification must remain accessible and the content must match the deployed endpoints during the review process.

How long does the brand-safety review take?

The repository does not specify exact timeframes, but the review process checks that your code contains no secrets, implements proper rate limiting, and complies with content policies. Ensure your contact_email is valid, as reviewers use this for clarification requests during the safety verification phase.

Do I need tests if my plugin is simple?

Yes. The repository structure indicates that plugins should include functional tests in a tests/ folder regardless of complexity. These tests verify that your endpoints behave according to the OpenAPI contract, satisfying the Testing & Stability criterion required for listing.

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