APIs-guru/openapi-directory: a CC0 catalogue of OpenAPI definitions you can clone and query

The gap APIs-guru/openapi-directory fills

Public APIs rarely publish a machine-readable contract in a predictable place. Some ship a Swagger 2.0 file, some an OpenAPI 3.0 or 3.1 document, some only an HTML reference. Anyone building a client generator, a mock server, an API search index or a parser test suite ends up collecting those files by hand, and the collection goes stale the moment it is finished. APIs-guru/openapi-directory exists to hold that collection in one repository and keep it refreshed. The README states the goal plainly: create the most comprehensive, standards-compliant and up-to-date directory of machine-readable API definitions. The stated principles are that it is open source and community driven, that it only includes publicly available APIs whether free or paid, that anyone can add or change an entry rather than only the API owner, and that all data is reachable through a REST API. The audience is therefore tool authors and integration platforms, not application developers looking for one client library. The repository topics list aws, azure and google-api alongside oas and openapi3, which reflects how much of the collection comes from large cloud vendors whose specifications are otherwise scattered across separate documentation sites.

What happens between an original spec and the file in APIs/

The repository is not a passive mirror. The README lists four things the project does to incoming definitions: filter out private and non-reliable APIs, convert non-OpenAPI formats into OpenAPI 3.x, fix mistakes (the README claims roughly 80% of definitions have some), and add extra data such as logos and categories. Acceptance is governed by three criteria: the API must be public, meaning anyone can access it after clearly defined steps such as subscribing or paying fees; it must be persistent rather than built for a conference or hackathon; and it must be useful beyond its owner. Updates come from the original source rather than from manual edits. Each openapi.yaml or swagger.yaml carries an x-origin property recording where the definition was fetched from, and the README says the update script runs at least weekly and revalidates automatically before committing. That last point is the part worth understanding: the pipeline validates the document before it lands in the tree, but validation is against the OpenAPI specification, not against the live API. A definition can be schema-correct and still describe endpoints that no longer behave as written. The README also points to a backup validation process run by a contributor against the official OpenAPI JSON Schemas, and says that if APIs go unupdated for more than two weeks, an issue should be opened. That is a manual escalation path, not a guarantee.

Cloning the directory and querying the index API

There is no package to install and no server to run. The definitions live in the APIs/ directory of the repository, and the index is served from api.apis.guru. The README gives the REST API documentation as the entry point for programmatic access, and lists RSS feeds for added and updated APIs. A practical first step is to clone the repository and confirm the layout, since the per-API folder naming is what every downstream tool assumes.

git clone https://github.com/APIs-guru/openapi-directory.git
ls APIs

You should see one directory per provider, each containing versioned subdirectories with openapi.yaml or swagger.yaml inside. If you only need the index rather than the documents, the REST API is lighter. The README links the API documentation at api.apis.guru; the feeds below are the two endpoints it names explicitly for change tracking.

curl https://api.apis.guru/v2/list.json -o list.json
curl https://api.apis.guru/v2/added.rss

The first command retrieves the full list of APIs with their available versions and metadata, which is the structure most integrations consume instead of walking the git tree. The second returns an RSS feed of newly added APIs; the README also names a feed at http://api.apis.guru/v2/list.rss for updated ones. If you are building a parser test suite, point it at a handful of files under APIs/ rather than the whole tree, because the collection is large and the documents vary widely in size and in the OpenAPI version they target.

Where the directory is the wrong source

The directory is community maintained and explicitly accepts changes from anyone, not only from API owners. That is the design, and it has a consequence: an entry is a best-effort reconstruction, not a vendor-published contract. If you are generating a client for a payment or identity provider and the definition disagrees with the vendor's own published specification, the vendor wins and the directory entry is the bug. The README's own framing supports this reading, since it describes fixing mistakes in definitions rather than guaranteeing their accuracy. The update cadence is also a limit. A weekly refresh means a breaking change published by an API owner on Monday may not appear until the following week, and the README treats two weeks without an update as the threshold for filing an issue. There is no documented rollback mechanism if a revalidated definition turns out to be wrong, and the README does not describe one. Finally, the acceptance criteria exclude anything private or short-lived, so internal APIs, partner-only endpoints and hackathon projects are out of scope by rule. If your work depends on those, the directory will never contain them.

How it differs from generating clients from a single spec

The obvious comparison is with OpenAPI Generator, which takes one specification as input and emits client code, server stubs or documentation. The two solve different halves of the problem. OpenAPI Generator is a code generator with a template system and a large set of target languages; it assumes you already have the specification you care about. APIs-guru/openapi-directory is the supply of specifications, plus normalisation and an index, and it does not generate code at all. The README positions the project as a source that other tools consume: it lists Microsoft Kiota for client generation, ReDoc for reference documentation, swagger-parser and OpenAPI-schema-validator as validators, and Speakeasy and swagger-parser among the projects that use the directory as a test suite. So the realistic combination is to pull a definition from the directory or the list.json endpoint and hand it to a generator or validator, rather than choosing one over the other. The difference that matters in practice is freshness and provenance. A generator run against a spec you fetched yourself has a known origin and a known date; a definition from this directory has an x-origin property recording its source and a last-update time you should check before trusting it.

Licence, maintenance and the cost of tracking it

The repository is licensed CC0-1.0, which places the collection in the public domain to the extent the project can do so. That is unusually permissive for a data set and removes the attribution questions that usually accompany API metadata, though it says nothing about the terms of the APIs described inside. Each definition describes a third-party service with its own terms of use, and the CC0 grant covers the definition files, not the services. On maintenance, the last push to the main branch was on 2026-04-20, which is more than six months before today; the repository is not archived, but that gap is long enough that the weekly update claim in the README should be verified against the current commit history rather than assumed. Upgrade cost is low in the conventional sense because there are no dependencies to bump. The real cost is re-syncing: if you vendor definitions into your own repository, you need a process to pull the upstream changes and re-run your validation, and the RSS feeds for added and updated APIs are the mechanism the project provides for that. The README notes that logos, categories and other added metadata live alongside the specifications, so a downstream consumer that depends on those fields is coupled to this project's conventions rather than to the OpenAPI specification alone.

Editorial conclusion

Adopt it if you need a large corpus of real-world OpenAPI documents for testing a parser, generating clients or seeding a search index, and you accept that each definition is only as correct as the community fix applied to it. Do not adopt it as the source of truth for a single vendor's API contract; pull that vendor's own specification instead. Before relying on any entry, open its openapi.yaml or swagger.yaml and read the x-origin property to see where the definition came from and when it was last refreshed.

Frequently asked questions

Official sources

1. APIs-guru/openapi-directory on GitHub
2. Issues
3. License: CC0-1.0
4. Project website
5. README