Devices
The API offers endpoints to maintain data about the devices that users integrate into Sherpa.ai Platform.
According to the device configuration and management access form, there are two categories:
-
Backend controlled
Devices that can be controlled from Sherpa.ai's backend. For example:- SmartThings
- Nest
-
Client controlled
Devices that must be controlled from within the user's local network. For example:- SmartTV
- Philips Hue
**Security Restrictions**
Authenticated users MUST have **USER_DEVICES** role permissions in order to be able to execute device endpoint requests.
Device Types
Supported Device Types
Currently supported device types
Type | Description | Control Type |
---|---|---|
smarthings | Samsung SmartThings devices | backend |
nest | Nest devices | backend |
smartTV | Smart TVs | client |
hue | Philips Hue | client |
GET /devices/types
Return the list of currently supported device types.
curl -X GET "https://api.sherpa.ai/v2/devices/types" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX"
[{
"type": "smartthings",
"description": "Samsung SmartThings",
"controlled": "backend"
},
{
"type": "smartTV",
"description": "Smart TV",
"controlled": "client"
}, ...
]
Response
Status: 200 OK
Currently suported device type list.
Field | Type | Description |
---|---|---|
type | String | Device type |
description | String | Description of the type |
controlled | String | Control Type: backend or client |
GET /devices/types/backend
GET /devices/types/client
Return the list of currently supported device types for a given controlled type.
curl -X GET "https://api.sherpa.ai/v2/devices/types/client" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX"
[{
"type": "smartTV",
"description": "Smart TV",
"controlled": "client"
},
{
"type": "hue",
"description": "Philips Hue",
"controlled": "client"
}]
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
controlled | Query | ✓ | String | Valid values: "backend": Backend controlled device type "client": Client controlled device types |
Response
Status: 200 OK
Response data content completed by device type.
Field | Type | Description |
---|---|---|
type | String | Device type |
description | String | Description of the type |
controlled | String | Control Type: backend or client |
Device Fields
The device fields required are dependent upon the device type.
Backend Controlled Devices
Field | Mandatory | Type | Description |
---|---|---|---|
name | ✓ | String | User friendly name |
Client Controlled Devices
Field | Mandatory | Type | Description |
---|---|---|---|
name | ✓ | String | User friendly name |
ip | ✓ | String | Internal network current IP |
List
GET /devices
Return the list of all currently registered devices.
curl -X GET "https://api.sherpa.ai/v2/devices" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX"
[{
"type": "smartthings",
"name": "Living room Lamp",
"id": "5f971b51-d5ca-421b-b2b0-4d9bace8595f"
},
{
"type": "nest",
"name": " Living room Thermostat",
"id": "8585cd61-731c-472e-a334-71fbf158ad50"
}
]
Response
Status: 200 OK
List of Devices
Field | Type | Description |
---|---|---|
type | String | Device type. See Device Types. |
id | String | Internal device ID |
- | - | Device specific fields |
List by Type
GET /devices/{type}
Get all devices by type.
curl -X GET "https://api.sherpa.ai/v2/devices/smarthings" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX"
[{
"type": "smartthings",
"name": "Living room Lamp",
"id": "5f971b51-d5ca-421b-b2b0-4d9bace8595f"
}]
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
type | Query | ✓ | String | Device type. See Device Types. |
Response
The client could receive a redirect in the response. If this occurs, open the redirect url (Location field of the Response Header) in a browser or a WebView.
When no redirection is needed:
Status: 200 OK
Field | Type | Description |
---|---|---|
type | String | Device type. See Device Types. |
id | String | Internal device ID |
- | - | Device specific fields |
Get
GET /devices/{id}
Get information about a device ID.
curl -X GET "https://api.sherpa.ai/v2/devices/5f971b51-d5ca-421b-b2b0-4d9bace8595f" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX"
{
"type": "smartthings",
"name": "Livingroom Lamp",
"id": "5f971b51-d5ca-421b-b2b0-4d9bace8595f"
}
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
id | Query | ✓ | String | Internal device ID |
Response
Status: 200 OK
Device Detail response data content completed by device type.
Field | Type | Description |
---|---|---|
type | String | Device type. See Device Types. |
id | String | Internal device ID |
- | - | Device specific fields |
Add
POST /devices/{type}
Registers a new device to the platform.
curl -X POST "https://api.sherpa.ai/v2/devices/smarthings" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX"
-d "{\"name\":\"Livingroom Lamp\"}"
{
"type": "smartthings",
"name": "Livingroom Lamp",
"id": "5f971b51-d5ca-421b-b2b0-4d9bace8595f"
}
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
type | Query | ✓ | String | Device type. See Device Types. |
- | - | - | - | Device specific fields |
Response
Status: 200 OK
Field | Type | Description |
---|---|---|
type | String | Device type. See Device Types. |
id | String | Internal device ID |
- | - | Device specific fields |
Update
PUT /devices/{id}
Update a previously registered device.
curl -X PUT "https://api.sherpa.ai/v2/devices/5f971b51-d5ca-421b-b2b0-4d9bace8595f" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX"
-d "{\"name\":\"Entrance livingroom Lamp\"}"
{
"type": "smartthings",
"name": "Entrance livingroom Lamp",
"id": "5f971b51-d5ca-421b-b2b0-4d9bace8595f"
}
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
id | Query | ✓ | String | Internal device ID |
Response
Status: 200 OK
Field | Type | Description |
---|---|---|
type | String | Device type. See Device Types. |
id | String | Internal device ID |
- | - | Device specific fields |
Delete
DELETE /devices/{id}
Delete a previously registered device.
curl -X DELETE "https://api.sherpa.ai/v2/devices/5f971b51-d5ca-421b-b2b0-4d9bace8595f" \
-H "Authorization: Basic XXXX-SHERPA-TOKEN-XXXX"
Parameters
Field | Source | Mandatory | Type | Description |
---|---|---|---|---|
id | Query | ✓ | String | Internal device ID |
Response
Status: 200 OK