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.
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 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 my@email.com:password https://api.sensorist.com/v1/users
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.
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 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 with_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 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.
Optional parameters from and 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.
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 takes no parameters and returns an array of alarms and most recent logs.
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 id's and by dates from and to specificing the period of interest.
By default the history is returned chronological 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.
curl -u my@email.com:password https://api.sensorist.com/v1/alarms/history
Get list of registered callbacks. Method takes 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 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 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 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 my@email.com:password -d 'data_source=1' -d 'value=-5' -d 'direction=below' https://api.sensorist.com/v1/alarms
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). Optionally specify the id of the alarm to delete.
curl -u my@email.com:password -X 'DELETE' https://api.sensorist.com/v1/alarms/2
Delete callback(s). Optionally specify the id of the callback to delete.
curl -u my@email.com:password -X 'DELETE' https://api.sensorist.com/v1/callbacks/5