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.
How API Evangelist Uses Overlays
5,550 overlays across 2,299 providers, 17,209 actions, and not one of them removes anything.
OpenAPI Overlay Specification
A way to say something about somebody else's API contract without editing it.
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 |