# Internal API

The Internal API consists of a set of endpoints designed to govern the Ruuvi Network, such as whitelisting and blacklisting devices and/or IP addresses.

## whitelist

<mark style="color:green;">`POST`</mark> `https://network.ruuvi.com/whitelist`

Whitelists a set of gateways.

#### Headers

| Name              | Type   | Description                                      |
| ----------------- | ------ | ------------------------------------------------ |
| X-Internal-Secret | string | The secret to authenticate with the internal API |

#### Request Body

| Name | Type   | Description                                                                                     |
| ---- | ------ | ----------------------------------------------------------------------------------------------- |
|      | object | JSON object containing a list of Gateway Mac Addresses and their corresponding Signing Secrets. |

{% tabs %}
{% tab title="200 In case of success, a 200 OK is returned." %}

```
{
  "gateway": "<<MAC>>",
  "blockedAt": <<TIMESTAMP IF BLOCKED>>
}
```

{% endtab %}

{% tab title="400 If the provided data is invalid, 400 is returned." %}

```
```

{% endtab %}

{% tab title="403 In case no internal secret or invalid internal secret is provided, you will receive a 403 Forbidden." %}

```
```

{% endtab %}
{% endtabs %}

```
POST /whitelist
{
    "macAddress": "ab:ba:cd:ba:cd:ba",
    "secret": "1234"
}

```

<mark style="color:blue;">`GET`</mark> `https://network.ruuvi.com/gwinfo`

Fetches info for the gateway

#### Query Parameters

| Name    | Type   | Description         |
| ------- | ------ | ------------------- |
| gateway | string | Gateway Mac Address |

#### Headers

| Name              | Type   | Description                                      |
| ----------------- | ------ | ------------------------------------------------ |
| X-Internal-Secret | string | The secret to authenticate with the internal API |

{% tabs %}
{% tab title="200 " %}

```
{
    "result": "success",
    "data": {
        "gateway": {
            "GatewayId": "<<GATEWAY MAC>>",
            "Whitelisted": <<UNIX TIMESTAMP WHEN WHITELISTED>>,
            "Connected": <<FIRST CONNECTED AFTER WHITELISTING>>,
            "Latest": <<MOST RECENT UPDATE>>,
            "InvalidSignatureTimestamp": <<MOST RECENT SIGNING REJECTION>>
        }
    }
}
```

{% endtab %}

{% tab title="401 If not authorized" %}

```
```

{% endtab %}
{% endtabs %}

## Register a sensor to Cloud

<mark style="color:green;">`POST`</mark> `https://network.ruuvi.com/register-sensor`

This operation register a sensor with MAC address + secret to Cloud. The secret can be used to verify ownership of a sensor in case of a contested sensor.

Parameters are packed inside a JSON object, e.g. { "macAddress":"value", "secret":"value"}

#### Headers

| Name              | Type   | Description                                      |
| ----------------- | ------ | ------------------------------------------------ |
| X-Internal-Secret | String | The secret to authenticate with the internal API |

#### Request Body

| Name                                         | Type   | Description                                             |
| -------------------------------------------- | ------ | ------------------------------------------------------- |
| macAddress<mark style="color:red;">\*</mark> | String | MAC address of sensor, 6 bytes. e.g. "AA:BB:CC:DD:EE:FF |
| secret<mark style="color:red;">\*</mark>     | String | Secret of sensor, e.g. "DE:AD:BE:EF:00:11:22:33         |

