OpenAPI and the ChatGPT API: the two things that phrase means, and how to use each one

The phrase "OpenAPI ChatGPT API" covers two separate jobs and the first thing to do is work out which one you are on. Either you want the machine readable OpenAPI description of OpenAI's own REST API, so you can generate a client, a mock server or request validation from it, and OpenAI publishes exactly that in the public repository openai/openai-openapi. Or you want to describe your API in an OpenAPI document so that ChatGPT can call it as a tool on your behalf, which is a document you write and host. The two use the same file format and almost nothing else. The sections below cover both, with a working example of the second.

This page covers OpenAPI documents on both sides of the ChatGPT API. For what calls cost, see ChatGPT API cost, and for what is free against what is billed, see ChatGPT free API.

First, what OpenAPI is

OpenAPI is a format for describing an HTTP API in one machine readable document: the endpoints, the methods, the parameters, the request and response shapes, and the authentication. It is maintained by the OpenAPI Initiative, and the specification text for version 3.1.0 is published at spec.openapis.org. Version 3.1 aligns the schema part of the format with JSON Schema, so the same schema snippets work in both places, and write 3.1 for anything new. There is a short introduction at learn.openapis.org if you have never written one.

Note the spelling. OpenAPI is the description format. OpenAI is the company.

What you want	Where it comes from	What you do with it
A description of OpenAI's REST API	The public openai/openai-openapi repository	Generate a typed client, a mock server, request validation, or a diff between versions
A description of your own API for ChatGPT to call	You write and host it	Register it as an action or connector so the assistant can call your endpoints

Route one: OpenAI's published OpenAPI description

Checked on 10 October 2026, the repository github.com/openai/openai-openapi is described as the OpenAPI specification for the OpenAI API and is published under the MIT licence. It contains the description in two equivalent files, openapi.yaml and openapi.json. The header of the YAML file on the same date declares openapi: 3.1.0, an info.version of 2.3.0, a title of "OpenAI API", and a single server entry of https://api.openai.com/v1. OpenAI's own API reference documentation remains the authoritative description of behaviour; the OpenAPI file is the machine readable shape of it.

Four things worth generating from it:

• A typed client in your language. The OpenAPI Generator project takes the document and emits client code for a long list of languages, which is most useful where there is no first party SDK you want to use.
• A mock server, so your test suite runs without network calls, spend or hand written stubs.
• Request validation in your own gateway. If you proxy model calls through your own service, validating the inbound body against the schema catches malformed requests before they cost you a billed call.
• A diff between two versions. Pull the file at two commits and diff it for a precise list of endpoints, parameters and fields added, removed or changed, which is far faster than rereading release notes.

# fetch the description and inspect it locally
curl -sL -o openapi.yaml \ https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml # list every path in the document
grep -E '^ /' openapi.yaml | sed 's/://' # validate and bundle it with a linter before generating anything
npx @redocly/cli@latest lint openapi.yaml

One habit worth keeping: pin the commit you generated from and record it in your repository. When a generated client behaves differently, the first question is which version of the description produced it.

Route two: an OpenAPI document ChatGPT can call

This is the more common intent behind the search. You have an API, you want ChatGPT to call it, and the way you describe that API to the assistant is an OpenAPI document. The shift in thinking is that the document is read by a language model deciding whether and how to call you, so the prose in it is functional. Descriptions are instructions.

What the document needs:

• A single HTTPS server URL, reachable from the public internet, with a valid certificate.
• A unique, readable operationId on every operation. This is the handle the assistant uses. searchInventory is useful. get_v2_items_1 is not.
• A one line summary and a fuller description per operation, written as when to use this: what it does, what it does not do, and which of your operations to prefer when two could apply.
• A description on every parameter and schema property, with units, formats and allowed values. Use enum wherever the set is closed.
• Narrow, concrete response schemas. Return the fields that answer the question. Four hundred fields spends the context window and makes the answer worse.
• A declared security scheme, in components.securitySchemes and referenced by the operations.

openapi: 3.1.0
info: title: Inventory lookup description: Read only stock and price lookups for the public catalogue. version: 1.0.0
servers: - url: https://api.example.com/v1
paths: /items: get: operationId: searchInventory summary: Search the catalogue by text and return stock and price description: > Use this to answer questions about what is in stock, how many units remain, and the current price. Returns at most 20 items. Does not place orders and does not read customer records. parameters: - name: q in: query required: true description: Free text search over item name and SKU. schema: type: string - name: warehouse in: query required: false description: Restrict to one warehouse code. schema: type: string enum: [LON, MAN, EDI] responses: "200": description: Matching items. content: application/json: schema: type: object properties: items: type: array items: type: object properties: sku: type: string description: Stock keeping unit. name: type: string units_available: type: integer description: Whole units in stock. price_gbp: type: number description: Price per unit in GBP, excluding tax. required: [sku, name, units_available, price_gbp]
components: securitySchemes: apiKey: type: apiKey in: header name: X-API-Key
security: - apiKey: []

Where this is different from function calling

When you call the API yourself and want the model to use your tools, you pass tool definitions in the request as JSON Schema, in your own code, and you execute the call when the model asks for it. You are making the HTTP request. When you hand ChatGPT an OpenAPI document instead, the assistant side does the calling against the server URL in the document. The first route suits a product you are building; the second suits exposing an existing API to people working inside ChatGPT. The schema discipline is identical in both.

A third route exists. The Model Context Protocol is an open standard for exposing tools and data to assistants over a dedicated protocol rather than as an HTTP description, designed for the case where one server serves several different assistants.

Debugging an action that is not being called

• Lint the document. An invalid document fails before anything else. Fix every error, not just the blocking ones.
• Read your own descriptions as instructions. If two operations could plausibly answer the same request, say in each description which to prefer and when.
• Check the server URL from outside your network. Certificate problems, firewall rules and staging URLs account for a large share of silent failures.
• Return useful errors. A 400 with a body explaining which parameter was wrong lets the assistant correct itself. A bare 500 ends the attempt.
• Shrink the response. If calls succeed but answers are vague, the payload is too large. Add filtering parameters and trim the default fields.
• Log every inbound request with its parameters. Your access log shows what was asked for.

Which file should I use, openapi.yaml or openapi.json?

They describe the same API. Use the YAML file for reading and reviewing in version control, and the JSON file where a tool expects JSON. Pick one per project so diffs stay clean.

Is the published OpenAPI description a complete reference?

Treat it as the machine readable shape of the API and the documentation as the reference for behaviour. The document gives you endpoints, parameters, schemas and auth, which is what code generation needs. Semantics such as rate limit behaviour and model specific details live in the documentation.

How do I keep the document in step with the code?

Generate it from the code where your framework supports that, and lint it in continuous integration so a change that breaks the document fails the build. Where the document is handwritten, add a contract test that calls each documented operation and checks the response against its schema.

What should I never expose through an action?

Write operations that move money or delete data, anything returning personal data without an authenticated user context, and anything with no rate limit. Start read only, scope the key tightly, and add write operations one at a time behind confirmation.

One more thing worth measuring once your API is callable

Once an assistant can call your API, the next question is whether it ever recommends your product. Ask ChatGPT, Gemini, Perplexity, Claude and Google's AI Overviews the questions a buyer in your category would ask, without naming your company, and record which products get named and which pages are cited. The five answer differently from each other, and the sources behind the answer are usually documentation, comparison pages and community threads rather than a home page, which makes the gap fixable. AI Knows Us runs that comparison across the five and reports the sources each answer was built from, and the first scan needs no account.