Device Group Management REST API Reference
Use the Device Group Management REST API to create groups of devices within a unit.
A device group represents a group of devices that a user can control together by speaking to an Alexa Built-in device that's a member of the group. Targeting can be explicit or implicit. Explicit targeting happens when the user specifies a device group name, for example, "Alexa, turn on the living room lights." Implicit targeting happens when the user doesn't specify the group name. For example, if a user says, "Alexa, turn on the lights" to a device that's in a device group, Alexa turns on all lights in the group. Devices in a device group are typically located in the same physical space, but this isn't a requirement.
API endpoints
Based on the country of your organization, set the Host
parameter in the request header to one of the following API endpoints.
Country | Endpoint |
---|---|
CA, US |
|
DE, ES, FR, IT, UK |
|
JP |
|
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.
Operations
The Device Group API includes the following operations.
Operation | HTTP Method and URI |
---|---|
| |
| |
| |
| |
| |
|
Add device to device group
Add a device to an existing device group. You can add one device at a time.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To add a device, you make a POST
request to the /v1/deviceGroups
resource.
Request path and header example
POST /v1/deviceGroups/{id}/memberDevices HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies an existing device group. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"memberDevice": {
"id": "amzn1.alexa.endpoint.2"
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Endpoint to add to the device group.
|
Object |
Yes |
|
Unique ID for the endpoint. |
String |
Yes |
Response
A successful response returns HTTP 204 No Content
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Endpoint added to the device group successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Change friendly name of group
Change the friendly name of the device group.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To change the friendly name, you make a POST
request to the /v1/deviceGroups/{id}/friendlyName
resource.
Request path and header example
POST /v1/deviceGroups/{id}/friendlyName HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies an existing device group. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"type": "PLAIN",
"value": {
"text": "entryway"
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Format of the value field. Currently, the only supported type is plain text. |
String |
Yes |
|
Describes the name. |
Object |
Yes |
|
Friendly name given in plain text.
Names must contain at least one number or letter. |
String |
Yes |
Response
A successful response returns HTTP 204 No Content
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Friendly name changed successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Create device group
Create a new device group. You can add devices to the group with this operation, or you can add them later with the Add device to device group operation.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To create a device group, you make a POST
request to the /v1/deviceGroups
resource.
Request path and header example
POST /v1/deviceGroups HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"friendlyName": {
"type": "PLAIN",
"value": {
"text": "kitchen"
}
},
"memberDevices": [{
"id": "amzn1.alexa.endpoint.1"
}],
"associatedUnits": [{
"id": "amzn1.alexa.unit.did.101"
}]
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Name of the device group. |
|
Yes |
|
List of endpoints in the group.
|
Array of objects |
No |
|
Unique ID for the endpoint that Amazon assigns to each customer device. |
String |
No |
|
List of units to associate with the device group.
|
Array of objects |
Yes |
|
Unique ID for the unit. |
String |
Yes |
Response
A successful response returns HTTP 201 Created
, along with the device group identifier.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The following example shows a response.
{
"id": "amzn1.alexa.endpointGroup.1"
}
Response body properties
Property | Description | Type |
---|---|---|
|
Identifies the new device group. |
String |
HTTP status codes
Status | Description |
---|---|
|
Device group created successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Delete device group
Delete the specified device group. This operation removes all member devices and associated units from the device group upon deletion, but the groups and units continue to exist.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To remove a device group, you make a DELETE
request to the /v1/deviceGroups/{id}
resource.
Request path and header example
DELETE /v1/deviceGroups/{id} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies an existing device group. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 204 No Content
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Device group deleted successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List device groups
Get a list of device groups for the specified unit.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To list device groups, you make a GET
request to the /v1/deviceGroups
resource.
Request path and header example
GET /v1/deviceGroups?associatedUnits.id={unitId}&expand=all&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Query |
Unique ID for the unit. |
String |
Yes |
|
Query |
Return details of the device group, including friendly name and group members. |
String |
No |
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
Query |
Token from the previous response. |
String |
No |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with a list of groups defined for the specified unit.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body examples
Response body properties
Property | Description | Type |
---|---|---|
|
List of device groups associated with the specified unit. |
Array of objects |
|
Identifies a device group associated with the unit. |
Object |
|
Identifies the device group. |
String |
|
(Optional) Name of the device group. |
|
|
(Optional) List of endpoints that are members of the group. |
List of objects |
|
Unique ID for the member device. |
String |
|
(Optional) List of units to associate with the device group. |
List of objects |
|
Unique ID for the unit. |
String |
|
(Optional) Indicates whether there are more results to return. |
Object |
|
Included when the response is truncated. Use this value in a subsequent request. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains a list of device groups for the unit. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Remove device from group
Remove the specified device from a device group.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To remove a device from a group, you make a DELETE
request to the /v1/deviceGroups/{id}/memberDevices/
resource.
Request path and header example
DELETE /v1/deviceGroups/{id}/memberDevices/{endpointId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies an existing device group. |
String |
Yes |
|
Path |
Identifies the device to remove from the group. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 204 No Content
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Endpoint deleted from the specified device group successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Object definitions
The Device Group API defines the following object definitions.
NameValue object
The NameValue
object is a container for names of objects.
The following table defines the properties of the object.
Property | Description | Type |
---|---|---|
|
Format of the value field. At this time, the only supported type is plain text. |
String |
|
Name. |
Object |
|
Name given in plain text. |
String |
Related topics
- Endpoints REST API Reference
- Get Started with Alexa Smart Properties APIs
- Alexa Smart Properties REST API Reference
- About Alexa Smart Properties
Last updated: Sep 09, 2024