{% tabs %}
{% tab title="200: OK Sensor was added" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request A parameter is missing or data is invalid" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="403: Forbidden Missing or invalid internal secret" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Register a subscription to be claimed by user

<mark style="color:green;">`POST`</mark> `https://network.ruuvi.com/subscription-register`

This endpoint is called by Ruuvi Shop after payment for user subscription is verified. Parameters are in JSON object of body.

#### Headers

| Name                                            | Type   | Description                      |
| ----------------------------------------------- | ------ | -------------------------------- |
| X-Shop-Secret<mark style="color:red;">\*</mark> | String | Ruuvi Shop authentication secret |

#### Request Body

| Name                                                   | Type   | Description                                                                                              |
| ------------------------------------------------------ | ------ | -------------------------------------------------------------------------------------------------------- |
| validDays<mark style="color:red;">\*</mark>            | String | Validity of subscription, e.g. 365                                                                       |
| maxClaims<mark style="color:red;">\*</mark>            | Number | Number of sensors user can Claim                                                                         |
| maxShares                                              | Number | Number of shares user can have. Defaults to maxClaims \* maxSharesPerSensor                              |
| maxSharesPerSensor                                     | Number | Number of times one sensor can be shared. Defaults to 10                                                 |
| maxHistoryDays<mark style="color:red;">\*</mark>       | Number | Number of days of history user is allowed to retrieve. This does not affect sensors shared to this user. |
| maxResolutionMinutes<mark style="color:red;">\*</mark> | Number | Best resolution user is allowed to retrieve. This does not affect sensors shared to this user.           |
| subscriptionName                                       | String | Name of subscription. Defaults to "Ultimate" (custom)                                                    |
| claimCode<mark style="color:red;">\*</mark>            | String | Code used to claim this subscription                                                                     |
| creatorId                                              | String | String id for creator of code, e.g. webshop account which triggered code generation                      |

{% tabs %}
{% tab title="200: OK Subscription was registered" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="403: Forbidden Missing or invalid authentication header" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request Missing required fields in payload" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="500: Internal Server Error Server error, request might have been valid" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="409: Conflict Subscription code already used" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Freebase Cloud Messaging to iOS devices - Proposal 2023-02-08

<mark style="color:green;">`POST`</mark> `FCM://iOS`

FCM is used to deliver push notifications to user applications. To receive the notification, user must register their device token with a POST to <https://network.ruuvi.com/push-register>

`{ "notification":{`\
`"body": $alertData,`\
`"title":"Ruuvi $alertType alert: $name"`\
`},`\
`"alert":{`\
`"title-loc-key": RUUVI_$alertType,`\
`"title-loc-args": [$alertType, $triggertype],`\
`"loc-key" : "RUUVI_$alertType_$triggerType",`\
`"loc-args" : [ $name, $currentValue, $alertUnit, $thresholdValue, $alertUnit]`\
`},`\
`"content_available":1,`\
`"mutable-content":1,`\
`"token":$token,`\
`"email":$email,`\
`"type":"alert",`\
`"data":{`\
`"name": $name,`\
`"id":$`sensor\_id`,`\
`"alertType": $alertType,`\
`"triggerType": $triggertype,`\
`"currentValue": $currentValue,`\
`"thresholdValue": $thresholdValue,`\
`"alertUnit": $alertUnit,`\
`"alertData": $alertData`\
`}`\
`}`

#### Request Body

| Name                                             | Type   | Description                                                                                                          |
| ------------------------------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------- |
| alertData                                        | String | User-defined alert title. May be empty string                                                                        |
| alertType<mark style="color:red;">\*</mark>      | String | Physical quantity of alert, one of: {"Temperature", "Humidity", "Pressure", "Movement", "Voltage", "RSSI", "noData"} |
| triggerType<mark style="color:red;">\*</mark>    | String | Type of violation, one of {"Over", "Under", "Different from"}                                                        |
| name<mark style="color:red;">\*</mark>           | String | User-configured sensor name                                                                                          |
| alertUnit<mark style="color:red;">\*</mark>      | String | Unit of alert, e.g. "C", "F", "K"                                                                                    |
| currentValue<mark style="color:red;">\*</mark>   | String | Current value of alerting sensor, in alertUnit units                                                                 |
| thresholdValue<mark style="color:red;">\*</mark> | String | Threshold value of alerting sensor, in alertUnit units                                                               |
| token<mark style="color:red;">\*</mark>          | String | FCM Token of receiver                                                                                                |
| sensor\_id<mark style="color:red;">\*</mark>     | String | MAC Address of alerting senser                                                                                       |
| email<mark style="color:red;">\*</mark>          | String | User email                                                                                                           |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ruuvi.com/communicate-with-ruuvi-cloud/cloud/internal-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.