821 OpenAI spec changes, 3 that can break a client: the honest negative

openai · report · 2026-08-01 · source: change database

Between two published snapshots of the OpenAI OpenAPI spec — 5162af98d314 (2026-05-13) and 117ce5680e42 (2026-07-31) — a structural diff produced 821 change records. Exactly 3 of them can break an existing client. This is the write-up of a corridor where almost nothing broke, and why that finding is worth publishing anyway.

The shape of the corridor

Every one of the 821 records carries the engine's classification, and the distribution tells the story:

- 515 response properties added - 141 enum values added - 130 request properties added - 20 paths added and 10 operations added - 2 optional parameters added - 3 request media types removed — the only client-breaking kind in the corridor

818 additive records plus 3 breaking ones account for all 821. Zero endpoint paths were removed: every route present in the May snapshot is still present in the July one. Over this eleven-week window, OpenAI's wire contract grew; it did not shrink.

The 3 that matter

All 3 breaking records are the same kind of change, at the transport layer rather than the semantic layer:

- POST /responses/compact — application/x-www-form-urlencoded request encoding withdrawn. Only JSON requests are accepted on this route now. - POST /responses/input_tokens — application/x-www-form-urlencoded request encoding withdrawn. Only JSON requests are accepted on this route now. - POST /skills/{skill_id} — application/x-www-form-urlencoded request encoding withdrawn. Only JSON requests are accepted on this route now.

If your integration posts JSON — which is what every official SDK does — none of these touch you. If you hand-roll form-encoded requests against these routes, your next call fails. Each record entered the change database with a fixability verdict and migration guidance, and npx mendapi scan reports file and line if your repo is exposed.

The recent-baseline corridor: 13 records, 0 breaking

A second, shorter corridor against a more recent baseline (bcb644949593 to the same July head) produced 13 records, all additive, zero breaking. Two corridors, one conclusion, independently derived.

Re-verified, record for record

Both corridors were re-run from the cached snapshots after ingestion: 821 of 821 records reproduced on the long corridor and 13 of 13 on the short one, with zero regressions, zero new breaking records, and zero unexplained differences. Both pairs are marked stable in the archived drift report. That recheck guards the numbers on this page against silent drift of the tooling; it is a statement about these two snapshot pairs, not a forward guarantee about future OpenAI releases.

Why publish a corridor where nothing much broke

Because "you are fine" is only worth something when it is measured. A tool that can only find problems has an incentive to inflate them; the alert-fatigue failure mode starts exactly there. The value of this corridor is the ratio itself: 821 records screened so that 3 genuine breaks surface with file-and-line impact — and the 818 that do not break anything stay out of your alerts. Other corridors in this series look very different: 47 Stripe spec pairs head-to-head found real divergences worth adjudicating, three providers across 49 pairs closed every gap by name, and Cloudflare's 136 raw removals were mostly spec refactoring noise. This one is the quiet corridor. We do not extrapolate any of these ratios to other providers or other windows — that variance is the argument for measuring per corridor instead of trusting a vibe.

Check your own repo

All 3 client-breaking records from this corridor are in the change database behind this site. To find out whether your repo is exposed — file and line number, no code leaving your machine:

npx mendapi scan --repo .

The full OpenAI timeline lives on the OpenAI breaking-change guide. If you are here because you run a drop-in replacement backend, the OpenAI drop-in replacement guide covers what a compatible base URL does and does not shield you from. Methodology comparison is on the when to use mendapi page.

Detected and tracked by mendapi — Dependabot for every API you depend on. Scans run locally; your code never leaves your machine.