User API

Ruuvi Cloud 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. Fields marked with * are mandatory, and omitting them results in backend returning HTTP 400 - Bad Request.

For example, if the body parameter in the sections below refers to an email field, the corresponding JSON payload would look like this:

{
    "email": "<YOUR VALUE>"
}

Note that GET requests use URL parameters, e.g. https://network.ruuvi.com/sensors-dense?measurements=true, but the Authorization bearer token is in headers.

All authenticated queries are ratelimited to 8 * 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 209 queries per minute. The throtteled response has response code of 429 and payload of:

{
      result: 'error',
      error: 'Too many requests.',
      code: 'ER_THROTTLED'
}

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
email	string	Email address to be registered / reset

200 On a successful call, you will receive a 200 OK. An e-mail will be sent to the given address to confirm the registration. In case of a reset, the token will be provided as a response to the call.

{
    "result": "success",
    "data": {
        "email": "[email protected]"
    }
}

500 If a something goes wrong with the request itself, you might receive an Unknown error. Please contact your system administrator if this occurs.

{
    "result": "error",
    "error": "Unknown error occurred.",
    "code": "ER_INTERNAL"
}

429: Too Many Requests Over 10 calls in an hour

{
      result: 'error',
      error: 'Too many requests.',
      code: 'ER_THROTTLED'
}

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)

200 On a successful response, you will receive the confirmation on the e-mail address an an access token to be used with other end-points. Store it well as the only way to retrieve it is to go through the reset flow again.

{
    "result": "success",
    "data": {
        "email": "<E-MAIL ADDRESS OF THE USER>",
        "accessToken": "<NEW ACCESS TOKEN>",
        "newUser": <true|false>
    }
}

403 Forbidden if user is not allowed to access resource.

{
    "result": "error",
    "error": "Forbidden.",
    "code": "ER_FORBIDDEN"
}

500 (Actual code 493): You will receive an error if the token is invalid.

{
    "result": "error",
    "error": "Code used or expired.",
    "code": "ER_TOKEN_EXPIRED"
}

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

200: OK Verification email has been sent

{
    "result": "success",
    "data": {
        "email": "[email protected]"
    }
}

400: Bad Request Missing authorization or email parameter

{
    "result": "error",
    "error": "<SPECIFIC ERROR>",
    "code": "ER_<ERROR>"
}

403: Forbidden Returned if Authorization token does not match email

{
    "result": "error",
    "error": "Unauthorized request.",
    "code": "ER_UNAUTHORIZED"
}

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

200: OK Account deletion was started

{
    // Response
}

403: Forbidden Invalid or missing authorization token

