An OpenAPI spec reads like a contract. It is versioned, it is machine-readable, it generates your
client. It is also a file the vendor edits, and nothing in it records what it said last week.
I have been diffing the published specs of OpenAI, Anthropic and Groq and keeping every key that
appears: 2,802 operations, parameters, enum variants and beta markers. Of those, 215 are no
longer there.
157 parameters
29 enum variants
27 whole operations
2 beta markers
The removals are not evenly aged. Sorted by how long each one was in the file:
76 over a year
87 under a year
17 under 30 days
33 first seen and last seen on the SAME DAY
2 excluded — a defect in my own collection, see the notes
That last line is the one I did not expect.
Fourteen of them landed on a single afternoon
On 2025-03-22, OpenAI's spec gained four operations for fine-tuning checkpoint permissions:
POST /fine_tuning/checkpoints/{permission_id}/permissions
GET /fine_tuning/checkpoints/{permission_id}/permissions
DELETE /fine_tuning/checkpoints/{permission_id}/permissions
DELETE /fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions
Read the path parameters. Three of them key the collection on {permission_id} — the id of a
thing inside the collection you are listing. The fourth keys the same collection on the
checkpoint. They cannot both be right, and a GET .../{permission_id}/permissions that returns a
list of permissions is a path that was never going to ship in that shape.
The next capture did not have any of them. Fourteen keys — four operations and their ten
parameters — in and out, same date.
And some land on endpoints you actually call
POST /chat/completions carried a parameter called instance_id on 2024-02-09 and on no other
day I have.
POST /responses listed computer-preview as a tools[] variant on 2025-03-11 and not
afterwards.
Anthropic's POST /v1/messages carried user_profile_id from 2026-04-16 to 2026-06-22 — 67
days, long enough that a client generated in May has a field for it. Six of Anthropic's
/v1/environments operations carried a sessionKey parameter on 2026-04-08 and lost it on
2026-04-09. I do not know what any of these were for, and I am not going to guess; what I can say
is that they were in the published document and then were not.
What this does and does not mean
It does not mean the API changed. This is the part I had to be careful about, and the clearest
example is Anthropic's tool_choice.
On 2024-10-03 three enum variants — auto, any, tool — stop appearing. tool_choice: auto
obviously still works. What happened is that the schema moved those values behind a $ref, and
the shape my reader looks for stopped matching. The parameter tool_choice is still in the file
and still marked present; only the three variant keys went to zero.
So "removed from the spec" means the key is no longer where it was in the document. Sometimes
that is a deprecation. Sometimes it is a refactor of the YAML. The 27 removed operations are the
subset I would trust furthest — a path disappearing is hard to do by accident — and even there,
OpenAI's six Assistants file endpoints going on 2024-04-15 is the documented v2 migration, not a
surprise.
What it does mean is that the file is not a record of itself. If you want to know when
user_profile_id appeared, the current spec cannot tell you, and neither can the changelog —
there was no entry for it.
What I would actually do about it
Pin the spec file, not the URL. Vendor it into your repo with a hash and diff it on a
schedule. Every one of the findings above is a git diff someone could have had for free; the
only reason I have them is that nobody else kept the old copy.
Treat a generated client as a snapshot with a date on it. A client generated between April and
June of 2026 has an user_profile_id field that no longer exists upstream. Nothing failed, and
nothing told you.
Watch for same-day keys before you build on one. A capability that appears in the spec and
nowhere in the changelog, docs or release notes is a capability that may not survive the week.
Fourteen of OpenAI's did not survive the day.
Notes on the numbers
Three vendors only — OpenAI (1,605 keys), Anthropic (1,069) and Groq (128). They are the ones
publishing a machine-readable spec at a stable URL; most of the vendors I track do not, which is
why the comparison stops at three.
first_seen is a floor, not an introduction date, for 153 of the keys: 90 OpenAI, 38 Groq and
25 Anthropic were already in the file on the first capture I have. Everything in this post keys
off removals, where the date is observed rather than inferred — but a lifespan that starts at a
floor is a lower bound.
Two rows have a last_seen earlier than their first_seen (an OpenAI uploads parameter and a
Groq stream_options). That is a defect in my own collection, not a vendor doing something
strange, and both are excluded from the 33.
The removed keys, per vendor, with the dates:
aichangewatch.com/api-features
Top comments (0)