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