Overlays
An overlay is how you say something about somebody else's API contract without editing it. API Evangelist is a second author on 2299 providers' documents, and this is where that stays legible.
These are first-party artifacts
Providers did not write these overlays — API Evangelist did, to annotate their contracts without modifying them. Every one of the 17209 actions is an update; not one is a remove. Nothing this network adds can delete an operation, drop a server, or narrow a schema somebody else published.
Adding Tool-Specific Content
Vendor extensions describe how a tool should treat your API, not what your API is — so keep them in overlays and out of the canonical document.
Batch and Reusable Modifications
The JSONPath target is a query, not an address — write the filter once and let one file do the work of a hundred across a whole fleet.
Brownfield Correction
An overlay is a bug report you can run. Stop forking specs you do not own and stop waiting on a vendor's backlog.
Compliance and Redaction Profiles
A checklist asks an auditor to trust that a human did a thing correctly, under deadline, without a paper trail. An overlay hands them the diff.
Deprecation and Migration Choreography
A deprecation done as scattered manual edits is a one-way door. A deprecation done as an overlay is a diffable, reversible artifact you can preview, schedule, and undo.
Environment Promotion
Environment configuration is not three contracts you keep in sync by discipline and prayer. It is one contract with three projections.
Filtering Multiple Audiences
One parent definition and a stack of small remove overlays, instead of three hand-edited copies that drift apart.
Governance as an Artifact
Spectral tells you that you are non-compliant and stops. An overlay brings the spec into compliance — stop shipping rules that fail specs, ship overlays that fix them.
How API Evangelist Uses Overlays
5,550 overlays across 2,299 providers, 17,209 actions, and not one of them removes anything.
Improving Developer Experience
Enrich a thin, code-generated spec with prose, examples, and fresh dates — without editing a file codegen will overwrite.
MCP and AI-Agent Enrichment
Agent-readiness is not a docs problem and not a rewrite-your-API problem. It is an overlay concern.
Monetization and Plan Tiering
If your plan tiers are hand-maintained documents, you do not have plans — you have three lies decaying at different rates.
OpenAPI Overlay Specification
A way to say something about somebody else's API contract without editing it.
Overlay Tooling
The open-source engines and commercial platforms that implement Overlay today — the specification is stable, the engines interoperate, and you can swap one out without rewriting your overlays.
Public vs. Internal Docs
One base spec, two overlays, two deploys — a clean public portal and a richer internal one, with drift made impossible rather than merely unlikely.
SDK Generation Prep
Push codegen naming, tagging, and typing fixes into an overlay committed next to the SDK build, so the source spec stops describing your generator's mood.
Separation of Concerns
The consumer-side use case overlays were born for — bend somebody else's contract to your world without forking a document you will have to feed forever.
Stripping Internal Endpoints
Almost every internal API leak came down to a human being expected to remember a manual step — overlays let you delete that assumption.
Test Fixtures and Mock Generation
Your marketing examples and your test fixtures are different content with different owners and different lifecycles. Stop making them share one example set.
Translating and Localizing
One overlay per language against one canonical spec, so localization is a rendering step rather than a second source of truth.
Visual Authoring
The people who most need to fix a spec are almost never the people allowed to touch it — a GUI that writes the JSONPath removes the last technical excuse.
Where the actions land
447 distinct JSONPath targets. $.info dominates, which is the right place for a second author to write — metadata beside the document's own metadata, rather than inside the operations a provider defined.
| Target | Actions |
|---|---|
$.info | 8538 |
$ | 1057 |
$.servers | 833 |
$.servers[0] | 275 |
$.components | 216 |
$.tags | 193 |
$.components.securitySchemes | 156 |
$.externalDocs | 143 |
$.components.securitySchemes.bearerAuth | 83 |
$.components.schemas.Error | 50 |
$.components.schemas | 48 |
$.servers[*] | 41 |
$.paths | 37 |
$.info.contact | 33 |
$.components.securitySchemes.ApiKeyAuth | 28 |
$.servers[0].variables.apiRoot | 22 |
$.components.securitySchemes.oauth2 | 21 |
$.paths.*.* | 21 |
$.components.securitySchemes.applicationPassword | 20 |
$.components.securitySchemes.OAuth2 | 20 |
The vocabulary they inject
3051 distinct x- keys across the corpus — the largest coherent extension vocabulary in the catalog, and one that has never been documented in one place. That is an authoring backlog, and it is ours.
| Extension key | Occurrences |
|---|---|
x-apievangelist-provider | 3501 |
x-apievangelist-artifacts | 1623 |
x-apievangelist-enriched | 1330 |
x-apievangelist-source | 1178 |
x-apievangelist-note | 1119 |
x-generated | 1087 |
x-method | 1087 |
x-apievangelist-conventions | 889 |
x-apievangelist-auth | 753 |
x-apievangelist-errors | 750 |
x-apievangelist | 694 |
x-source | 654 |
x-apievangelist-notes | 577 |
x-apievangelist-authentication | 569 |
x-apievangelist-harvested | 564 |
x-apievangelist-lifecycle | 413 |
x-agentic-access | 409 |
x-apievangelist-idempotency | 338 |
x-note | 335 |
x-authentication | 334 |
x-idempotency | 311 |
x-apievangelist-slug | 297 |
x-apievangelist-rating | 297 |
x-apievangelist-category | 251 |