How to use our REST API to send telemetry or metadata into DevicePilot
DevicePilot has a simple REST API for POSTing device data. You post a JSON body of properties, to
"label": "My sensor",
We use token authentication so you'll need to supply two headers to the POST:
"Authorization: Token xxxxyyyyzzzz"
Your API key can be found in the Tokens page.
Your device objects may contain any properties you like, so long as they do not begin with $. The $ symbol is reserved for DevicePilot system properties, some of which you can pass in to describe your data. These include:
- $id Your id for this device. This field is mandatory, DevicePilot will use this to uniquely identify your device
- $ts Timestamp of the device state. This field is optional, if you don't pass this in DevicePilot will automatically generate a value using the time it received the message. The timestamp can be supplied in epoch seconds, epoch milliseconds, or ISO 8601 time format - we'll work it out for you. We will assume the epoch times are in UTC, and the ISO 8610 can describe its own time zone. See How does time work in DevicePilot for more details.
If you'd like to send us some JSON you already have, that uses different field names, you can tell us about that in the URL. The following query parameters are supported:
- idField is the name of the unique device id
- timeField is the name of the field containing time
DevicePilot doesn't differentiate between creating and updating devices - just POST the data and we'll "create" devices as new $ids are seen. Also, you don't need to send all properties everytime - you can if you like but the most efficient way is to send us only what's changed.
DevicePilot supports POSTing an array of JSON objects to update multiple devices at once. You can most a maximum of 500 records or 1Mb of data, whichever is smaller. Unless you have dozens and dozens of properties, you'll likely hit the 500 record limit first.
Batch POSTing is recommended as more efficient than individual POSTs.
The fine print
- Properties cannot start with $ or #
- Only strings, numbers or booleans are allowed
- Flat objects only - no arrays or objects
- Types must be consistent
- $ts cannot be in the future
- $id must only contain a-Z, 0-9, or any of _ , : -
- null is supported - set properties to null to "unset" them (don't use "")
- The first time a property is set it can't be null because we can't tell the type
HTTP Status Codes
DevicePilot is eventually consistent, so we return 202 on Accepting the POST.
We return 400 on bad arguments i.e. if any of the rules above not met. The body will have a detailed explanation of the error, so this should help you understand what went wrong.
Other codes returned:
- 401 (Unauthorized) - Something was wrong with the Authorization header, either it was missing, malformed or the API key was not recognised.
- 403 (Forbidden) - This user does not have permission to POST data
- 413 (Payload Too Large) - The body is too big: see Batch Updating above