An OpenAPI Overlay is a small document that changes an OpenAPI contract without touching it. Each action pairs a JSONPath target with an update or a removal, and you apply the overlay on top of the original. For integration that means you can fix a missing operationId, add the descriptions an agent needs, or point at the right servers, all without forking the provider’s spec. The overlays index on apis.io holds 29,288 of them across 3,883 providers, carrying 188,703 actions between them. The median overlay has 4.
Almost all of them are ours.
Who wrote them
| Authorship recorded | Overlays |
|---|---|
| generated | 24,910 |
| unmarked | 3,977 |
| derived | 236 |
| provider | 148 |
Count by purpose and phrasing leads, with 16,031 overlays across 379 providers. Those are the x-apievangelist-phrasing overlays, which attach the questions people actually ask to each operation. Next come general updates (10,358), documentation (1,654), servers (717) and security (511).
The provider row is wrong
That provider row of 148 does not hold up. 146 of the 148 overlays labeled authorship: provider are titled, in their own source, “API Evangelist enhancements for…” They are concentrated in HERE (48), Avaya (40) and Cisco ISE (32). Take Vim’s as an example. Its provenance block says method: searched, and the thing that was searched for is the underlying OpenAPI, which Vim’s docs ship inside a JavaScript bundle. The overlay itself is API Evangelist’s work. It adds the two operationIds Vim’s document leaves unset, rate limits, consequence notes, and sandbox IDs for two of the reads. The overlay’s own apis.io entry then describes it as “an OpenAPI Overlay Vim publishes.” That is a labeling defect in our pipeline. It credits providers with work they did not do. I’m not crediting them for it here, and it needs fixing in the build.
So the honest count of provider-written overlays is very small. Only 10 files in the whole collection are marked as hosted by the provider. They are spread across seven small providers, two of which (Yawplet and Yarnhen) are sites in our own network.
The collection has quality problems of its own too. 185 overlays have zero actions. 83 have an overlay_version that parsed as an object instead of a version string, because the source file put an object, usually an empty actions list and sometimes a JSON Patch or partial OpenAPI document, where the version belongs. Another 107 declare no version at all. None of those is a valid Overlay document.
What a good one looks like
The Vim overlay, apart from its label, is the model. It targets specific operations rather than $.info alone. It records why each change exists (“operationId absent in the provider document; supplied by overlay only”). It never mutates the original. And it states the consequence of each write, for example “not idempotent; 409 on unique-field conflict is the only guard.” That is the kind of note an agent needs before it calls a write, and the kind most contracts leave out.
Takeaway
Overlays are the cheapest way for a provider to improve a contract it cannot easily change, and almost no provider in the catalog publishes one. Anyone can query the collection through the apis.io MCP’s find_overlays tool. Three fixes are on us: correcting the 146 mislabeled files, dropping the 83 malformed ones, and keeping “generated” and “provider” strictly apart. The one move that belongs to providers is shipping even one overlay next to their spec, so the improvements stop living only on our side.
Browse them at apis.io/overlays/.