# openai/openai-openapi: the generated OpenAPI 3.1 spec for the OpenAI REST API

> The repository publishes openapi.yaml and openapi.json as generated artifacts, not as an editable source. That single design decision explains both its usefulness and its limits.

**openai/openai-openapi** — OpenAPI specification for the OpenAI API

- Repository: https://github.com/openai/openai-openapi
- Website: https://platform.openai.com/docs/api-reference/introduction
- Stars: 2,534 · Forks: 528
- Language: Unknown
- License: MIT
- Published: 2026-09-14 · Updated: 2026-09-14 · Language: en
- Canonical page: https://hysenlabs.com/projects/openai-openai-openapi

## What openai/openai-openapi actually ships

This repository publishes a machine-readable description of the OpenAI REST API, authored in OpenAPI 3.1. According to the README, the spec describes the API's endpoints, authentication, parameters, and request and response schemas. The repository layout matches that claim: the top level holds openapi.yaml, openapi.json, assets/, and a set of policy files (AGENTS.md, CONTRIBUTING.md, LICENSE, README.md, SECURITY.md), with no source tree and no build scripts.

The intended audience is narrower than the name suggests. The README lists four uses: generating typed clients, building API explorers, configuring testing tools, or working with the OpenAI API in any OpenAPI-compatible workflow. If you want prose documentation, guides and examples, the README points elsewhere, to the OpenAI API docs. So this is a contract artifact for tooling, not a reading experience for humans.

The licence is MIT, which is permissive and places few conditions on redistribution. That matters if you plan to vendor the YAML into a private repository or ship it inside a generated client.

## Generated artifacts, and why you cannot fix the spec here

The important mechanism is stated plainly: openapi.yaml and openapi.json are generated artifacts synchronized automatically from upstream source. OpenAI maintainers make specification corrections in the upstream source using an internal OpenAPI authoring guide, and the publication workflow updates this repository's generated YAML and JSON automatically. The README adds a warning that direct edits here do not update that source.

That has a practical consequence. A pull request against openapi.yaml is not a path to a fix, and the contribution policy confirms the asymmetry: issue reports and suggestions are welcome from everyone, but pull requests are limited to OpenAI team members. External contributors are told to use issues, including for documentation or asset suggestions. OpenAI team members can submit pull requests here for repository policy, documentation, and assets, subject to required review.

The feedback section is specific about what a good report contains: the affected revision, endpoint and HTTP method or schema, the expected behavior, and a minimal example using synthetic data. It also asks you to remove credentials, customer data, and private URLs. Suspected vulnerabilities go through SECURITY.md, not public issues. The README describes the team's triage and resolution of spec issues as a best-effort attempt, which is worth reading as a statement about response time rather than a guarantee.

One more thing to weigh: the two releases listed are 1.3.0 on 2023-06-13 and 2.0.0 on 2023-06-19. Releases are not the delivery channel for this repository. The generated files change on the default branch, so version numbers tell you little about how current the spec is. The last push was on 2026-09-13, which is the more useful signal here.

## Install and first use: curl the YAML, then lint it

There is nothing to install. The README gives one download command for the latest YAML version, which writes the document to a local file named openai-openapi.yaml:

```bash
curl -L https://raw.githubusercontent.com/openai/openai-openapi/main/openapi.yaml \
  -o openai-openapi.yaml
```

You can also browse openapi.yaml or openapi.json directly in the repository. Pin a revision if the spec feeds a build, because the default branch moves whenever the publication workflow runs.

Once the file is on disk, the first real use is to check that your OpenAPI tooling parses it, since the document is OpenAPI 3.1 and older parsers may reject it. The README does not name a validator, so use whatever your toolchain already provides; the point of the first run is to confirm the 3.1 version is accepted before you wire it into client generation.

The second use is generation. The README lists official SDKs generated from this specification for Python, JavaScript and TypeScript, .NET, Go, Java, and Ruby, each in its own repository. If you are generating your own client, treat those repositories as reference points for what a faithful generation looks like rather than as replacements for your generator's output.

## Where openai/openai-openapi is the wrong tool

The README is explicit that human-readable documentation, guides, and examples live elsewhere. If you are trying to answer "what does this parameter do and when should I use it", the spec is a poor source. It carries schemas and descriptions, but the explanatory material the README points to is on the docs site, not in this repository.

