The four versions
One artefact at four versions, and the four things a reader can be told about the one they are in.
The switcher on any reference page moves between them. They are four files in
one folder, not four git refs — which is how an API is usually versioned, and
the shape the versions key on a generated section exists for.
| Version | Status | What it is |
|---|---|---|
main | upcoming | 3.x plus a streaming endpoint. May still change |
v3.x | current | The full document, and the one served without a version segment |
v2.x | deprecated | Where shipments became consignments and paging became a cursor |
v1.x | eol | Switched off. Kept only to be read |
That is deliberate. upcoming, current, deprecated and eol are everything
a reader can be told about the version they are in, and every one of them is
drawn by this site's own build.
What differs between them
v1.x is the shape before the rename: shipments, a label and a state,
paged by number. v2.x is where each of those became consignments, a
reference and a status, paged by cursor — so switching between the two on
one endpoint shows a real difference rather than a changed heading.
v3.x adds the parts a reference has to be able to draw at all: several media
types on one response, a oneOf with a discriminator, a callback, a webhook,
three authentication schemes. main is that document plus a streaming endpoint
under a tag of its own, which is what an unreleased line usually is.