openai/openai-openapi: the OpenAI API as an OpenAPI 3.1 document
OpenAPI specification for the OpenAI API
At a glance
- What is it?
- openai/openai-openapi publishes the OpenAI REST API as a generated OpenAPI 3.1 file. It is a read-mostly artifact for code generation and tooling, not a place to send patches.
- Who is it for?
- Adopt openai/openai-openapi if you generate clients, mocks or API explorers from an OpenAPI document and want the official one rather than a hand-written approximation. Do not adopt it if you need human-readable guides, since the README points to developers.openai.com for those, or if you expect to fix schemas yourself: pull requests are limited to OpenAI team members and direct edits to openapi.yaml do not propagate upstream.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What the openai/openai-openapi repository actually contains
The repository is a publication channel for one artifact: a machine-readable description of the OpenAI REST API, authored in OpenAPI 3.1. The README says the spec covers endpoints, authentication, parameters, and request and response schemas. The top level holds openapi.yaml and openapi.json, plus LICENSE, README.md, CONTRIBUTING.md, SECURITY.md, AGENTS.md, an assets directory and .github. There is no application code, no build script you are meant to run, and no server.
That shapes who it is for. If you write a client library, generate typed bindings, feed a mock server, or load an API into a tool that consumes OpenAPI, this file is the input. If you want to read about how to call the API, the README sends you elsewhere: the note in the About section points to the OpenAI API docs for human-readable documentation, guides, and examples. The repository knowingly does not serve that audience.
The README also states that openapi.yaml and openapi.json are generated artifacts synchronized automatically from upstream source. That single sentence explains most of the repository's constraints, and it is the fact to keep in mind before opening a pull request.
Why generated artifacts change the contribution model
Because the YAML and JSON are generated, editing them here is not how a schema change lands. The README states that OpenAI maintainers make specification corrections in the upstream source using an internal OpenAPI authoring guide, and that the publication workflow updates this repository's generated YAML and JSON automatically. It says plainly that direct edits here do not update that source.
External input therefore goes through issues. The README welcomes issue reports and suggestions from everyone, while pull requests are limited to OpenAI team members. External contributors are told to use issues, including for documentation or asset suggestions, and CONTRIBUTING.md holds the full policy. OpenAI team members can still open pull requests here for repository policy, documentation, and assets, subject to required review.
This is a deliberate trade-off, not an oversight. A generated file cannot accept patches without the next regeneration overwriting them. The cost is latency: a schema fix has to move through the upstream authoring source and the publication workflow before it appears in openapi.yaml. If your team's workflow assumes you can fork and patch a spec locally, you can, but you will carry that patch forever.
Downloading openapi.yaml and openapi.json
There is nothing to install. The README gives two routes: browse openapi.yaml or openapi.json directly in the repository, or download the latest YAML version with curl. The README's own example is:
curl -L https://raw.githubusercontent.com/openai/openai-openapi/main/openapi.yaml \
-o openai-openapi.yamlAfter that command finishes, you should have a file named openai-openapi.yaml in the current directory containing the specification. The README does not document a versioned download URL or a checksum, so if you need a pinned revision, take it from a specific commit rather than main.
The document is OpenAPI 3.1, and the README says it can be imported into tools that support the OpenAPI ecosystem. That version matters more than it sounds. 3.1 aligns its schema dialect with JSON Schema, so generators and validators that only understand 3.0 may reject or silently misread parts of the document. Check your generator's supported version before you build a pipeline around this file.
A first real use is client generation. Point your generator at the downloaded file, choose a language, and let it emit models and endpoint methods. The README notes that OpenAI publishes official SDKs for Python, JavaScript and TypeScript, .NET, Go, Java and Ruby, all generated from this specification. If one of those covers your language, generating your own is mostly a way to control naming, dependency footprint or vendoring.
Where the spec stops being the right tool
The repository documents no rollback mechanism for the published artifacts. If a regeneration introduces a schema change that breaks your generated client, the README says nothing about reverting the published file or about a deprecation window. Your practical fallback is pinning to an earlier commit and diffing before you upgrade, which is work the repository does not do for you.
The second limitation is scope. The README describes the spec as covering endpoints, authentication, parameters, and request and response schemas. It does not promise prose explanations, migration notes, or runnable examples, and it explicitly redirects readers who want guides and examples to the API docs. A team that wants to understand why a parameter exists will not find the answer here.
The third is support. The README says the OpenAI team will make a best-effort attempt to triage and resolve spec issues. That is not a service-level commitment. If your release schedule depends on a schema fix landing by a particular date, this repository is the wrong dependency to bet a deadline on. Security problems follow a different path entirely: the README asks that suspected vulnerabilities be reported privately using SECURITY.md, not in public issues or pull requests.
openai/openai-openapi versus the official SDK repositories
The obvious alternative is not another spec, it is the official SDKs listed in the README: openai-python, openai-node, openai-dotnet, openai-go, openai-java and openai-ruby. Both routes trace back to the same specification, since the README states the SDKs are generated from it. The difference is what you get on top.
An SDK is an opinionated, tested surface with its own release cycle, changelog and language idioms. The spec is the raw contract: every endpoint, parameter and schema in one document, with no runtime behavior attached. Choosing the spec means you own the generation step, the naming conventions and the upgrade diff. Choosing an SDK means someone else owns those, and you accept their abstraction.
The spec wins when you are not writing application code at all: building an API explorer, configuring a testing tool, generating mocks, or feeding a gateway that validates requests against a contract. It also wins when your language has no official SDK. It loses when you just want to call the API from Python or TypeScript and have no reason to care about the underlying schema.
Licence, maintenance and the cost of staying current
The project is licensed under the MIT License, per the README and the LICENSE file at the repository root. That is permissive and places few conditions on reuse, including in commercial tooling. It covers the specification artifacts and repository contents; it is not a licence for the OpenAI API service itself, and nothing here should be read as legal advice about your own distribution.
Maintenance is not in question on the publication side. The repository is not archived, and the last push was on 2026-09-13, one day before this writing, which is consistent with the README's description of an automatic synchronization workflow. The generated files move on their own schedule.
Upgrade cost is where the real work sits, and the release history is worth reading carefully. The most recent release listed is 2.0.0 from 2023-06-19, preceded by 1.3.0 on 2023-06-13. Those tags are old relative to the ongoing pushes, which suggests the release tags are not how the specification is versioned for consumers. If you need a stable reference point, pin a commit hash rather than waiting for a tag. Budget for a diff review each time you refresh the file, because the README describes no compatibility guarantee between regenerations.
Reporting a schema problem without wasting a cycle
The feedback process is specific, and following it saves a round trip. The README asks you to search existing issues first, then open a new one if the problem has not been reported. For a non-security problem, the report should include the affected revision, the endpoint and HTTP method or the schema, the expected behavior, and a minimal example using synthetic data. Credentials, customer data and private URLs should be stripped from examples and diagnostic output.
That last requirement is not boilerplate. A schema bug report is often easiest to demonstrate with a real request, and a real request carries an API key. The README treats removing it as part of the report, and security issues are routed away from public issues entirely via SECURITY.md.
For immediate help with the API itself, as opposed to the specification, the README points to OpenAI Support through help.openai.com. Knowing which channel applies to your problem is the difference between a triaged issue and a closed one.
Editorial conclusion
Adopt openai/openai-openapi if you generate clients, mocks or API explorers from an OpenAPI document and want the official one rather than a hand-written approximation. Do not adopt it if you need human-readable guides, since the README points to developers.openai.com for those, or if you expect to fix schemas yourself: pull requests are limited to OpenAI team members and direct edits to openapi.yaml do not propagate upstream. Before wiring it into a pipeline, check whether a schema gap you hit is already in the issue tracker, and confirm your toolchain handles OpenAPI 3.1 rather than 3.0.
Frequently asked questions
What is the openai/openai-openapi specification?
It is a machine-readable description of the OpenAI REST API, authored in OpenAPI 3.1, published as openapi.yaml and openapi.json. The README says it describes the API's endpoints, authentication, parameters, and request and response schemas.
How do I download the openai openapi yaml file?
The README gives a curl command that fetches openapi.yaml from the main branch of the repository and writes it to a local file. You can also browse openapi.yaml or openapi.json directly in the repository.
Can I submit a pull request to openai/openai-openapi?
Pull requests are limited to OpenAI team members, and external contributors are asked to use issues instead, including for documentation or asset suggestions. The README also states that direct edits to the generated YAML and JSON do not update the upstream source.
What OpenAPI version does the openai openapi schema use?
The README states the document uses OpenAPI 3.1 and can be imported into tools that support the OpenAPI ecosystem. Generators built only for OpenAPI 3.0 may not handle it correctly.
Are the official OpenAI SDKs generated from this openai openapi definition?
Yes. The README lists official SDKs for Python, JavaScript and TypeScript, .NET, Go, Java and Ruby, and states they are generated from this specification.
How do I report an incorrect schema in openai/openai-openapi?
Search the existing issues first, then open a new one including the affected revision, the endpoint and HTTP method or schema, the expected behavior, and a minimal example using synthetic data with credentials removed. Suspected vulnerabilities go through SECURITY.md instead of public issues.
Community notes