Device report API
Send readings from anything that can make an HTTPS request: a gateway in a plant room, a controller bridge, a computer, a phone app or a script.
/api/devices/{deviceId}/telemetry/reportEach request reports one moment from one device. Create the device in the console first, with a template whose datastreams use the keys you will send.
Authentication
Put the Device ID in the address and the device's access token in the X-Device-Token header. A wrong ID and a wrong token give the same 401 answer, on purpose.
Body
temperature, pump, ...number | string | boolean | nullRequiredOne field per reading, named by its datastream's key on the device's template. Text up to 512 characters. A key with no datastream is ignored.
evtstring | numberAn id for this report, up to 64 characters. Retry with the same id and a report already received in the last hour is not stored twice. Use it on any network that can time out.
tsintegerWhen the readings were taken, in Unix seconds. Leave it out to use the time the report arrives. Useful for readings a gateway held while offline.
signalnumberSignal strength in dBm, shown beside the device.
rssiis accepted as the same field.uptimenumberSeconds since the device started, shown beside the device.
A report holds at most 64 fields. Any other key is refused with 400.
Example
curl -X POST "https://maxwelltrack.com/api/devices/YOUR_DEVICE_ID/telemetry/report" \
-H "X-Device-Token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"temperature": 4.2, "humidity": 61, "evt": "boiler-1-000124"}'Response
{ "success": true, "data": { "accepted": true, "duplicate": false } }duplicate is true when a report with the same evt was already received, and nothing new was stored.
Limits
- Up to 1,200 reports per hour per device: on average one every 3 seconds. Above that,
429. - A device shows as Reporting while it is heard from at least every 30 seconds. Report more often than that, or expect it to show as not reporting between reports; its readings are stored either way.
- Every value in a report is metered as one reading: a report with three values is three readings.
One token per unit
The access token is a password for that one device. In a product you ship, give each unit its own device and token, so one leaked token never exposes the others.
Something unclear or out of date on this page? Tell support.