{
   {
    "result": "error",
    "error": "Unauthorized request.",
    "code": "ER_UNAUTHORIZED"
}

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"

200: OK Sensor was claimed successfully

{
    "result": "success",
    "data": {
        "sensor": "C5:2A:E7:4D:CE:7F"
    }
}

400: Bad Request Request had malformed JSON or was missing a required parameter. Alternatively user account has reached subscription limit

{
    'code': {'ER_MISSING_ARGUMENT', 'ER_CLAIM_COUNT_REACHED'}
}

401: Unauthorized Request had no authorization token

{

}

409: Conflict Sensor is claimed by another account

{
    'code': 'ER_SENSOR_ALREADY_CLAIMED';
}

500: Internal Server Error Unexpected error occurred in handler

{
    // Response
}

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

200

{
    "result": "success"
}

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

200 On success, you will get the shared sensor id returned back to you.

{
    "result": "success",
    "data": {
        "sensor": "<YOUR SENSOR ID>"
        "invited": true
    }
}

400 If the sharing failed due to malformed data, such as missing arguments.

{
    "result": "error",
    "error": "Invalid E-mail given.",
    "code": "ER_INVALID_EMAIL_ADDRESS"  
}

401 If an invalid or expired access token is provided, you will receive 401 Unauthorized.

{
    "result": "error",
    "error": "Unauthorized request.",
    "code": "ER_UNAUTHORIZED"
}

409 You will receive a conflict if the sensor is already shared to the user.

{
    "result": "error",
    "error": "Sensor already shared to user.",
    "code": "ER_SENSOR_ALREADY_SHARED"
}

500 If something went wrong with the request, you will receive a 500 internal server error. Please contact your System Administrator.

{
    "result": "error",
    "error": "Unknown error occurred.",
    "code": "ER_INTERNAL"
}

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.

200

{
    "result": "success"
}

400 Returned with Invalid or missing fields.

{
    "result": "error",
    "error": "<SPECIFIC ERROR>",
    "code": "ER_<ERROR>"
}

403 Returned when user

{
    "result": "error",
    "error": "Unauthorized request.",
    "code": "ER_UNAUTHORIZED"
}

404 Returned if shared sensor or user is not found.

{
    "result": "error",
    "error": "User not found.",
    "code": "ER_USER_NOT_FOUND"
}

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

200

{
    "result": "success",
    "data": {
        "sensors": [
            {
                "sensor": "<SENSOR ID>",
                "name": "<SENSOR NAME>",
                "picture": "<SENSOR PICTURE URL>",
                "public": <TRUE|FALSE>,
                "canShare": <TRUE|FALSE>,
                "offsetHumidity": <DOUBLE>,
                "offsetTemperature": <DOUBLE>,
                "offsetPressure": <DOUBLE>,
                "measurements": [
                    {
                        "gwmac": "<SOURCE GATEWAY MAC>",
                        "coordinates": "<COORDINATES / N/A>",
                        "rssi": <RSSI>,
                        "timestamp": <UNIX TIMESTAMP OF MEASUREMENT>,
                        "data": "<HEX ENCODED SENSOR DATA>"
                    }
                ]
                "sharedTo": [
                    "<EMAIL OF TARGET USER 1>",
                    ...
                ]
            },
            ...
        ],
        "sharedToMe": [
            {
                "sensor": "<SENSOR ID>",
                "name": "<SENSOR NAME>",
                "picture": "<SENSOR PICTURE URL>",
                "public": <TRUE|FALSE>,
                "canShare": <TRUE|FALSE>,
                "offsetHumidity": <DOUBLE>,
                "offsetTemperature": <DOUBLE>,
                "offsetPressure": <DOUBLE>,
                "measurements": [
                    {
                        "gwmac": "<SOURCE GATEWAY MAC>",
                        "coordinates": "<COORDINATES / N/A>",
                        "rssi": <RSSI>,
                        "timestamp": <UNIX TIMESTAMP OF MEASUREMENT>,
                        "data": "<HEX ENCODED SENSOR DATA>"
                    }
                ]
            },
        ]
    }
}

401

{
    "result": "error",
    "error": "Unauthorized.",
    "code": "ER_UNAUTHORIZED"
}

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
settings	bool	Optionally returns the sensor-specific settings of sensors.
mode	string	Fetch mode: [dense, sparse, mixed], determines how the data is returned. Default: mixed

401: Unauthorized

{
    "result": "error",
    "error": "Unauthorized.",
    "code": "ER_UNAUTHORIZED"
}

200: OK

{
    "result": "success",
    "data": {
        "sensors": [
            {
                "sensor": "<SENSOR ID>",
                "name": "<SENSOR NAME>",
                "picture": "<SENSOR PICTURE URL>",
                "public": <TRUE|FALSE>,
                "canShare": <TRUE|FALSE>,
                "offsetHumidity": <DOUBLE>,
                "offsetTemperature": <DOUBLE>,
                "offsetPressure": <DOUBLE>,
                "measurements": [
                    {
                        "gwmac": "<SOURCE GATEWAY MAC>",
                        "coordinates": "<COORDINATES / N/A>",
                        "rssi": <RSSI>,
                        "timestamp": <UNIX TIMESTAMP OF MEASUREMENT>,
                        "data": "<HEX ENCODED SENSOR DATA>"
                    }
                ],
                "sharedTo": [
                    "<EMAIL OF TARGET USER 1>",
                    ...
                ],
                "alerts": [
                    {
                        userId: <userId>,
                        sensorId: <sensorMAC>,
                        type: <humidity|pressure|temperature>,
                        min: <lower limit>,
                        max: <higher limit>,
                        enabled: <true|false>,
                        offsetHumidity: <double>,
                        offsetTemperature: <double>,
                        offsetPressure: <double>,
                        triggered: <true|false>,
                        triggeredAt: <timestamp>
                    },
                    ...
                ]
            },
            owner: <EMAIL, masked if public sensor>
            subscription: {
                    "maxHistoryDays": <INT>,
                    "maxResolutionMinutes": <INT>,
                    "emailAlertAllowed": <true|false>,
                    "pushAlertAllowed": <true|false>,
                    "subscriptionName": <STRING>
            }
            ...
        ]
    }
}

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.

200 User information successfully retrieved.

{
    "result": "success",
    "data": {
        "email": "[email protected]",
        "sensors": [
            {
                "sensor": "CD:CD:CD:CD:ED:01",
                "owner": "[email protected]",
                "name": "Sauna",
                "picture": "https://url-to/picture.png",
                "public": true
            },
            {
                "sensor": "AB:BA:CD:BE:AB:AA",
                "owner": "[email protected]",
                "name": "Kitchen",
                "picture": "",
                "public": false
            }
        ]
    }
}

401 Unauthorized request.

{
    "result": "error",
    "error": "Unauthorized request.",
    "code": "ER_UNAUTHORIZED"
}

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

200 Returns the most recent data points for the requested tag based on configuration and parameters.f

{
    "result": "success",
    "data": {
        "sensor": "<SENSOR ID>",
        "total": <TOTAL MEASUREMENTS RETURNED>,
        "name": "<SENSOR NAME>",
        "picture": "<SENSOR PICTURE URL OR FILENAME>",
        "measurements": [
            {
                "gwmac": "<SOURCE GATEWAY MAC>",
                "coordinates": "<COORDINATES / N/A>",
                "rssi": <RSSI>,
                "timestamp": <UNIZ TIMESTAMP OF MEASUREMENT>,
                "data": "<HEX ENCODED SENSOR DATA>"
            },
            ...
        ]
    }
}

400

{
    "result": "error",
    "error": "Invalid <SPECIFIC ERROR>",
    "code": "ER_INVALID_<SPECIFIC>"
}

401 In case of an invalid or expired authentication token, you will receive a unauthorized response.

{
    "result": "error",
    "error": "Unauthorized request.",
    "code": "ER_UNAUTHORIZED"
}

403 If you have not claimed or been shared the target sensor, you will receive a Forbidden.

{
    "result": "error",
    "error": "Forbidden.",
    "code": "ER_FORBIDDEN"
}

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.

200 Only returns the fields that had an update targeted to them.

{
    "result": "success",
    "data": {
        "sensor": "<SENSOR ID>",
        "name": "<GIVEN NAME>",
        "public": "<GIVEN PUBLIC VALUE>"
    }
}

403

{
    "result": "error",
    "error": "Forbidden.",
    "code": "ER_FORBIDDEN"
}

404

{
    "result": "error",
    "error": "Sensor not claimed or found. Data not updated.",
    "code": "ER_SENSOR_NOT_FOUND"
}

500

{
    "result": "error",
    "error": "Unknown error occurred.",
    "code": "ER_INTERNAL"
}

409: Conflict Cloud has fresher data than timestamp

{
    "result": "error",
    "error": "Newer setting already exists",
    "code": "ER_CONFLICT",
    "sub_code": "ER_OLD_ENTRY"
}

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

200

{
    "result": "success",
    "data": {
        "uploadURL": "<SIGNED UPLOAD URL>"
    }
}

403

{
    "result": "error",
    "error": "Forbidden.",
    "code": "ER_FORBIDDEN"
}

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

200

403

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

200

{
    "status": "success",
    "data": {
        "settings": {
            "<SETTING 1>": "<SETTING 1 VALUE>",
            ...
        }
    }
}

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.

200

{
    "status": "success",
    "data": {
        "action": "<added|updated>"
    }
}

409: Conflict Cloud has fresher data than timestamp

{
    "result": "error",
    "error": "Newer setting already exists",
    "code": "ER_CONFLICT",
    "sub_code": "ER_OLD_ENTRY"
}

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.

Headers

Name	Type	Description
Authorization*	string	Bearer token of the user

Request Body

Name	Type	Description
counter	number	For movement alerts, one can manually set the current number. If not provided, last known value is used.
type*	string	One of: temperature, humidity, pressure, signal, movement, offline, co2, pm10, pm25, pm40, pm100, sound, luminosity, voc, nox
min	number	Lower limit for the alert - omit to leave unchanged
max	number	Upper limit for the alert - omit to leave unchanged
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. Set to current second by default
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

200

{
    "result": "success",
    "data": {
        "action": "success"
    }
}

400: Bad Request

 { 
  "result": "error", 
  "error": "Invalid MAC address format", 
  "code": "ER_INVALID_MAC_ADDRESS" 
  }

409: Conflict Cloud has fresher data than timestamp

{
    "result": "error",
    "error": "Newer setting already exists",
    "code": "ER_CONFLICT",
    "sub_code": "ER_OLD_ENTRY"
}

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

200

{
    "result": "success",
    "data": {
        "alerts": [
            {
                userId: <userId>,
                sensorId: <sensorMAC>,
                description: <string>
                type: <humidity|pressure|temperature|movement|offline>,
                counter: number, // Relevant for movement
                min: <lower limit>,
                max: <higher limit>,
                enabled: <true|false>,
                offsetHumidity: <double>,
                offsetTemperature: <double>,
                offsetPressure: <double>,
                triggered: <true|false>,
                triggeredAt: <timestamp>,
                delay: <number, positive integer>
            }
        ]
    }
}

Update sensor setting

POST /sensor-settings

Configure a sensor-specific setting. Note: Offsets, image, name and shares of sensors are updated in their own endpoints. Only owner of a sensor can configure the settings.

To clear a setting, send empty string as a value of setting type.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
sensor*	string	MAC address of sensor
type*	string array	Type of the setting. Free-form. sensor+type combination is unique identifier of setting.
value*	string array	Value of setting. Length of type and value arrays must match. Settings are appended, e.g. it's allowed to configure settings individually
timestamp*	number	Epoch timestamp in seconds of settings. If backend has fresher data stored, this will be ignored. If omitted, timestamp is set to current time.

Response

200

{
    "result": "success",
    "data": {
        "action": "<added | updated>"
    }
}

400

{
    "result": "error",
    "error": "Body must be a valid JSON string",
    "code": "ER_INVALID_ARGUMENT"
}

409

{
    "result": "error",
    "error": "No setting was updated or added, newer settings might exist.",
    "code": "ER_CONFLICT"
}

500

{
    "result": "error",
    "error": "Unknown error occured in User API",
    "code": "ER_INTERNAL"
}

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>

200: OK Masked email of sensor owner, empty string if sensor is not owned

{
    "status": "success",
    "data": {
        "email": <string>
    }
}

400: Bad Request If request doesn't have "sensor" parameter, or parameter is not a valid MAC address

    "status": "success",
    "data": {
        "email": <string>
    }
}

