Versioning

The version is in the path

Every endpoint lives under /v1. While it stays there, we will not make a change that breaks a client written against it.

What may change without warning

Additive things, which a correctly written client ignores:

• New fields on existing responses. Do not use a parser that rejects unknown fields — treat anything you do not recognise as ignorable.
• New endpoints, new query parameters, new optional filters.
• New enum values. This is the one that catches people: a status you have never seen can appear because we added a state. Handle an unrecognised enum as "something else" rather than crashing or, worse, silently mapping it to a state it is not.

What will not change under you

• An existing field will not be removed, renamed, or change type.
• An endpoint will not disappear or change what it accepts.
• An enum value we have shipped will not change meaning.

If we ever need to break one of these, it goes in a /v2 and /v1 keeps working while we tell you how long for. We do not have a deprecation policy to point at yet — when there is something to deprecate, it will be announced in the changelog before it happens, not after.

Read-only, for now

This release exposes reads only. Every operation is a GET, and that is enforced by a test over the generated spec rather than by anyone remembering — adding a write endpoint fails the build until it is a deliberate decision.

So today you can build reporting, dashboards, alerting and sync-into-our-system integrations. You cannot create a shipment or update an inquiry; those still happen in the app.

Writes are the obvious next step, and they raise questions reads do not — idempotency, validation feedback, partial updates. When they arrive they will be new endpoints alongside these, not changes to them.

Keeping up

• /openapi.json is generated from the API's own definitions on every deploy, so it always describes what is running. If you generate a client, regenerate it from this rather than pinning a copy.
• /changelog.md is the plain-text changelog, served from the API itself.
• The changelog page is the same content, rendered.

There is no version number to poll and no Sunset header to watch. The spec is the contract, and the changelog is the narration.