136 raw removals, 17 real ones: what a spec diff over-reports

Originally published at mendapi.com . Between two published snapshots of the Cloudflare OpenAPI schema — 7abe88500e55 (2026-03-31) → c92b9b0fde23 (2026-07-27) — a raw structural diff produced 6,354 change records. 136 of them were endpoint path removals, the scariest kind a diff can report: the route your code calls is simply gone from the spec. Except 119 of those 136 were not gone at all. This is the accounting of how we know, per record, with machine evidence. The trap in a raw diff A path removal in a spec diff means one thing: the string key disappeared from the paths object. It does not mean the runtime URL stopped working. Specs get refactored — concrete routes collapse into templated ones, path parameters get renamed, methods get merged — and every one of those refactors shows up as a "removal" if you only look at one side of the diff. An alerting tool that pages you 136 times for this corridor is training you to ignore it. The whole job of the curation layer is to keep that from happening without silently dropping a real break. The ledger: 17 + 119 = 136 Every one of the 136 raw removals has an adjudicated destination. 17 were kept as genuinely client-breaking: the runtime URL or method really disappeared, with no surviving successor. The other 119 were excluded, each with machine evidence from the two spec snapshots that the surface actually survives: Template consolidation — 107 records. Concrete Workers AI model routes like /ai/run/@cf/baai/bge-m3 collapsed into the pre-existing generic /ai/run/{model_name} route. The runtime URL a client sends never changed; the spec just stopped enumerating each model. The evidence rule requires the templated route to exist in both snapshots and to swallow the removed path with a literal-anchored match, so a template that is merely a shape prefix of a genuinely removed endpoint does not count. Parameter rename, runtime-identical — 11 records. Path parameters renamed ( {postfix_id} to {investigate_id} and friends). Afte