API Reference

Subscribe Topics

Overview

The subscribe topics, allow a device to listen to events and changes recorded by the server. Most objects map (almost) exactly to HTTP based APIs, as such the payload for each topic is the same as the payload received from a matching HTTP API endpoints.

The table below outlines the trackable objects, their topic for subscription and the matching HTTP API containing a detailed description of the payload received.

❗️

Note the special "Sync Topics" section at the end

Subscriptions topics

Command

Topic: v1/device/{DEVICE_ID}/command

Receive notification of the next pending command from the server. The data received matches the return data of the Get Command API

Command with children

Topic: v1/device/{DEVICE_ID}/command/children

Receive notification of the next pending command for each of the device's children. The data received matches the return data of the Get Commands with Children API.

Configuration

Topic: v1/device/{DEVICE_ID}/config

Receive notification of configuration updates from the server. The data received matches the return data of the Get Config API

Licenses

Topic: v1/device/{DEVICE_ID}/license

Receive notification on any licenses requiring device actions. The data received is an array of licenses, matching the return data of the Get Licenses API

Space

Topic: v1/device/{DEVICE_ID}/space_info

Receive notification of changed to the space containing the device. The data received matches the return data of the Get Space Info API

Incidents

Topic: v1/device/{DEVICE_ID}/incidents

Receive notification of new incidents created. The data received is an array of incidents, matching the return data of the Get Incidents API

New firmware available

Topic: v1/device/{DEVICE_ID}/firmware

Receive notification when a new firmware file has been uploaded by the manufacturer who's version is higher than the version currently reported by the device.

{  
  latest_fw_version: '1.0.5',  
  latest_fw_file_id: '9266cb1b-fc23-4e76-b622-cc1fd4389549'  
}

Unsupported APIs

Some objects cannot be subscribed to, requiring a call to the HTTP API to retrieve the data:


Sync Topics

If a device is temporarily not subscribed to topics such as "Commands", it might miss pending requests. The following feature allows the device to ask the server to resend all pending changes.

It is strongly recommended for MQTT devices to add the following additional step after the device has been power-cycled, to request the server to resend all the pending requests.

  1. Subscribe to all relevant topics
  2. Send any message to the topic: v1/device/{DEVICE_ID}/get