Why we version the API and not the SDK

Pinning the wire format instead of the client library means an upgrade is your decision, not ours.

Version numbers have to live somewhere, and where they live decides who absorbs the pain of change. Put them on the SDK and every library release is a negotiation. Put them on the API and the contract holds still while everything around it improves.

The API carries the version because the API is the contract. A v1 endpoint keeps its shape until the major version changes, and the SDK is free to improve underneath it. When we flipped this around in an early prototype, every SDK release became a compatibility question, and every compatibility question became a support ticket.

The practical rule is simple. If a change would break a request that worked yesterday, it waits for the next major version and gets a line in the changelog with a removal date. If it only adds, it ships when it is ready.

That is why the header rename in v2.3.0 was announced months before v3 removes the old header. Both are accepted until then, and requests that still use the old one get a Deprecation header carrying the date. Nobody should learn about a breaking change from a stack trace.