The second limitation is the contribution model. If your workflow assumes you can patch the spec and upstream the change, it does not fit here. You can fork and edit your copy, but the README states that direct edits in this repository do not update the upstream source, so your fork drifts from the published artifact with every workflow run. For a schema error, the documented route is an issue with the affected revision, endpoint and HTTP method, plus a minimal example using synthetic data.

Third, this is a description of a remote service, not the service itself. Nothing here lets you run the OpenAI API locally, and the spec cannot tell you about rate limits, latency or account state. It also says nothing about pricing or access, so questions about whether the API is free are outside what this repository answers.

Finally, the release history offers no compatibility promise you can lean on. With 2.0.0 in June 2023 and no later releases listed, there is no changelog trail in the releases themselves to tell you when a field was added or removed. If you need that audit trail, you have to diff the generated files at two revisions yourself.

## How this differs from the official SDKs and from hand-written clients

The obvious alternative is the official SDK for your language. The README names six: openai-python, openai-node, openai-dotnet, openai-go, openai-java, and openai-ruby. The difference in approach is one of layer. An SDK gives you idiomatic types, retries and request plumbing for one language, maintained by OpenAI. The spec gives you the raw contract in a language-neutral format that any OpenAPI-compatible tool can consume.

That distinction decides the choice. If you are writing application code in a supported language, the SDK is the shorter path. If you are building a generator, an API explorer, a mock server, or a contract test that must cover many languages at once, the spec is the artifact you want, and the SDKs are downstream consumers of the same document.

A second alternative is writing the client by hand against the API reference. That gives you full control and no generator surprises, at the cost of tracking every schema change yourself. The spec does not remove that cost, but it moves the tracking to a file you can diff.

## Maintenance, upgrades and licence in practice

Maintenance here is not a matter of merging community patches. The publication workflow updates the generated YAML and JSON automatically, and corrections originate in an upstream source that external contributors cannot reach. The last push was on 2026-09-13, so the generated files are current as of that date.

Upgrade cost is mostly your own tooling's problem. Because there is no release cadence to follow, you pin a revision or a commit and re-pull when you choose. The README offers no rollback guidance and no versioning policy for the generated files, so a diff between your pinned copy and the current default branch is the only reliable way to see what changed. Budget for that diff review rather than assuming a release note will summarise it.

The MIT licence is permissive and does not restrict commercial use or modification of your copy. That is a statement about the licence text, not legal advice; if you redistribute the spec inside a product, read LICENSE and your own obligations. Note that the licence covers this specification repository, not the OpenAI API service it describes.

## Conclusion

Adopt it if you need a machine-readable OpenAI API surface for client generation, API explorers or contract tests, and you accept that the YAML and JSON are generated artifacts. Do not adopt it if you need human-readable guides, or if you want to submit a schema fix as a pull request, because pull requests are limited to OpenAI team members. Before relying on it, verify that the specific endpoint, parameter or schema you depend on appears in openapi.yaml at the revision you pin, and open an issue with the affected revision, endpoint and HTTP method if it does not.

## FAQ

### Is Swagger now called OpenAPI?

The README does not discuss Swagger. It states only that this repository's document is authored in OpenAPI 3.1 and can be imported into tools that support the OpenAPI ecosystem.

### What is OpenAPI versus an API?

In this repository, OpenAPI is the format: a machine-readable description of the OpenAI REST API covering endpoints, authentication, parameters, and request and response schemas. The API itself is the remote service; the spec is the document describing it.

### Is the OpenAI API free?

The repository does not address pricing or access. Its README covers the specification, the generated SDKs, the contribution policy, feedback and the MIT licence, and points to OpenAI Support for immediate help with the API.

## Sources

- [License: MIT](https://github.com/openai/openai-openapi/blob/main/LICENSE)
- [openai/openai-openapi on GitHub](https://github.com/openai/openai-openapi)
- [Project website](https://platform.openai.com/docs/api-reference/introduction)
- [README](https://github.com/openai/openai-openapi/blob/main/README.md)
- [Releases](https://github.com/openai/openai-openapi/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openai-openai-openapi