The Sensorist® REST API is free of charge and can be used by anyone.
You can use the API for retrieving details about and measurement data from the Sensorist® environment sensors. We hope you'll build interesting things from it.
You must respect the
cache-control header we return with all responses to avoid sending unnecessary requests. Please only re-issue a request if the last reply is outdated accordingly.
We continuously monitor the API and strive to keep the (average) response time within 100-300 milliseconds.
The API is always evolving. So you can expect functionality to be added or even changed without prior notice.
TLS only and HTTP basic authentication is required.
With every API request you must send the email address as username and the password from your Sensorist® account.
By default you can only access resources, such as measurements, that are associated with the account credentials provided.
You may impersonate another user by sending the parameter
impersonate with any method call. If set to a valid user identifier, and provided you have the required privileges, this will make the API execute on the specified user's behalf.
The API uses JSON as exchange format and content is gzip compressed.
curl -u firstname.lastname@example.org:password https://api.sensorist.com/v1/users
3. Data model
The diagramme above shows the fundamentals of our data model. It might help you better understand the resources involved when using the API.
Basically a user owns one or more gateways with multiple sensors attached. The measuring capabilities of a sensor we call data sources. Examples of data sources are temperature, humidity and battery level. The measurement values then refer to a particular data source.
All date and time values are Coordinated Universal Time (UTC) and ISO 8601 formatted.
4. GET methods
4.1 GET /users
Get user and account details. Method returns an user object corresponding to the authorized user.
The optional parameter
list provides an array of all users in your hierarchy.
curl -u email@example.com:password https://api.sensorist.com/v1/users
4.2 GET /gateways
Get device inventory. Method returns an array of gateways. Each gateway has a child device array of sensors, and each sensor an array of data sources.
The result may optionally be filtered by setting parameter
serials to a comma separated list of gateway serial numbers and by setting
from to a date, to include only the gateways added to the account after this date.
By default only master gateways are returned. To include slaves set parameter
curl -u firstname.lastname@example.org:password https://api.sensorist.com/v1/gateways
4.3 GET /measurements
Get measurement values. Method requires two parameters
type and returns an array of measurements.
data_sources must be a comma separated list of the id's of the data sources to fetch measurements for. Note that you can only retrieve measurements for one gateway at a time, so the list of data sources must all belong to the same gateway.
type must be one of either
latest, for the latest measurements,
min_max for minimum/maximum values,
range for grouped measurements or
raw for retrieving the unfiltered data. Each of these are described in more details below.
to are dates specificing the period of interest. If not provided or invalid, the period defaults to -1 week.
latest the most recent measurements. The period is ignored.
min_max minimum and maximum values in the period and their respective dates.
range are grouped measurements with average, minimum and maximum values. By default the grouping interval is automatically determined from the period length.
You may set parameter
ticks to the approximate number of measurements you would like returned, this is useful for charting, or you can set
interval to specify the grouping in minutes.
raw measurements for export or synchronization.
These can alternatively be queried by sequence number using
seq_from and or
seq_to. The sequence number is an sequentially incrementing (but not necessarily unique) integer generated server side as measurements are persisted.
A maximum of 5.000
raw measurements are returned. You can use the
next attribute as
offset parameter in subsequent requests to advance the result set.
The returned measurement objects each has a
type attribute with value
1 for regular measurements,
5 if triggered by sensor button push,
10 for grouped measurements,
20 indicates a blank measurement (range gap) and
30 means interpolated.
Sample request (latest)
curl -u email@example.com:password 'https://api.sensorist.com/v1/measurements?data_sources=1,2&type=latest'
Sample request (raw from date)
curl -u firstname.lastname@example.org:password 'https://api.sensorist.com/v1/measurements?data_sources=1,2&type=raw&from=2018-04-25T09:00:00Z'
4.4 GET /alarms
Get the data source alarms set by the user and their current state. Method takes no parameters and returns an array of alarms and most recent logs.
curl -u email@example.com:password https://api.sensorist.com/v1/alarms
4.5 GET /alarms/history
Get the alarm log history. Method returns an array of alarm logs.
The result may optionally be filtered by parameters
alarms set to a comma separated list of alarm id's and by dates
to specificing the period of interest.
By default the history is returned chronological with separate entries for
out of the alarm. To have them returned pairwise instead set parameter
curl -u firstname.lastname@example.org:password https://api.sensorist.com/v1/alarms/history
4.6 GET /callbacks
Get list of registered callbacks. Method takes no parameters and returns an array of callbacks.
curl -u email@example.com:password https://api.sensorist.com/v1/callbacks
4.7 GET /workflows/<id>
Get workflow with
id. Method returns the workflow.
Workflows are proxy constructs that represents and manages longer-term running processes. If the result of an API operation is not initially known, a workflow might be returned instead, encapsulating the process and eventually the result.
curl -u firstname.lastname@example.org:password https://api.sensorist.com/v1/workflows/5
5. POST methods
5.1 POST /users
Create a new user account. Method requires parameters
lname. Method returns the created user.
email_confirmed may be set to
true if the email address has been pre-confirmed, provided you have the necessary privileges.
curl -u email@example.com:password -d 'firstname.lastname@example.org' -d 'password=12345678' -d 'fname=my' -d 'lname=name' https://api.sensorist.com/v1/users
5.2 POST /gateways
Associate gateway with account. Method requires parameter
serial. The serial of the gateway to associate with the account. You may optionally specify a gateway
name. Method returns the associated gateway.
curl -u email@example.com:password -d 'serial=00000000' -d 'name=Home' https://api.sensorist.com/v1/gateways
5.3 POST /gateways/<id>
Update gateway with
id. Method accepts parameter
name to update the gateway display name. Method returns the updated gateway.
curl -u firstname.lastname@example.org:password -d 'name=Office' https://api.sensorist.com/v1/gateways/5
5.4 POST /gateways/<id>/commands
Send command to gateway with
id. Method requires parameter
command with the value of either
reboot to reboot the gateway or
pairing_start to initiate remote pairing.
Method returns a workflow managing the command execution.
curl -u email@example.com:password -d 'command=reboot' https://api.sensorist.com/v1/gateways/5/commands
5.5 POST /sensors/<id>
Update sensor with
id. Method accepts parameters
interval to set the sensor sampling interval in seconds (requires special privileges) and
name to update the sensor display name.
Method returns the updated sensor and possibly a workflow managing the interval change and its network propagation.
curl -u firstname.lastname@example.org:password -d 'interval=900' https://api.sensorist.com/v1/sensors/17
5.6 POST /alarms
Create a new alarm. Method requires parameters
data_source, the id of the data source to monitor,
value the alarm threshold value and
direction set to
You may optionally specifiy a
delay in minutes. E.g. 60 to trigger the alarm only after one hour of measurements continuously exceeding the threshold.
Method returns the created alarm.
curl -u email@example.com:password -d 'data_source=1' -d 'value=-5' -d 'direction=below' https://api.sensorist.com/v1/alarms
5.7 POST /callbacks
Register a callback URL. Receive HTTP/S notifications when selected events occur. Method requires two parameters
type and returns the registered callback.
type designates the type of events to subscribe to.
1 for measurement data when a sensor button is pressed,
2 for alarm notifications,
4 for system notifications (e.g. sensor battery low) or set to
7 for all.
We will send a POST request to the specified address when an event is triggered.
curl -u firstname.lastname@example.org:password -d 'url=https://925.dk/' -d 'type=3' https://api.sensorist.com/v1/callbacks