# How to Define API Endpoints for an OpenAI Plugin: A Complete Developer's Guide

> Learn how to define API endpoints for your OpenAI plugin. This guide details creating a manifest file and OpenAPI specification for your REST API capabilities.

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

---

**Define API endpoints for your OpenAI plugin by creating a manifest file at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) that points to a publicly hosted OpenAPI specification describing your REST API capabilities.**

The OpenAI plugins repository enables developers to extend AI capabilities through custom HTTP interfaces. To define API endpoints for your OpenAI plugin, you must configure a structured manifest and an OpenAPI document that the platform uses to automatically generate function calls for the model.

## Understanding the Plugin Manifest Structure

Every OpenAI plugin requires a manifest file located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) in your repository root. This file tells the OpenAI platform where your API lives and how to authenticate against it.

### Required Manifest Fields

The manifest must include the `name`, `description`, and `api` keys. The `name` field uses hyphen-case formatting (e.g., `"my-weather-plugin"`), while the `description` provides a human-readable summary of your plugin's capabilities. The `api` block is the critical component that defines your HTTP endpoints.

According to the source code in the Zoom plugin example at [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json), a minimal manifest structure looks like this:

```json
{
  "name": "weather-plugin",
  "description": "Provides real-time weather data",
  "api": {
    "type": "openapi",
    "url": "https://example.com/openapi.yaml"
  },
  "auth": {
    "type": "none"
  }
}

```

The `api.url` must point to a valid HTTPS endpoint hosting your OpenAPI specification. The OpenAI runtime fetches this document, validates it, and generates the corresponding function signatures that the model can invoke.

## Creating the OpenAPI Specification

Your OpenAPI specification enumerates every endpoint you want the model to access. This document must be publicly accessible via HTTPS and conform to OpenAPI 3.0.x standards.

### Essential OpenAPI Components

The specification must include `servers` (defining your base URL), `paths` (describing individual endpoints), and `components/schemas` (defining data structures). Each operation requires a unique `operationId`, which the model uses as the function name when calling your API.

As implemented in the Zoom plugin reference at [`plugins/zoom/skills/rest-api/references/openapi.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/openapi.md), your specification should follow this structure:

```yaml
openapi: 3.0.1
info:
  title: Weather Service
  version: "1.0"
servers:
  - url: https://api.myweather.com/v1
paths:
  /forecast:
    get:
      summary: Get a weather forecast
      operationId: getForecast
      parameters:
        - in: query
          name: city
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forecast'
components:
  schemas:
    Forecast:
      type: object
      properties:
        temperature:
          type: number
        conditions:
          type: string

```

The `operationId` (`getForecast` in this example) becomes the function name the model calls when requesting weather data.

## Wiring the OpenAPI Spec into the Manifest

Once your OpenAPI document is hosted at a public HTTPS URL, update your [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to reference it:

```json
{
  "api": {
    "type": "openapi",
    "url": "https://raw.githubusercontent.com/your-org/weather-plugin/main/openapi.yaml"
  }
}

```

For local development, you can expose a temporary tunnel using tools like `ngrok` and point the manifest at the temporary HTTPS URL. Remember to replace this with a stable production URL before publishing your plugin.

## Configuring Authentication

If your endpoints require authentication, add an `auth` block to your manifest. The OpenAI platform handles the authentication handshake automatically and passes the resulting tokens to your backend.

### OAuth Configuration

For OAuth flows, specify the client ID and required scopes:

```json
"auth": {
  "type": "oauth",
  "client_id": "YOUR_CLIENT_ID",
  "scopes": ["weather.read"]
}

```

### API Key Authentication

For API key authentication, define the security scheme in your OpenAPI specification using `components/securitySchemes` and reference it from each operation. The manifest should remain unchanged or use `"type": "none"` if the key is passed through the OpenAPI-defined headers.

Reference the Zoom plugin's OAuth implementation at [`plugins/zoom/skills/zoom-apps-sdk/references/oauth.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/references/oauth.md) for a complete working example.

## Validating and Testing Your Endpoints

Before deploying, validate your configuration using the built-in test suite.

### Running the Plugin Evaluator

Execute the validation tests from the repository root:

```bash
npm run test:plugin-eval

```

This command runs the test harness located at [`plugins/plugin-eval/tests/plugin-eval.test.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/tests/plugin-eval.test.js), which validates your manifest against the schema and verifies that your OpenAPI document is parseable and complete.

### Testing in the OpenAI Playground

After validation, enable the Plugins toggle in the OpenAI Playground, load your plugin, and test with natural language queries. The model will translate requests like *"What's the weather in Paris?"* into the corresponding `getForecast` function call with the appropriate parameters.

## Common Pitfalls to Avoid

When defining API endpoints for your OpenAI plugin, watch for these specific issues:

- **HTTPS Requirement**: The OpenAI platform rejects non-TLS URLs. Always use `https://` for your OpenAPI specification URL.
- **Unique Operation IDs**: Ensure every `operationId` in your OpenAPI spec is unique and descriptive, as these become the function names the model uses.
- **Public Accessibility**: Verify your OpenAPI document is reachable from the public internet, not just localhost or internal networks.
- **Manifest Name Consistency**: The directory name containing your plugin must match the `name` field in your manifest (hyphen-case format).
- **Auth Mismatch**: If your endpoint requires authentication but the manifest specifies `"type": "none"`, calls will fail with `401 Unauthorized` errors.

## Summary

- **Create** a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file that declares your plugin's metadata and API location.
- **Write** an OpenAPI 3.0 specification describing every endpoint, using descriptive `operationId` values for function naming.
- **Host** the OpenAPI document on a publicly accessible HTTPS URL.
- **Configure** authentication in the `auth` block if your endpoints require OAuth or API keys.
- **Validate** your configuration using `npm run test:plugin-eval` before testing in the OpenAI Playground.

## Frequently Asked Questions

### What file format should I use for the OpenAPI specification?

You can use either YAML (`.yaml`) or JSON (`.json`) format for your OpenAPI specification. Both are supported equally by the OpenAI plugin platform, though YAML is generally preferred for readability when maintaining complex API definitions.

### Do I need to implement authentication for my plugin endpoints?

Authentication is optional. If your API is public, set `"type": "none"` in the auth block. However, if your endpoints require credentials, you must configure OAuth or API key authentication in both the manifest and your OpenAPI specification's security schemes.

### How does the model know which endpoint to call?

The model uses the `operationId` field defined in your OpenAPI specification to determine which endpoint to invoke. When a user makes a request that matches your API's capabilities, the model generates a function call using that `operationId` and passes the appropriate parameters based on the path and query definitions in your spec.

### Where can I find working examples of plugin manifests?

The `openai/plugins` repository contains complete working examples. Examine the Zoom plugin manifest at [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json) and the corresponding OpenAPI reference at [`plugins/zoom/skills/rest-api/references/openapi.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/openapi.md) to see production-ready configurations for complex REST APIs.