Please report any errors in these documents to contact@sensorist.com.
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 max-age HTTP 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.
Query for multiple items at once where possible. Sensible rate limits apply. Handle 429 responses gracefully.
We continuously monitor the API and strive to keep the (average) response time within 100-200 milliseconds.
https://api.sensorist.com/v1
TLS 1.2 or 1.3 and HTTP basic authentication are 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 the data exchange format and content may be gzip compressed.
curl -u my@email.com:password https://api.sensorist.com/v1/users
The diagram 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 in Coordinated Universal Time (UTC) and ISO 8601 formatted.
Get user and account details. Method returns a user object corresponding to the authorized user.
The optional parameter list provides an array of all users in your hierarchy.
curl -u my@email.com:password https://api.sensorist.com/v1/users
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 include to slaves.
curl -u my@email.com:password https://api.sensorist.com/v1/gateways
Get measurement values. Method requires two parameters data_sources and type and returns an array of measurements.
data_sources must be a comma-separated list of the ids of the data sources to fetch measurements for. Note that you can only retrieve measurements for one gateway at a time, so the data sources in the list must all belong to the same gateway.
type must be one of 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 is described in more detail below.
Optional parameters from and to are dates specifying the period of interest. If not provided or invalid, the period defaults to the past week.
latest the most recent measurements. The period is ignored.
min_max minimum and maximum values in the period and their respective dates.
range returns 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 a 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 have 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.
curl -u my@email.com:password 'https://api.sensorist.com/v1/measurements?data_sources=1,2&type=latest'
curl -u my@email.com:password 'https://api.sensorist.com/v1/measurements?data_sources=1,2&type=raw&from=2018-04-25T09:00:00Z'
Get the data source alarms set by the user and their current state. Method requires no parameters and returns an array of alarms and most recent logs.
To include notes set parameter include to notes.
curl -u my@email.com:password https://api.sensorist.com/v1/alarms
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 ids and by dates from and to specifying the period of interest.
By default the history is returned chronologically with separate entries for in and out of the alarm. To have them returned pairwise instead set parameter format to pairs, and to have system notifications interleaved set to combined.
To include notes set parameter include to notes.
curl -u my@email.com:password https://api.sensorist.com/v1/alarms/history
Get list of registered callbacks. Method requires no parameters and returns an array of callbacks.
curl -u my@email.com:password https://api.sensorist.com/v1/callbacks
Get workflow with id. Method returns the workflow.
Workflows are proxy constructs that represent and manage 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 my@email.com:password https://api.sensorist.com/v1/workflows/5
Create a new user account. Method requires parameters email, password, fname and lname. Method returns the created user.
Optional parameter email_confirmed may be set to true if the email address has been pre-confirmed, provided you have the necessary privileges.
curl -u my@email.com:password -d 'email=my@email.com' -d 'password=12345678' -d 'fname=my' -d 'lname=name' https://api.sensorist.com/v1/users
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 my@email.com:password -d 'serial=00000000' -d 'name=Home' https://api.sensorist.com/v1/gateways
Update gateway with id. Method accepts parameter name to update the gateway display name. Method returns the updated gateway.
curl -u my@email.com:password -d 'name=Office' https://api.sensorist.com/v1/gateways/5
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 my@email.com:password -d 'command=reboot' https://api.sensorist.com/v1/gateways/5/commands
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 my@email.com:password -d 'interval=900' https://api.sensorist.com/v1/sensors/17
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 above or below.
You may optionally specify a delay in minutes. E.g. 60 to trigger the alarm only after one hour of measurements continuously breaching the threshold.
Method returns the created alarm.
curl -u my@email.com:password -d 'data_source=1' -d 'value=-5' -d 'direction=below' https://api.sensorist.com/v1/alarms
Notes are immutable free-text annotations that can be attached to alarm logs and system notifications.
Create a note. Method requires exactly one of alarm_log or notification, the id of the entry to annotate, and the note text.
Method returns the created note.
curl -u my@email.com:password -d 'alarm_log=7' -d 'note=Fridge door left open' https://api.sensorist.com/v1/notes
Register a callback URL. Receive HTTP/S notifications when selected events occur. Method requires two parameters url and 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 my@email.com:password -d 'url=https://925.dk/' -d 'type=3' https://api.sensorist.com/v1/callbacks
Delete alarm(s). Specify the id of the alarm to delete or omit it to delete all.
curl -u my@email.com:password -X 'DELETE' https://api.sensorist.com/v1/alarms/2
Delete callback(s). Specify the id of the callback to delete or omit it to delete all.
curl -u my@email.com:password -X 'DELETE' https://api.sensorist.com/v1/callbacks/5