# Twenty-Five Thousand Overlays, And None Of Them Are Yours Yet

**Published:** 2026-10-13  
**Author:** Kin Lane  
**Canonical:** https://apievangelist.com/2026/10/13/twenty-five-thousand-overlays-and-none-of-them-are-yours-yet/

Last week I wrote about [Overlay 1.2 and the fourteen jobs we already use Overlays for](https://apievangelist.com/2026/10/06/overlay-1-2-and-the-fourteen-jobs-we-already-use-it-for/), and then [about why an Overlay is a layer and not a diff](https://apievangelist.com/2026/10/08/an-overlay-is-a-layer-not-a-diff/). Both posts leaned on a number, that the APIs.io catalog holds tens of thousands of Overlay documents, and both admitted that nearly all of them are mine. There is now an [Overlays section on APIs.io](https://apis.io/overlays/) that makes that admission structural. It lists 25,011 Overlays across the network, each one labelled with who wrote it and what its actions touch, and the group it puts first, the Overlays a provider publishes on its own domain, is the group that is almost empty.

## What an Overlay is doing in a catalog

An [OpenAPI Overlay](https://spec.openapis.org/overlay/latest.html) is a small document of actions, each a JSONPath target plus an `update` to merge or a `remove`, applied on top of an OpenAPI you may not own. I keep a catalog of other people's contracts, so Overlays are how I add to them without forking them: provenance, rate limits, security schemes an export dropped, conversational phrasing for every operation, corrections to what a gateway mangled. Every one of those changes has to survive the provider regenerating their OpenAPI next week, which is the whole reason it is an Overlay and not an edit.

The section exists so that anyone can see those layers, one page per Overlay, with the targets it touches, the purpose of its actions, and the contract it extends. More importantly it exists so nobody mistakes my layers for the provider's.

## Four groups, in the order that matters

| Group | Overlays | Providers | What it means |
|---|--:|--:|---|
| Published by the provider | 147 | 17 | The provider wrote it and serves it: the Overlay pointer in its own APIs.json names a document on its domain. This is what the Kin Score credits as a published overlay |
| Derived from the provider's contracts | 205 | 97 | Built by my pipeline from what the provider publishes. The provider did not publish the file |
| Generated by API Evangelist | 20,720 | 2,211 | Written by my tooling for the provider's APIs, listed by provider because the phrasing overlays alone run to hundreds for some of them |
| Authorship not recorded | 3,939 | 1,576 | Built before the provenance field existed. Read as derived, never as the provider's own |

I want to be careful with the first row, because it is the one that makes a claim about a provider rather than about me. I read every one of the 147. They are all mine. Each is an "API Evangelist enhancements" overlay that extends a contract my pipeline harvested or searched out, and the classifier read the harvested-or-searched marker on that contract as if it described the Overlay sitting on top of it. The provider never published any of them. The label is a defect in my classifier, not a fact about those providers, and it is being corrected. If the page still says 147 when you read this, that is the number to disbelieve. The honest count of providers who publish an Overlay on their own domain, that my pipeline can fetch and verify, is zero.

That is the headline. Not the 25,011. Zero.

## What the other 24,864 are

The generated group is the catalog's working layer, and it is where the [fourteen jobs](https://apievangelist.com/2026/10/06/overlay-1-2-and-the-fourteen-jobs-we-already-use-it-for/) actually run. Most providers carry one Overlay, a small enhancement that adds provenance, a rating source, a base URL resolution, or a note about idempotency and error format to the contract's `info` block. Ninety-five providers carry fifty or more, and one carries 576, because the conversational phrasing work writes one Overlay per API and some providers publish a lot of APIs. Those phrasing overlays, the questions people ask an assistant and the instructions they give an agent for every operation, are the most useful thing in the section and the furthest from anything a provider wrote.

The derived group is smaller and more interesting. These are Overlays my pipeline measured out of a provider's own contract rather than wrote for it. Seven add security: a `securitySchemes` block and the OpenID Connect discovery document a contract referenced but never declared. Six add servers the contract left out. Thirty-three are documentation. The biggest, for Blueshift, carries 81 actions. A derived Overlay is a reading, and the page says so in the first sentence.

The unmarked group is debt. Nearly four thousand Overlays built before the pipeline recorded who wrote what, and the rule for them is the same as for [rulesets](https://apievangelist.com/2026/10/12/ninety-five-companies-publish-their-api-design-rules-and-apis-io-lists-them-first/): an artifact that cannot say who made it is read as derived, and never as the provider's.

## Why zero is worth a post

The Contract Governance facet of the Kin Score gives four points for a published Overlay, because a repeatable, versioned transformation of your own contract is what a spec pipeline looks like from the outside. Nobody earns them. Across 28,834 providers, not one publishes an Overlay the catalog can fetch from their domain. A few, Blueshift and Xoserve among them, have Overlays in their repositories that I built and they could adopt by pointing at them, and that is the path I would suggest to anyone: take the layer the catalog already wrote for you, read it, fix what it got wrong, and serve it from your own domain under your own name. The moment you do, the section moves it to the top, labels it yours, and the points follow.

This matters beyond the score. I argued last week that Overlays and Arazzo are where most of what people are calling context engineering will actually live, as portable documents rather than prompt text hidden in somebody's application. Right now every one of those documents in the catalog was written by the person asking the question, not the person who owns the answer. A provider's own Overlay, saying in plain language what each operation is for and when an agent should call it, would be the first context layer in the catalog that the provider authored. I would like the first row of that page to stop being empty.