Overview
Device API v2 is available for controllers on firmware 2.5.46 or later. Instead of asking the controller for each piece of data, the controller pushes a signed binary state frame to the cloud whenever anything changes and on a regular heartbeat. The cloud verifies the frame, merges it into a state document and serves it from cache.
/api-gateway/v2/iot-shadow/device/{deviceId}/…Authentication is the same bearer token and the same ownership check as v1.
Endpoints
Section titled “Endpoints”| Endpoint | Purpose |
|---|---|
GET …/state |
The merged state document, served instantly |
POST …/state/refresh |
Ask the controller for a fresh full frame and return the merged result |
GET …/envelope-key |
The controller’s per-device key, for LAN access |
POST …/query/{name} |
A signed query answered directly by the controller |
POST …/action/{name} |
A signed action executed by the controller |
GET …/events |
The controller’s audit event log |
POST …/events/rewind |
Ask the controller to re-upload events |
Why use v2
Section titled “Why use v2”- Instant reads.
GET …/statenever waits for the controller. Telemetry is at most 30 seconds old while the controller is online, and critical changes arrive within about 300 ms. - One document. Telemetry, configuration and equipment slots come back in one response with consistent field names.
- Authenticated end to end. Every frame is signed with a key unique to the controller; see Command Protocol v2.
- Audit trail. Every switch, schedule change, command, reboot and fault is logged on the controller and uploaded.
- Same protocol on the LAN. The frames you see here are the frames a controller exchanges on the local network.
Capability and freshness
Section titled “Capability and freshness”A controller counts as v2-capable while the cloud has received a verified frame from it in the last 10 minutes. The heartbeat is 90 seconds, so a healthy controller never drops out.
| Situation | Behaviour |
|---|---|
| Verified frame in the last 10 minutes | All endpoints work |
| No frame in the last 10 minutes, state document exists | GET …/state returns it with v2_capable: false; envelope-key and events still work; refresh, query, action and rewind return 409 |
| Controller never sent a frame | GET …/state returns 404; envelope-key and events still work; refresh, query, action and rewind return 409 |
On 409, fall back to Device API v1: the controller is offline, on older firmware, or not yet provisioned for v2.
Status codes
Section titled “Status codes”| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Invalid name, JSON, hex or field value. message explains |
| 401 | Missing or invalid bearer token |
| 403 | The user does not own this controller |
| 404 | No state document yet (GET …/state only) |
| 409 | Controller not v2-capable right now, see above |
| 429 | Controller cooling down after timeouts, see Rate limits |
| 503 | v2 is not enabled on this server |
| 504 | The controller did not answer a refresh or query within 8 seconds |
| 500 | Unexpected failure, including the controller link being down |
Pacing
Section titled “Pacing”Refresh, query, action and rewind go through the same per-controller pipeline as v1 writes: one at a time, at least 500 ms apart, writes at least 2 seconds apart. The server waits rather than rejecting, so a burst of calls simply takes longer. Repeated controller timeouts trigger the same cool-down and 429 as v1. GET …/state and GET …/envelope-key never enter the pipeline.