403: Forbidden If there was no valid authentication

{
    "result": "error",
    "error": "Unauthorized request.",
    "code": "ER_UNAUTHORIZED"
}

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

200: OK Sensor ownership was transferred

{
    "result": "success",
    "data": {
        "sensor": "C5:2A:E7:4D:CE:7F"
    }
}

400: Bad Request Missing parameter or user has full claim count

{
    'code': {'ER_CLAIM_COUNT_REACHED', 'ER_MISSING_ARGUMENT'}
}

401: Unauthorized User is not authenticated

{
    'code': 'ER_UNAUTHORIZED'
}

403: Forbidden macAddress and secret do not match

{
    'code': 'ER_FORBIDDEN'
}

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

200: OK Subscription was applied successfully

{
    "result": "success",
    "data": {
        "subscriptions": [
            {
                "subscriptionName": "DEV",
                "maxClaims": 25,
                "maxShares": 40,
                "maxSharesPerSensor": 5,
                "maxHistoryDays": 720,
                "maxResolutionMinutes": 1,
                "isActive": true,
                "startTime": 1673435374,
                "endTime": 1673608174
            },
            {
                "subscriptionName": "DEV",
                "maxClaims": 25,
                "maxShares": 40,
                "maxSharesPerSensor": 5,
                "maxHistoryDays": 720,
                "maxResolutionMinutes": 1,
                "isActive": false,
                "startTime": 1673435292,
                "endTime": 1673608092
            }
        ]
    }
}

