API Reference

Get Device Info

GET 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

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"
}

404 Could not find a cake matching this query.

{
    "error":"Not authorized"
}

Send Telemetry

POST 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	Time when the telemetry was taken, a string based on ISO_8601. Example: 2020-01-01T01:00:00.000Z

201 Received telemetry message

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

401 Invalid device id or access key

{
    "error":"Not authorized"
}

422 Error in data

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

Get Config

GET 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

200 Success

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

401 Invalid device id or access key

{
    "error":"Not authorized"
}

Set Config

POST 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

200 Success

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

401 Invalid device id or access key

{
    "error":"Not authorized"
}

Send Dump

POST 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

200 Success

{
  "success": true
}

401 Dump is not allowed for this device

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

422 Invalid device id or access key

{
    "error":"Not authorized"
}