Azzam Bilal Chamdy
In the evolving landscape of API governance and machine-readable contracts, a quiet but profound shift is occurring. For years, the industry has relied on static OpenAPI definitions—monolithic, often cumbersome files that serve as the "source of truth" for developers. However, a new paradigm, the OpenAPI Overlay, is changing how we manage metadata, security, and conversational context.
While the APIs.io catalog now boasts a staggering 25,011 Overlay documents, a recent audit of these files reveals a sobering reality: despite the volume, the number of API providers actually publishing their own Overlays stands at exactly zero. This article explores the mechanics of this discrepancy, the rise of "context engineering," and why the industry is missing a critical opportunity to reclaim control over their own API narratives.
The Core Concept: What is an Overlay?
To understand the current state of the APIs.io catalog, one must first understand what an Overlay is. Unlike a "diff"—which implies a destructive or fragmented change to a codebase—an Overlay is a structural layer. It is a discrete document containing a series of actions, each utilizing a JSONPath target paired with an update or remove operation.
These layers are applied on top of an existing OpenAPI contract that you may not own. For developers and API architects, this is a revolutionary approach. It allows for the injection of critical metadata—such as missing security schemes, refined rate-limiting policies, corrected documentation, or even conversational phrasing for AI agents—without the need to fork the original repository.
Because these changes exist as an independent layer, they survive even when the provider regenerates their base OpenAPI contract. This durability is the primary reason for the rapid growth of the ecosystem; it is a way to harmonize third-party APIs without breaking the link to the original source.
Chronology: From Experimental Tooling to Catalog Reality
The journey toward this current state began with a focus on functional utility. Initially, the goal was simply to bridge the gap between flawed, machine-generated contracts and the requirements of a modern, agent-centric web.
- Phase 1: The Build-Out (Pre-2026): Over thousands of interactions, custom tooling was developed to create "working layers" for various APIs. These early efforts focused on fixing gateways that mangled payloads or adding essential provenance information. During this time, the concept of provenance tracking was not yet standardized, leading to the "unmarked" group of legacy overlays in the current catalog.
- Phase 2: The Standardization (Early 2026): As the OpenAPI Overlay specification matured, the catalog began to formalize its structure. The objective shifted from mere "fixing" to "enhancing," particularly with the rise of Large Language Models (LLMs) and the need for conversational instructions that guide an AI agent through an API’s operations.
- Phase 3: The Audit (October 2026): With the launch of the dedicated Overlays section on APIs.io, a full audit was conducted. It was during this phase that the classification errors were discovered—specifically, the false attribution of 147 overlays to providers who had not actually published them. This led to the realization that while the catalog is growing, the participation from the API provider side remains non-existent.
Supporting Data: Dissecting the 25,011
The current state of the APIs.io catalog can be divided into four distinct groups. The data paints a clear picture of an ecosystem dominated by third-party curation rather than provider-led governance.
Table: The Overlay Ecosystem Breakdown
| Group | Overlays | Providers | Significance |
|---|---|---|---|
| Published by Provider | 0* | 0 | The "Holy Grail" of governance; currently empty. |
| Derived from Contracts | 205 | 97 | Insights extracted directly from existing schemas. |
| Generated by Evangelist | 20,720 | 2,211 | The "working layer" containing AI/Agent instructions. |
| Authorship Unknown | 3,939 | 1,576 | Legacy debt from pre-provenance record-keeping. |
*Note: While the catalog initially suggested 147 provider-published overlays, subsequent verification confirmed these were incorrectly classified. They were, in fact, enhancements written by external tooling.
Analyzing the "Derived" and "Generated" Layers
The Generated group is the engine room of the catalog. These 20,720 overlays represent the "fourteen jobs" that define modern API interaction, ranging from base URL resolution to complex instructions for AI agents. The most significant of these are the "phrasing overlays," which provide the specific questions and instructions an agent needs to execute an operation successfully.
The Derived group is equally fascinating. These overlays are essentially "readings" of existing contracts. By analyzing a provider’s own schema, the pipeline identifies missing security discovery documents or omitted server definitions and reconstructs them as an overlay. It is a testament to how much information is left implicit rather than explicit in modern API design.
Official Responses and the "Zero" Reality
The most striking revelation from the recent audit is the correction of the "Published by Provider" metric. For a brief period, the dashboard displayed 147 overlays as being "published" by providers. This was a technical failure of the classifier, which saw an external enhancement sitting on top of a harvested contract and mistakenly assigned ownership to the provider.
When the audit team corrected the logic, the number dropped to zero. This is a critical inflection point for the industry. While companies like Blueshift and Xoserve have seen overlays created for them by the community, not one of these organizations has formally adopted the layer, vetted it, and served it from their own domain.
The industry is currently in a state where the people using the APIs are the only ones writing the "instruction manuals" for them. Providers are currently neglecting their own API’s interface for the AI era.
Implications: The Future of Context Engineering
Why does this matter? It matters because of the looming shift toward "Context Engineering."
The Death of Hidden Prompting
Currently, developers are forced to bury instructions and context within their own applications—hidden in hardcoded prompts or proprietary middleware. This is inefficient, fragile, and siloed. If an API’s functionality changes, the application breaks.
By contrast, the Overlay is a portable document. It is a standard-compliant way to say: "Here is what this operation is for, and here is how an agent should handle the authentication." When a provider publishes this layer themselves, they are essentially providing a "Context API"—a machine-readable manual that tells the world how to interact with their services.
The Kin Score and Governance
The Contract Governance facet of the Kin Score currently reserves four points for a published overlay. These points are meant to reward "repeatable, versioned transformation." As it stands, nobody is earning these points. This is a missed opportunity for enterprises to signal maturity.
A Call to Action
The path forward is clear. The catalog already contains thousands of overlays that are waiting to be adopted. Providers should not feel the need to build these layers from scratch. Instead, the suggested workflow is:
- Retrieve: Identify the overlay already generated for your API in the APIs.io catalog.
- Audit: Review the actions and instructions for accuracy.
- Publish: Host the finalized version on your own domain.
The moment a provider takes ownership of their overlay, they transform from a passive participant into an active architect of the machine-readable web. The goal is to move the first row of the APIs.io statistics table from zero to a growing, vibrant number.
In an era where AI agents will soon be the primary consumers of our APIs, the ability to define your own context is not just a best practice—it is the next frontier of competitive advantage. If the provider does not define the context, the user will; and as the current data shows, the user is already hard at work.
Ammar Sabilarrohman
Reynand Wu