400: Bad Request Missing code

{
    "result": "error",
    "error": "Invalid request format.",
    "code": "ER_INVALID_FORMAT"
}

401: Unauthorized Missing or invalid authorization header

{
    "result": "error",
    "error": "Unauthorized request.",
    "code": "ER_UNAUTHORIZED"
}

409: Conflict Subscription code is already used

{
    "result": "error",
    "error": "Code already claimed",
    "code": "ER_SUBSCRIPTION_CODE_USED"
}

404: Not Found Subscription code does not exist

{
    "result": "error",
    "error": "Code not found",
    "code": "ER_SUBSCRIPTION_NOT_FOUND"
}

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

200: OK Returns subscription history

{
    "result": "success",
    "data": {
        "subscriptions": [
            {
                "subscriptionName": "DEV",
                "maxClaims": 25,
                "maxShares": 40,
                "maxSharesPerSensor": 5,
                "maxHistoryDays": 720,
                "maxResolutionMinutes": 1,
                "isActive": true,
                "startTime": 1673435374,
                "endTime": 1673608174
            },
            {
                "subscriptionName": "DEV",
                "maxClaims": 25,
                "maxShares": 40,
                "maxSharesPerSensor": 5,
                "maxHistoryDays": 720,
                "maxResolutionMinutes": 1,
                "isActive": false,
                "startTime": 1673435292,
                "endTime": 1673608092
            }
        ]
    }
}

