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

Define API endpoints for your OpenAI plugin by creating a manifest file at .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 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, a minimal manifest structure looks like this:

{
  "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, your specification should follow this structure:

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 to reference it:

{
  "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:

"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 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:

npm run test:plugin-eval

This command runs the test harness located at 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 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 and the corresponding OpenAPI reference at plugins/zoom/skills/rest-api/references/openapi.md to see production-ready configurations for complex REST APIs.

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