The header
SendX-Api-Version with the version you want, on every request:
The pin
Pinning sets your account’s default, so calls without the header use it: Pin account to a version Both the previous and the new version come back, so you can confirm the move happened.Which to use
Send the header on every request. It costs nothing, it is unambiguous, and it survives your account being pinned by someone else later. Pin as well once you are settled on a version and want calls that omit the header to behave. Pinning does not replace the header. It decides what happens when the header is absent.What a version fixes
A version fixes shapes, not behaviour you can see from outside. Two versions can return the same field with a different set of values, or wrap the same rows differently. Where a value set differs by version, the values page for that resource shows both, and the version selector at the top of these docs decides which reference you are reading.More versions exist than are documented
The API accepts versions this documentation does not cover, and the400 above names them all. Those are there so accounts pinned to them keep working. They are not choices to make.
Build against a documented version. If your account defaults to one that is not documented, send the header rather than working from a reference that does not describe what you will receive.