403: Forbidden Request was not authenticated or authentication token was not valid

{
    "result": "error",
    "error": "Unauthorized request.",
    "code": "ER_UNAUTHORIZED"
}

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.

200: OK Token was successfully registered

{
    "result": "success",
    "data": {
        "tokenId": INT
    }
}

400: Bad Request Request had malformed data

{
    // Response
}

401: Unauthorized Request did not have authentication

{
    // Response
}

403: Forbidden Authentication was invalid

{
    // Response
}

500: Internal Server Error Internal problem. Try again later.

{
    // Response
}

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

200: OK Token was removed

{
    // Response
}

400: Bad Request Message body did not have required data

{
    // Response
}

500: Internal Server Error Internal problem. Try again later.

{
    // Response
}

404: Not Found Given token or ID was not found.

{
    // Response
}

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

200: OK List was successfully retrieved

{
    "result": "success",
    "data": {
        "tokens": [
            {
                "id": 3308157406,
                "lastAccessed": 1674799893,
                "name": "Otso's landline"
            },
            {
                "id": 3721015809,
                "lastAccessed": 1674799924,
                "name": "Otso's mobile phone"
            }
        ]
    }
}

401: Unauthorized Authentication token was missing

{
    // Response
}

403: Forbidden Authentication token is invalid

{
    // Response
}

500: Internal Server Error Iinternal problem. Try again later.

{
    // Response
}