Overview
Subscribe topics let a Device listen for state changes pushed by the server. Each topic mirrors the equivalent HTTPS API, so the payload on any topic matches the response of the matching HTTPS endpoint.
The sections below list every supported subscribe topic and the HTTPS API that defines its payload schema.
Don't miss the Sync topics section at the end — it covers how to recover after a reconnect.
Subscription topics
Command
Topic: v1/device/{DEVICE_ID}/command
Pushes the next pending Command. Payload matches the Get Command API response.
Command with children
Topic: v1/device/{DEVICE_ID}/command/children
Pushes the next pending Command for each of the Device's child Devices. Payload matches the Get Commands with Children API response.
Configuration
Topic: v1/device/{DEVICE_ID}/config
Pushes Configuration updates. Payload matches the Get Config API response.
Licenses
Topic: v1/device/{DEVICE_ID}/license
Pushes Licenses that require Device action (add, update, or remove). Payload is an array, matching the Get Licenses API response.
Space
Topic: v1/device/{DEVICE_ID}/space_info
Pushes changes to the Device's Space configuration. Payload matches the Get Space Info API response.
Incidents
Topic: v1/device/{DEVICE_ID}/incidents
Pushes newly created Incidents. Payload is an array, matching the Get Incidents API response.
New firmware available
Topic: v1/device/{DEVICE_ID}/firmware
Pushes a notification whenever the manufacturer uploads a Firmware file with a version higher than the Device's current reported version.
{
latest_fw_version: '1.0.5',
latest_fw_file_id: '9266cb1b-fc23-4e76-b622-cc1fd4389549'
}APIs without an MQTT topic
Some endpoints have no MQTT subscription and must be called over HTTPS:
- Device info — Get Device Info.
Sync topics
If a Device is offline or unsubscribed when the server pushes an update (Command, License, etc.), it will miss that message. To recover, the Device can ask the server to re-publish all currently pending state.
After every reconnect or power cycle, an MQTT Device should:
- Subscribe to every relevant topic.
- Publish any message to
v1/device/{DEVICE_ID}/get.
The server then re-publishes the current state on the matching topics.