Versioning
The version lives in the path: /api/v2, /api/v3. On path-versioned routes the X-API-Version
header isn’t needed and is ignored — it never blocks the call, the path always decides. The
exception is v1 (the app’s internal routes, reachable by a key for compatibility): there’s no
versioned path there, so the version is decided by the X-API-Version header, which only accepts
v1 (the default if you omit it) — any other value is still rejected with 400.
v1 vs v2 vs v3
Section titled “v1 vs v2 vs v3”| v1 | v2 | v3 (beta) | |
|---|---|---|---|
| Path | the app’s internal routes (/api/…) |
/api/v2/… |
/api/v3/… |
| Resources | everything reachable by a key (devices, history, commands…) | devices, positions, history, events (read-only) | the same ones as v2 (same code, under /api/v3) plus areas/geofences (read and write) — v2 stays unchanged alongside it, v3 alone is enough |
| Response shape | raw database shapes, not standardized | stable envelope { data, meta } / { error } |
same envelope as v2, with details[] on validation errors |
| Version header | X-API-Version (only v1) |
from the path, ignored if sent | from the path, ignored if sent; every response also carries X-API-Status: beta |
| Status | deprecated for API keys | active, the recommended surface | beta: may still change, always announced first |
| Compatibility | stays reachable for compatibility | additive: resources/fields are added, never removed | additive, but not yet frozen — see API v3 overview |
v1 — the routes used by the app — stays reachable to API keys for compatibility, but it’s
deprecated: responses carry Deprecation: true and a shutdown date (Sunset: 2027-03-08). Every
new version gets at least 12 months of overlap with the previous one: no public route
disappears overnight.
/api/v2 and /api/v3 responses, instead, carry neither Deprecation nor Sunset: both are
active surfaces (one stable, one beta), not on their way out.
v2 contract compatibility
Section titled “v2 contract compatibility”The v2 contract is stable: no breaking change within it.
- Allowed: adding new resources, adding new fields to existing DTOs.
- Not allowed: removing or renaming a public field, changing the meaning of an
error.code— that kind of change requires a v3, not a v2 update.
If you’re integrating today, you can rely on a call that works continuing to work: fields can only be added, never disappear or change shape.
v3 is beta
Section titled “v3 is beta”v3 doesn’t replace v2, it sits alongside it: it includes all of v2 (devices, positions, history,
commands, events, same code) under /api/v3, plus areas (geofences), which no earlier version
exposed — you can integrate with v3 alone. While it’s beta its details may still be refined
(always announced before changing) — see API v3: overview and
From v2 to v3 for the full comparison with v2.