How to Link Your OpenAPI Specification to an OpenAI Plugin Manifest

Link your OpenAPI specification to a plugin manifest by adding an api object with "type": "openapi" and a publicly accessible HTTPS "url" pointing to a valid OpenAPI 3.0+ JSON file inside your .codex-plugin/plugin.json file.

To enable OpenAI models to interact with your REST API, you must declare the specification location in your plugin manifest. The openai/plugins repository defines this linkage in the .codex-plugin/plugin.json schema, where the api field serves as the bridge between the plugin metadata and your endpoint definitions.

Plugin Manifest Structure for OpenAPI Specifications

The manifest schema, located at .codex-plugin/plugin.json in the repository root, requires a top-level api object that instructs the platform how to ingest your service definition. This object must contain specific keys to ensure proper discovery and validation.

The api Object Fields

The api configuration accepts the following properties:

• type: Must be set to "openapi" to signal that the URL points to an OpenAPI specification.
• url: A publicly accessible HTTPS URL that returns a valid OpenAPI 3.0 or higher JSON document. The file must be reachable without authentication unless protected by the auth flow defined in the manifest.
• is_user_authenticated: (Optional) Boolean indicating whether the API requires user-level tokens. Set to true if endpoints require per-user credentials.
• has_user_authentication: (Optional) Legacy field name maintained for backward compatibility; prefer is_user_authenticated.

Minimal Manifest Example

Below is a complete .codex-plugin/plugin.json structure demonstrating the OpenAPI linkage:

{
  "schema_version": "v1",
  "name_for_human": "Weather Lookup Plugin",
  "name_for_model": "weather_lookup",
  "description_for_human": "Provides current weather data for any location.",
  "description_for_model": "Accesses real-time weather information via REST API.",
  "api": {
    "type": "openapi",
    "url": "https://api.example.com/openapi.json"
  },
  "auth": {
    "type": "none"
  },
  "logo_url": "https://example.com/logo.png",
  "contact_email": "support@example.com",
  "legal_info_url": "https://example.com/terms"
}

Referencing External OpenAPI Documents

You can point to existing specifications hosted on CDNs or version control platforms. For example, the Zoom skill reference in plugins/zoom/skills/rest-api/references/openapi.md demonstrates linking to a raw GitHub-hosted specification:

{
  "api": {
    "type": "openapi",
    "url": "https://raw.githubusercontent.com/zoom/api/442998230a148f403c3d1de1fe7aa54937354fa9/openapi.v2.json"
  }
}

Ensure the URL returns Content-Type: application/json and allows cross-origin requests. The platform fetches this file during the manifest validation process to generate request schemas and validate model interactions.

Validating the OpenAPI Link

After updating your manifest, verify the configuration using the validation endpoint referenced in plugins/zoom/skills/rest-api/references/marketplace-apps.md:

1. Commit your changes to .codex-plugin/plugin.json.
2. Ensure the OpenAPI URL is publicly accessible via HTTPS.
3. Validate the manifest using the OpenAI validation API:

curl -X POST https://api.openai.com/v1/plugins/manifest/validate \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"manifest_url":"https://raw.githubusercontent.com/yourorg/yourplugin/main/.codex-plugin/plugin.json"}'

The response confirms whether the OpenAPI URL is reachable and conforms to the required schema version.

Common Linking Pitfalls

Avoid these frequent errors when configuring your api URL:

• Private or raw URLs pointing to authenticated repositories: Using a GitHub raw link that requires session cookies will result in a 404 during validation. Host the JSON on a public static server or CDN instead.
• OpenAPI 2.0 (Swagger) specifications: The platform expects OpenAPI 3.0+. Convert legacy Swagger files using tools like swagger2openapi before linking.
• Missing CORS headers: If the spec URL blocks cross-origin requests, the validation will fail. Ensure the server returns Access-Control-Allow-Origin: * or permits the OpenAI domain.
• Omitting the type field: Without "type": "openapi", the platform cannot determine how to parse the linked resource.

Summary

• Store your plugin manifest in .codex-plugin/plugin.json at the repository root.
• Populate the api object with "type": "openapi" and a public HTTPS "url" to your OpenAPI 3.0+ JSON file.
• Reference external specifications using absolute URLs, as demonstrated in plugins/zoom/skills/rest-api/references/openapi.md.
• Validate your configuration using the marketplace validation endpoint to ensure the link is reachable and compliant.

Frequently Asked Questions

Can I use a local file path instead of a URL for the OpenAPI specification?

No, the url field must be an absolute HTTPS URL accessible from the public internet. The OpenAI platform fetches the specification during plugin registration and runtime, so local file paths or internal network addresses will fail validation.

What OpenAPI version is required for the plugin manifest?

The platform requires OpenAPI 3.0 or higher. OpenAPI 2.0 (Swagger) specifications are not supported. You must upgrade or convert your specification before linking it in the manifest's api.url field.

How do I handle authentication for the OpenAPI specification URL?

The specification URL itself must be publicly accessible without authentication. If your API requires authentication, define the auth flow (such as OAuth or API keys) in the manifest's auth object, not on the spec file access. The is_user_authenticated boolean in the api object signals whether the endpoints require per-user tokens.

Where is the manifest schema defined in the openai/plugins repository?

The canonical schema and example structure reside in .codex-plugin/plugin.json at the repository root. Additionally, the Zoom plugin examples in plugins/zoom/skills/rest-api/references/openapi.md and plugins/zoom/skills/rest-api/references/marketplace-apps.md demonstrate practical implementations of the OpenAPI linking pattern and validation procedures.

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