There are two version prefixes and they mean different things. Neither is a marketing label; each is a commitment about what can change under you.
/v1 is additive only
Fields in /v1 are never removed and never redefined. New fields appear as the dataset grows, which is the only kind of change a stable version makes. The obligation that puts on a client is small and worth stating: ignore fields you do not recognise. Code that fails on an unexpected key will break on an addition that was, by contract, safe.
/v0 is preview, and says so
Endpoints on /v0 carry data whose shape is still settling. Labor is the clearest example: the fields around a measured hour have changed as the measurement improved. Preview endpoints can change with notice on the changelog, which is why the changelog exists and why every entry names the endpoints it touches.
Ninety days, whichever version
No version is retired with less than ninety days of notice, announced on the changelog before anything changes. That is the number to plan around: it is long enough to schedule an upgrade into a normal release cycle, and short enough that we are not carrying a shape nobody uses.
- Pin the prefix you built against; do not follow whatever is newest.
- Ignore unknown fields, so an addition is never a breakage.
- Read the changelog before a release, not after an incident.