User API
Ruuvi Network (Serverless) user facing API. Lifecycle: in production
User API uses a JSON based API to allow users to register, secure and edit their information as well as claim and share sensors, retrieve sensor data and alter their subscription details.
For example, if the body parameter in the sections below refers to an email field, the corresponding JSON payload would look like this:
All authenticated queries are ratelimited to 4 * MAX_SENSORS_OWNED + 0.1 * MAX_HISTORY_DAYS per minute. For example user with Basic plan has maximum of 90 days of history on 25 sensors and can make up to 109 queries per minute. The throtteled response has response code of 429 and payload of:
Register User or Reset Token
POST
https://network.ruuvi.com/register
Registers a new user or resets an existing user's password if the user already exists.
Request Body
Name | Type | Description |
---|---|---|
string | Email address to be registered / reset |
Verify Account
GET
https://network.ruuvi.com/verify
Verifies the given e-mail address and finalizes creating the account and creating a Ruuvi Network subscription. Notice that the token for this end-point is delivered via e-mail by the Register User endpoint.
Query Parameters
Name | Type | Description |
---|---|---|
token | string | Verification token (received in the e-mail) |
Request deletion of account
POST
https://network.ruuvi.com/request-delete
This operation requests complete removal of user account from Ruuvi Cloud. After a successful call to this endpoint, user gets a verification email with a link to confirm deletion of account.
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer token to authorize the request |
Request Body
Name | Type | Description |
---|---|---|
email* | String | Email of account to delete |
Verify account deletion operation
GET
https://network.ruuvi.com/verify-delete
Following actions will be done:
User sensors will be unshared
Sensors shared to user will be removed.
Data of user sensors will be deleted. (TODO)
User account data, including sensor claims and settings, will be deleted.
Account deletion is a permament action which cannot be undone
Path Parameters
Name | Type | Description |
---|---|---|
token* | String | Short verification string |
Claim a sensor for user
POST
https://netowrk.ruuvi.com/claim
After this call, given sensor is claimed under authenticated user account
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | BBearer token to authorize the request |
Request Body
Name | Type | Description |
---|---|---|
sensor* | String | MAC address of sensor to claim, e.g. "AA:BB:CC:11:22:33" |
name | String | Human-readable name of sensor, e.g. "Fridge temperature sensor" |
description | String | Human-readable description of sensor, e.g. "Sensor in top shelf of fridge" |
Unclaim a sensor from your user
POST
https://network.ruuvi.com/unclaim
Unclaims a sensor from your user, revoking your own access to it and making it claimable by other users.
Headers
Name | Type | Description |
---|---|---|
Authorization* | string | Bearer token to authorize the request |
Request Body
Name | Type | Description |
---|---|---|
sensor* | string | ID of the sensor to be unshared |
deleteData | boolean | set to true to delete user data |
Share a sensor
POST
https://network.ruuvi.com/share
You can share your sensor data with other users via share end-point. In addition to sensor you want to share, you must also include the e-mail address of the recipient. This will grant them access to the data via the get end-point. Furthermore, it will also send the target user a notification e-mail about the new share. If the target user does not exist yet, an invitation to create an account will be sent to them and they will gain access upon sign up.
Headers
Name | Type | Description |
---|---|---|
Authorization | string | Bearer token to authorize the request |
Request Body
Name | Type | Description |
---|---|---|
user | string | E-mail of the user to share to |
sensor | string | Sensor ID to share |
Unshare a sensor
POST
https://network.ruuvi.com/unshare
Unshares (i.e. revokes access to) the sensor from a target user. This can also currently be used to remove sensors shared with your user.
Headers
Name | Type | Description |
---|---|---|
Authorization | string | Bearer token of the user |
Request Body
Name | Type | Description |
---|---|---|
sensor | string | ID of the sensor being unshared |
user | string | E-mail of the user the sensor is shared to. Optional if removing sensor shared to current user. |
Get your sensors
GET
https://network.ruuvi.com/sensors
Fetches a list of sensors you have access to including who those are shared to. This end-point deprecates the old shared end-point.
Query Parameters
Name | Type | Description |
---|---|---|
sensor | string | Optionally filter only one sensor |
Headers
Name | Type | Description |
---|---|---|
Authorization | string | Bearer token of the user |
Get your sensors with calibration data, latest measurement, and alerts settings
GET
https://network.ruuvi.com/sensors-dense
Fetches the list of claimed and shared sensors with calibration data, sensor last measurement, subscription type and alert settings. By default the endpoint returns only the claimed sensors with calibration data. Optional arguments must be passed to get shared sensors, last measurement, and alert settings.
Query Parameters
Name | Type | Description |
---|---|---|
sensor | string | Optionally filter only one sensor |
sharedToOthers | bool | Optionally returns the list of users with whom each of the sensors is shared to. Returns empty list for non-owners |
sharedToMe | bool | Optionally returns the sensors shared to the logged-in user alongside claimed sensors by the user |
measurements | bool | Optionally returns the latest measurement of each of the sensors in the collection. Returns also the subscription on which the data is based on. |
alerts | bool | Optionally returns the alerts settings of each of the sensors in the collection |
mode | string | Fetch mode: [dense, sparse, mixed], determines how the data is returned. Default: mixed |
Get User Info
GET
https://network.ruuvi.com/user
Fetches user information for an authenticated user.
Headers
Name | Type | Description |
---|---|---|
Authentication | string | Authentication Bearer token retrieved from the login flow. |
Get Sensor data
GET
https://network.ruuvi.com/get
Returns the data points for the requested sensor. Notice that for implementing pagination, you can use since and until parameters with custom limit to segment your results as they are always returned in either ascending or descending order by timestamp.
Data can be fetched in dense, sparse and mixed mode. Dense mode returns highest data density possible, but has a limited time range before data is pruned to save storage space. Sparse mode has downsampled data, but time range is not limited. Mixed mode returns all the dense data available and rest of the time range is filled with sparse data
Query Parameters
Name | Type | Description |
---|---|---|
mode | string | Fetch mode: [dense, sparse, mixed], determines how the data is returned. Default: mixed |
until | string | Maximum timestamp of first returned result in Unix epoch format, in seconds. Default until now. |
since | string | Minimum timestamp of first returned result in Unix epoch format, in seconds. Default 0. |
limit | string | Maximum amount of results returned (capped at 5000). |
sort | string | Sort Direction for the result: [asc, desc]. Default descending |
sensor* | string | Sensor ID to retrieve the data |
Headers
Name | Type | Description |
---|---|---|
Authorization | string | Bearer token to authorize the request |
Update Sensor metadata
POST
https://network.ruuvi.com/update
Updates sensor metadata.
Headers
Name | Type | Description |
---|---|---|
Authorization | string |
Request Body
Name | Type | Description |
---|---|---|
picture | string | Filename of a picture (or URL if uploaded) |
offsetHumidity | number | Offset humidity to calibrate sensor |
offsetPressure | number | Offset pressure to calibrate sensor |
offsetTemperature | number | Offset temperature to calibrate sensor |
public | boolean | If true, data will be publicly accessible. |
sensor | string | Sensor ID to update |
name | string | Desired name of the tag |
timestamp | number | Epoch timestamp in seconds of settings. If backend has fresher data stored, this will be ignored. |
Upload Sensor image (part 1)
POST
https://network.ruuvi.com/upload
Retrieves a signed upload URL to a bucket. This makes the back-end ready for the image upload to happen.
Headers
Name | Type | Description |
---|---|---|
Authorization | string | Bearer token of the user |
Request Body
Name | Type | Description |
---|---|---|
action | string | One of: upload, reset (default: 'upload' if not given') |
sensor | string | ID of the target Sensor |
type | string | (Required when type is 'upload') Content-Type of the desired image upload. Supported formats: image/png image/gif image/jpeg |
Upload the actual image
PUT
<URL FROM part 1>
Create a PUT request to the URL produced by /upload end-point with the data payload to complete the upload.
Headers
Name | Type | Description |
---|---|---|
Content-Type | string | Matching content type to part 1 |
Request Body
Name | Type | Description |
---|---|---|
Image binary data | object | Binary data for the image upload |
Get User Settings
GET
https://network.ruuvi.com/settings
Gets the full list of existing user settings.
Headers
Name | Type | Description |
---|---|---|
Authorization | string | Bearer token of the user |
Update user setting
POST
https://network.ruuvi.com/settings
Sets a single user setting (currently).
Headers
Name | Type | Description |
---|---|---|
Authorization | string | Bearer token of the user |
Request Body
Name | Type | Description |
---|---|---|
value | string | Setting value |
name | string | Setting key (alphanumeric with "_", "-" and "." |
timestamp | number | Epoch timestamp in seconds of settings. If backend has fresher data stored, this will be ignored. |
Create and update Alerts
POST
https://network.ruuvi.com/alerts
Sets an alert on a sensor for a given metric. The alert condition is tested against the absolute value received from the sensors in conjunction with the use set offsets for that particular sensor.
Proposed values are marked with *.
Request Body
Name | Type | Description |
---|---|---|
counter | number | For movement alerts, one can manually set the current number |
type | string | One of: temperature, humidity, pressure, signal, movement, offline |
min | number | Lower limit for the alert |
max | number | Upper limit for the alert |
enabled | boolean | Used to toggle alert on and off |
sensor | string | Sensor MAC of the target sensor |
timestamp | number | Epoch timestamp in seconds of settings. If backend has fresher data stored, this will be ignored. |
delay | number | How many *seconds* alert condition has to be valid before alert gets triggered. Delay is reset if alert is cleared. Defaults to 0. |
Get alerts
GET
https://network.ruuvi.com/alerts
Fetches alerts for all sensors user has access to or a single sensor if optional parameter is provided.
Request Body
Name | Type | Description |
---|---|---|
sensor | string | Optional Sensor MAC for filter the alerts |
Check if a sensor with given MAC address is claimed by someone
GET
https://network.ruuvi.com/check
Query Parameters
Name | Type | Description |
---|---|---|
sensor* | MAC address | AA:BB:CC:DD:EE:FF (String) |
Headers
Name | Type | Description |
---|---|---|
Authorization* | Bearer | Bearer <Bearer Token> |
Contest ownership of a sensor
POST
https://network.ruuvi.com/contest-sensor
This call is used to reclaim a sensor claimed by someone else. After this endpoint returns 200, the sensor is claimed by calling account. Parameters are passed as a body JSON object.
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer token of the user |
Request Body
Name | Type | Description |
---|---|---|
sensor* | String | MAC address of sensor to reclaim |
secret* | String | Secret of sensor to reclaim |
Claim a subscription by a code
POST
https://network.ruuvi.com/subscription
This endpoints applies a new subscription to user immediately. Previous subscription is lost. Parameters are passed as JSON in body. The success response has full subscription history of user, with active subscription being first element of array of subscriptions.
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer token of the user |
Request Body
Name | Type | Description |
---|---|---|
code* | String | Code of subscription |
Get subscription history
GET
https://network.ruuvi.com/subscription
Return array of JSON objects detaling the subscriptions user has had.
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer token of the user |
Register a push notification token for user
POST
https://network.ruuvi.com/push-register
Register a device to Cloud so Cloud can send push notifications to user. Currently only alerts for Android and iOS are supported.
Tokens must be unique, one token cannot be associated with two accounts. If token already exists in Ruuvi Cloud with another account, the token will be removed from old account.
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer token of the user |
Request Body
Name | Type | Description |
---|---|---|
token* | String | Device identification token |
type* | String | Device type, e.g. "Android" or "iOS" |
data | String | Optional data to be passed to to push notification. Can be e.g. authentication token. |
params | String | Optional parameters used internally by Ruuvi Cloud when delivering notifications. Currently unused,this is for future needs |
name | String | Human-readable device name, e.g. "Otso's mobile phone". Defaults to device type. |
Remove a push notification token for user
POST
https://network.ruuvi.com/push-unregister
Removes given token from user, e.g. when signing off from the app. This does not require authentication to ensure that a device can always unregister itself.
Either full token or Token ID must be given, but both are optional. If both arguments are given, either can be processed but not both in one request.
Request Body
Name | Type | Description |
---|---|---|
token | String | Device identification token |
id | String | Token ID received in listing of tokens |
Get a list of tokens associated with user account
GET
https://network.ruuvi.com/push-list
List all tokens of user. Returns a listing of tokenId - name pairs.
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer token of the user |
Last updated