OpenAI publishes an official OpenAPI spec at openai/openai-openapi, maintained by OpenAI itself. You can generate a typed client from it in minutes. OpenAI already ships official SDKs for Python and Node/TypeScript (plus community-maintained ones for Go, Java, and .NET) — so this isn't about replacing openai-node. It's for a language OpenAI's official list doesn't cover, an internal wrapper around a specific model configuration, or generating typed tool schemas for an agent framework.
Where the spec lives
| Fact | Value |
|---|---|
| Repo | openai/openai-openapi |
| File | openapi.yaml (also openapi.json) |
| Spec version | OpenAPI 3.1.0, API version 2.3.0 |
| Size | ~3.6 MB, ~106,000 lines |
| License | MIT |
| Covers | Chat, Assistants, Audio, Conversations, Embeddings, Fine-tuning, and more, per the repo's own tag list |
How to fetch it
curl -sL -o openai-openapi.yaml \
https://raw.githubusercontent.com/openai/openai-openapi/main/openapi.yaml
The honest complication: OpenAPI 3.1 plus heavy oneOf/anyOf
Two things compound here. First, this is a genuine OpenAPI 3.1 spec (openapi: 3.1.0 at the top of the file), using real JSON Schema 2020-12 — see OpenAPI 3.1 vs 3.0 if your generator or validator is 3.0-only, since that's a hard blocker, not a warning.
Second, the schema style leans hard on unions. A direct scan of the file:
grep -c "anyOf:" openapi.yaml # 1088
grep -c "oneOf:" openapi.yaml # 345
Over 1,400 union sites, driven by things like the Chat Completions request body (where content can be a plain string or an array of typed content parts), streaming vs non-streaming response shapes, and the many input/output variants across the Responses and Assistants APIs. Generators that handle 3.1's type: [string, "null"] syntax and discriminated oneOf correctly will produce clean, usable types; generators still catching up to full 3.1 support will fall back to loosely-typed unknown or any in the union-heavy spots. Test against a single endpoint like /chat/completions before generating the whole spec, since that endpoint alone exercises most of the union patterns you'll hit elsewhere.
Generate a TypeScript client locally
npx @openapitools/openapi-generator-cli generate \
-i openai-openapi.yaml \
-g typescript-fetch \
-o ./generated/openai-client
Confirm your OpenAPI Generator version is recent enough to have solid 3.1 support — older cached versions of the CLI default to Swagger 2.0-era assumptions and will mishandle the "null" type unions. For types-only output paired with a hand-written fetch wrapper, openapi-typescript tends to track 3.1 support faster:
npx openapi-typescript openai-openapi.yaml -o ./src/openai-api.d.ts
Run the spec through a validator first — the free OpenAPI validator flags 3.1-specific issues before you spend codegen time on them.
The hosted path
Sourced reads OpenAPI 3.1 natively. Paste the raw openapi.yaml URL or point at your repo and it produces hosted docs, a TypeScript SDK preview, a Python SDK preview, and an llms.txt file — with the union-heavy Chat/Responses schemas resolved by the pipeline rather than something you debug generator-by-generator. Previews are free and unlimited, with up to two hosted noindex docs sites and one hosted MCP server, no credit card required.
When this actually makes sense
- Learning 3.1-aware codegen. OpenAI's spec is one of the largest public OpenAPI 3.1 documents available, so it's a realistic target for testing whether your toolchain actually handles 3.1 correctly, not just accepts the version string.
- A language OpenAI doesn't officially support — the official SDK list covers Python and Node/TS directly; other languages rely on community packages of varying quality.
- Internal wrappers around a fixed model/parameter configuration, where you want generated request/response types without the full
openaipackage's surface area. - Agent tooling. Feeding the OpenAI spec into an MCP server generator or a typed tool-schema pipeline gives an agent framework structured access to OpenAI's own API — useful when you're building tooling that orchestrates OpenAI calls programmatically rather than calling the SDK directly in application code.
If you're writing a Python or Node/TypeScript app that calls the OpenAI API, use openai (the official package) for that language. It's maintained by OpenAI, ships type definitions by hand-tuned as well as generated, and tracks new endpoints and streaming behavior as they ship — a third-party-generated client will lag behind by definition.
FAQ
Does OpenAI have an official OpenAPI spec?
Yes. openai/openai-openapi is maintained by OpenAI and kept in sync with the live API — it's not a community reconstruction.
Is the OpenAI OpenAPI spec 3.0 or 3.1?
3.1.0. If your generator or validator only supports OpenAPI 3.0, this spec will fail to parse correctly rather than just producing weaker types — check 3.1 support before you invest time in a generator.
Why are so many fields typed as unions in the generated client?
OpenAI's request/response shapes are genuinely polymorphic — chat message content can be a string or an array of typed parts, and responses differ between streaming and non-streaming modes. The spec models this with oneOf/anyOf (over 1,400 sites total), and how well that survives codegen depends entirely on your generator's union handling.
Should I generate a client instead of using openai?
Not for Python or Node/TS — use the official openai package; it's actively maintained and tracks the API in real time. Generate a client for other languages, internal wrappers, or agent/tool-schema use cases.
Does the OpenAI spec cover every API, including the Assistants and Responses APIs?
The repo's tag list spans Chat, Assistants, Audio, Conversations, Embeddings, Fine-tuning, and more — check the current openapi.yaml for the exact endpoint list before you generate, since OpenAI ships new endpoints regularly and the spec is what tracks them.
Can Sourced handle the 3.1-specific parts of this spec?
Yes — Sourced accepts both OpenAPI 3.0 and 3.1 input, including this spec's "null" type unions and JSON Schema 2020-12 features, and produces docs and SDK previews from it directly. Start a free preview to see the generated output before deciding whether to publish it.