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

TypeDescriptionControl Type
smarthingsSamsung SmartThings devicesbackend
nestNest devicesbackend
smartTVSmart TVsclient
huePhilips Hueclient

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.

FieldTypeDescription
typeStringDevice type
descriptionStringDescription of the type
controlledStringControl 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

FieldSourceMandatoryTypeDescription
controlledQueryStringValid values:
"backend": Backend controlled device type
"client": Client controlled device types

Response
Status: 200 OK
Response data content completed by device type.

FieldTypeDescription
typeStringDevice type
descriptionStringDescription of the type
controlledStringControl Type: backend or client

Device Fields

The device fields required are dependent upon the device type.

Backend Controlled Devices

FieldMandatoryTypeDescription
nameStringUser friendly name

Client Controlled Devices

FieldMandatoryTypeDescription
nameStringUser friendly name
ipStringInternal 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

FieldTypeDescription
typeStringDevice type. See Device Types.
idStringInternal 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

FieldSourceMandatoryTypeDescription
typeQueryStringDevice 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

FieldTypeDescription
typeStringDevice type. See Device Types.
idStringInternal 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

FieldSourceMandatoryTypeDescription
idQueryStringInternal device ID

Response
Status: 200 OK
Device Detail response data content completed by device type.

FieldTypeDescription
typeStringDevice type. See Device Types.
idStringInternal 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

FieldSourceMandatoryTypeDescription
typeQueryStringDevice type. See Device Types.
----Device specific fields

Response
Status: 200 OK

FieldTypeDescription
typeStringDevice type. See Device Types.
idStringInternal 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

FieldSourceMandatoryTypeDescription
idQueryStringInternal device ID

Response
Status: 200 OK

FieldTypeDescription
typeStringDevice type. See Device Types.
idStringInternal 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

FieldSourceMandatoryTypeDescription
idQueryStringInternal device ID

Response
Status: 200 OK