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 smart home 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 an Alexa Built-in device 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

https://api.amazonalexa.com

DE, ES, FR, IT, UK

https://api.eu.amazonalexa.com

JP

https://api.fe.amazonalexa.com

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

POST /v1/deviceGroups/{id}/memberDevices

Change friendly name of group

POST /v1/deviceGroups/{id}/friendlyName

Create device group

POST /v1/deviceGroups

Delete device group

DELETE /v1/deviceGroups/{id}

List device groups

GET /v1/deviceGroups?associatedUnits.id={unitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1

Remove device from group

DELETE /v1/deviceGroups/{id}/memberDevices/{endpointId}

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

Copied to clipboard.

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

id

Path

Identifies an existing device group.
Formatted as amzn1.alexa.endpointGroup.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "memberDevice": {
        "id": "amzn1.alexa.endpoint.2"
    }
}

Request body properties

Property Description Type Required

memberDevices

Endpoint to add to the device group.

  • The endpoint must exist, and the caller must have access to it.
  • The endpoint must be associated with the same unit as the device group.
  • You can add an Alexa-enabled endpoint to one device group only.
  • You can add a smart home endpoint to more than one device group. Amazon considers smart home endpoints to be devices that aren't Amazon Echo devices.

Object

Yes

memberDevices.id

Unique ID for the endpoint.
Formatted as an Amazon Common Identifier (ACI), amzn1.alexa.endpoint.{id}.

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 object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Endpoint added to the device group successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

id

Path

Identifies an existing device group.
Formatted as amzn1.alexa.endpointGroup.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

Copied to clipboard.

{
  "type": "PLAIN",
  "value": {
    "text": "entryway"
  }
}

Request body properties

Property Description Type Required

type

Format of the value field. Currently, the only supported type is plain text.
Valid values: PLAIN.

String

Yes

value

Describes the name.

Object

Yes

value.text

Friendly name given in plain text. Names must contain at least one number or letter.
Valid values: 1–128 Unicode (UTF-8) characters.
Characters must be numbers, letters, spaces, or apostrophes. You can use Chinese characters and non-Roman letters. No other special characters or punctuation allowed.

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 object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Friendly name changed successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

Copied to clipboard.

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

friendlyName

Name of the device group.
All device groups within the same unit must have unique names.

NameValue object

Yes

memberDevices

List of endpoints in the group.

  • All endpoints in the list must exist, and the caller must have access to them.
  • All endpoints in the list must be associated with the same unit as the new device group.
  • You can add an Alexa-enabled endpoint to one device group only.
  • You can add a smart home endpoint to more than one device group. Amazon considers smart home endpoints to be devices that aren't Amazon Echo devices
  • The list can be empty.

Array of objects

No

memberDevices[].id

Unique ID for the endpoint that Amazon assigns to each customer device.
Formatted as an Amazon Common Identifier (ACI), amzn1.alexa.endpoint.{id}.

String

No

associatedUnits

List of units to associate with the device group.

  • At this time, you can associate a group with one unit.
  • The unit must exist, and the caller must have access to the unit.
  • After you create the device group, you can't add a unit to the group.

Array of objects

Yes

associatedUnits[].id

Unique ID for the unit.
Formatted as an Amazon Common Identifier (ACI), unit.did.{id}.

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 object.

Response body example

The following example shows a response.

{
    "id": "amzn1.alexa.endpointGroup.1"
}

Response body properties

Property Description Type

id

Identifies the new device group.
Formatted as amzn1.alexa.endpointGroup.{id}.

String

HTTP status codes

Status Description

201 Created

Device group created successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

id

Path

Identifies an existing device group.
Formatted as amzn1.alexa.endpointGroup.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

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 object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Device group deleted successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

unitId

Query

Unique ID for the unit.
Formatted as an Amazon Common Identifier (ACI), unit.did.{id}.

String

Yes

expand

Query

Return details of the device group, including friendly name and group members.
Valid value: all.

String

No

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–50. Default: 10.

Integer

No

nextToken

Query

Token from the previous response.
Include if iterating over a paginated response.

String

No

access token

Header

Access token for the customer.
Set to an LWA token.

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 object.

Response body examples

Response body properties

Property Description Type

results

List of device groups associated with the specified unit.
If no groups defined, this list is empty.

Array of objects

results[].deviceGroup

Identifies a device group associated with the unit.

Object

results[].deviceGroup.id

Identifies the device group.
Formatted as amzn1.alexa.endpointGroup.{id}.

String

results[].deviceGroup.friendlyName

(Optional) Name of the device group.
All device groups within the same unit have unique names.

NameValue object

results[].deviceGroup.memberDevices

(Optional) List of endpoints that are members of the group.

List of objects

results[].deviceGroup.memberDevices[].id

Unique ID for the member device.
Formatted as an Amazon Common Identifier (ACI), amzn1.alexa.endpoint.{id}.

String

results[].deviceGroup.associatedUnits

(Optional) List of units to associate with the device group.
At this time, you can associate a group with one unit.

List of objects

results[].deviceGroup.associatedUnits[].id

Unique ID for the unit.
Formatted as an Amazon Common Identifier (ACI), unit.did.{id}.

String

paginationContext

(Optional) Indicates whether there are more results to return.
For details, see Handling Pagination in Query Results

Object

paginationContext.nextToken

Included when the response is truncated. Use this value in a subsequent request.

String

HTTP status codes

Status Description

200 OK

Response body contains a list of device groups for the unit.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

id

Path

Identifies an existing device group.
Formatted as amzn1.alexa.endpointGroup.{id}.

String

Yes

endpointId

Path

Identifies the device to remove from the group.
Formatted as an Amazon Common Identifier (ACI), amzn1.alexa.endpoint.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

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 object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Endpoint deleted from the specified device group successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

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.

Error object

The Error object defines the error type and message included in the response when an error occurs.

The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}
Property Description Type

type

Type of error that occurred.
For specific error types, see the HTTP status code table for each operation.

String

message

The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message..

String

NameValue object

The NameValue object is a container for names of objects.

The following table defines the properties of the object.

Property Description Type

type

Format of the value field. At this time, the only supported type is plain text.
Valid values: PLAIN.

String

value

Name.

Object

value.text

Name given in plain text.

String

Was this page helpful?

Last updated: Oct 30, 2024