Skip to content

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 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.

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 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.