From v2 to v3

API in beta

v3 is beta — see Overview for what may still change. This page isn’t an “upgrade your client” guide: it explains what’s new, and just as importantly, what you don’t need to touch.

In short

You don’t need to migrate anything. v3 doesn’t replace v2, both stay active: no v2 endpoint changes shape, no field disappears, no key stops working. If you integrate devices, positions, history and events with /api/v2 today, you can keep doing exactly that. Or, if you’d rather, you can integrate with only /api/v3 from now on: it includes everything in /api/v2 (same code, same responses) plus areas — it’s not required, just an extra option.

What v3 adds

Two things, compared to v2:

1. All of v2, mounted under /api/v3 instead of /api/v2: devices, positions, history, commands, events — same code, same scopes, same responses. Anyone who wants to can integrate with just v3 instead of separate v2 + v3 calls.
2. Areas (geofences), a resource v2 never exposed: create them, read them, update them, delete them, check whether a point is inside one, read their entry/exit events — with an external_id code to sync them from your own system with no duplicates and a dwell_seconds minimum dwell time before notifying entry. Until now the only way to manage areas was the app. See the full reference in Areas.

	v2	v3 (beta)
Resources	devices, positions, history, events (read-only)	the same ones as v2, identical, plus areas/geofences (read and write)
Permissions (scopes)	read_devices, read_locations, read_history, read_history_summary, read_events, send_commands	all of v2’s, plus read_areas, write_areas
Base URL	/api/v2	/api/v3
Status	stable	beta (the parts inherited from v2 share the same stable contract; see Overview)

The two base URLs coexist: the same key, with the right scope, can read /api/v2/devices and write /api/v3/areas in the same integration — or use only /api/v3 for everything.

What stays identical

• Authentication: X-API-Key header, same key lifecycle — see Authentication.
• Response envelope: { data, meta } / { error: { code, message } } — v3 only adds details[] on validation errors.
• Rate limit: 120/minute and 1000/hour per key, 120/minute per IP — shared between v2 and v3, not doubled per version.
• Scope: always the key owner’s scope; another customer’s resources are always 404, never 403.
• General errors (API_KEY_INVALID, API_KEY_REVOKED, API_KEY_OWNER_INACTIVE, API_KEY_IP_BLOCKED, always 403) — see Versioning.

What’s different, only on v3

• X-API-Status: beta header on every response.
• Idempotency-Key on POST /api/v3/areas — v2 has no equivalent.
• Its own machine-readable documentation: /api/v3/openapi.json and /api/v3/docs.

If you only integrate v2 today

There’s nothing to do. If you’ll need to read or write areas via the API in the future (say, syncing geofences with an external system, or generating them from your own process), you have two options: add the read_areas/write_areas scope to your existing key — or create a dedicated one — and call /api/v3/areas alongside /api/v2, without touching the integration already in production; or move to /api/v3 entirely (same behavior for devices and events, plus areas) and stop using /api/v2. Neither is required.