# How to Link Your OpenAPI Specification to an OpenAI Plugin Manifest

> Learn how to link your OpenAPI specification to your OpenAI plugin manifest. Add an api object with type openapi and a URL to your plugin.json file.

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

---

**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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) structure demonstrating the OpenAPI linkage:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/openapi.md) demonstrates linking to a raw GitHub-hosted specification:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/marketplace-apps.md):

1. Commit your changes to [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json).
2. Ensure the OpenAPI URL is publicly accessible via HTTPS.
3. Validate the manifest using the OpenAI validation API:

```bash
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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) at the repository root. Additionally, the Zoom plugin examples in [`plugins/zoom/skills/rest-api/references/openapi.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/openapi.md) and [`plugins/zoom/skills/rest-api/references/marketplace-apps.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/marketplace-apps.md) demonstrate practical implementations of the OpenAPI linking pattern and validation procedures.