> For the complete documentation index, see [llms.txt](https://spdocs.xyte.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spdocs.xyte.io/integrators-api/api-documentation.md).

# API Reference

## Get Device Info

<mark style="color:blue;">`GET`</mark> `https://sphub.syncpro.io/v1/devices/:id`

This endpoint allows you to get Get device information from the server.

#### Path Parameters

| Name | Type   | Description   |
| ---- | ------ | ------------- |
| id   | string | Device's Uuid |

#### Headers

| Name           | Type   | Description         |
| -------------- | ------ | ------------------- |
| Contenet-Type  | string | application/json    |
| Authentication | string | Device's access key |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{
    "id":"11111111-2222...",
    "name": "Room Device",
    "version": 17,
    "manufacturer":
    {
        "mac":"11:22:33:44:55:BB"
        "sn":"12345"
        "vendor":"ACME"
        "model":"Super10"
    },
    "config":
    {
        "version":0
    },
    "state":{},
    "custom": {},
    "last_seen":"2020-01-01T01:00:00.000Z"
}
```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
{
    "error":"Not authorized"
}
```

{% endtab %}
{% endtabs %}

## Send Telemetry&#x20;

<mark style="color:green;">`POST`</mark> `https://sphub.syncpro.io/v1/devices/:id/telemetry`

Send telemetry to the cloud server.\
\
Every device should periodically send telemetry to the server. Additionally, when an important event happens (e.g., an occupancy sensor detects an occupancy change), an immediate telemetry report should be sent.\
\
Different data points can be sent in each; the server will automatically merge and aggregate the data across reports.\
\
**Note:** Telemetry should be sent at least every 5 minutes to allow the server to detect if the device goes offline.\
\
**Note:** The common object MUST include a status string field  - "online"/"offline"/"error"

#### Path Parameters

| Name | Type   | Description   |
| ---- | ------ | ------------- |
| id   | string | Device's Uuid |

#### Headers

| Name           | Type   | Description         |
| -------------- | ------ | ------------------- |
| Contenet-Type  | string | application/json    |
| Authentication | string | Device's access key |

#### Request Body

| Name      | Type   | Description                                                                                                                          |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| common    | string | Object to include all common telemetry as defined in the Common Telemetry section.                                                   |
| timestamp | string | <p>Time when the telemetry was taken, a string based on ISO\_8601.<br><br>Example:<br><code>2020-01-01T01:00:00.000Z</code><br> </p> |

{% tabs %}
{% tab title="201 Received telemetry message" %}

```
{
    "config_version":9
    "command":true
    "new_licenses":false
    "success":true
}
```

{% endtab %}

{% tab title="401 Invalid device id or access key" %}

```
{
    "error":"Not authorized"
}
```

{% endtab %}

{% tab title="422 Error in data" %}

```
{
    "error":"Missing 'common' telemetry object"
}
```

{% endtab %}
{% endtabs %}

## Get Config&#x20;

<mark style="color:blue;">`GET`</mark> `https://sphub.syncpro.io/v1/devices/:id/config`

Get latest device configuration from the server.\
After getting the configuration, the device should apply it and save its version number locally.

#### Path Parameters

| Name | Type   | Description   |
| ---- | ------ | ------------- |
| id   | string | Device's Uuid |

#### Headers

| Name           | Type   | Description         |
| -------------- | ------ | ------------------- |
| Contenet-Type  | string | application/json    |
| Authentication | string | Device's access key |

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

```
{
    "version":10
    "last_updated":"2020-01-01T01:01:01.000+00:00"
    "network":{
    "ip":"192.168...."
    "...":"..."
    }
        "other":{
        "data":"..."
    }
    }
```

{% endtab %}

{% tab title="401 Invalid device id or access key" %}

```
{
    "error":"Not authorized"
}
```

{% endtab %}
{% endtabs %}

## Set Config&#x20;

<mark style="color:green;">`POST`</mark> `https://sphub.syncpro.io/v1/devices/:id/config`

Notify the server that the device configuration has changed or the received configuration was applied.\
\
The local configuration of the device can be changed for two reasons:\
1\.  The Get Config API returned a configuration object with a higher version number.\
2\. A user changed the device configuration locally.\
\
**Local configuration update by operator**\
Increase the `version` number and call this API to update the server of the new configuration\
\
**New configuration received from Get Config**\
MUST call to this API to notify the server that the configuration was applied successfully.\
\
A successful configuration request will return the new configuration object version. This number must be saved instead of the previous configuration version number.

#### Path Parameters

| Name | Type   | Description   |
| ---- | ------ | ------------- |
| id   | string | Device's Uuid |

#### Headers

| Name           | Type   | Description         |
| -------------- | ------ | ------------------- |
| Contenet-Type  | string | application/json    |
| Authentication | string | Device's access key |

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

```
  {
    "version":10
    "last_updated":"2020-01-01T01:01:01.000+00:00"
    "network":{
    "ip":"192.168...."
    "...":"..."
    }
        "other":{
        "data":"..."
    }
    }
```

{% endtab %}

{% tab title="401 Invalid device id or access key" %}

```
{
    "error":"Not authorized"
}
```

{% endtab %}
{% endtabs %}

## Send Dump&#x20;

<mark style="color:green;">`POST`</mark> `https://sphub.syncpro.io/v1/devices/:id/dump`

Sends a full report to the server that can be used to analyze any issues on the device.\
\
The report is a simple text blob without any structure and can be of arbitrary size.\
\
**Note:** This request uses special header: text/plain.

#### Path Parameters

| Name | Type   | Description   |
| ---- | ------ | ------------- |
| id   | string | Device's Uuid |

#### Headers

| Name           | Type   | Description         |
| -------------- | ------ | ------------------- |
| Contenet-Type  | string | text/plain          |
| Authentication | string | Device's access key |

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

```
{
  "success": true
}
```

{% endtab %}

{% tab title="401 Dump is not allowed for this device" %}

```
{
"error":"Data can't be blank"
}
```

{% endtab %}

{% tab title="422 Invalid device id or access key" %}

```
{
    "error":"Not authorized"
}
```

{% endtab %}
{% endtabs %}