Device Group Management API

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.

In Alexa Smart Properties, you can use the Device Group Management API to create groups of devices within a unit.

API endpoint

In the request header, set Host to one of the following, depending on the region of your organization:

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

Operations

The Device Group API includes the following operations.

Create a device group

Call POST /v1/deviceGroups to create a device group.

This operation is available in the following countries.

Request format

POST /v1/deviceGroups HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

None.

Request body format

{
  "friendlyName": {
    "type": "PLAIN",
    "value": {
      "text": "{groupFriendlyName}"
    }
  },
  "memberDevices": [
    {
      "id": "amzn1.alexa.endpoint.{endpointId}"
    }
  ],
  "associatedUnits": [
    {
      "id": "amzn1.alexa.unit.did.{UnitId}"
    }
  ]
}

Request body example

{
  "friendlyName": {
    "type": "PLAIN",
    "value": {
      "text": "kitchen"
    }
  },
  "memberDevices": [
    {
      "id": "amzn1.alexa.endpoint.es2fiL0v9nOJlfYf5Raw7Ff90bv7tAJkie3p3Zzf4C7svpIEL4GcGh8lQdBbYWIjqfA2ydFEvzy_kG3QBOg2MRUBDR0StBHCwNombp4-2N7SY8H1JCQxKO0mKO1Ez5VX3QPItZ26rEvnqpjjday41DZ0lz4lNZAHpoc0GuvX6M4uRKO9wFuTklf7XZf1EOiRLyKQg0rPBE1V7epjFqVRKtAZluxMmZkCgQJ30Mwt4MxQFmha-Ypfm0s2vzpXqe6"
    }
  ],
  "associatedUnits": [
    {
      "id": "amzn1.alexa.unit.did.7R9ITXF3SHFHJDGQYSAXJ9C7E78CA2DD3C1NM2RN70BSELVVZ1EDZZC4KVQ6GLZ72W0QXDIQ49RT5CMPU91DW6ZTSKA6HPQI3LAPZYMY"
    }
  ]
}

Request body parameters

NameValue object

Value object

Endpoint object

DeviceGroup object

Unit object

Success response header

HTTP/1.1 201 Created
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

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

Response body parameters

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

Add a device to a device group

Call POST /v1/deviceGroups/{id}/memberDevices to add a device to a device group.

This operation is available in the following countries.

Request format

POST /v1/deviceGroups/{id}/memberDevices HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body format

{
    "memberDevice": {
      "id": "{endpointId}"
    }
}

Request body example

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

Request body parameters

Success response header

HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

Remove a device from a device group

Call DELETE /v1/deviceGroups/{id}/memberDevices/{endpointId} to remove a device from a device group.

This operation is available in the following countries.

Request format

DELETE /v1/deviceGroups/{id}/memberDevices/{endpointId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Success response header

HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

Change a device group's friendly name

Call POST /v1/deviceGroups/{id}/friendlyName to change a device group's friendly name.

This operation is available in the following countries.

Request format

POST /v1/deviceGroups/{id}/friendlyName HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body format

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

Request body example

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

Request body parameters

Success response header

HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

Delete a device group

Call DELETE /v1/deviceGroups/{id} to delete a device group. All member devices and associated units are removed from the device group upon deletion, but they continue to exist.

This operation is available in the following countries.

Request format

DELETE /v1/deviceGroups/{id}  HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Success response header

HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

List device groups

Call GET /v1/deviceGroups to retrieve a list of device groups.

This operation is available in the following countries.

Request format

GET /v1/deviceGroups?associatedUnits.id={UnitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

None.

Request and response examples

The following examples show how to use this call.

Include only default information

This example shows how to include only default information for each device group.

Following is the request:

GET /v1/deviceGroups?associatedUnits.id=amzn1.alexa.unit.did.KOHSO00IAQYD6S0W5GWBKF1U2JQFDK1GHAJFNPAK4MTCHO0VJNMTJQOQVOVHMOUW4CW5XM0TC4LDRKBA1NLOS6EKPAXDD5AVEY3E5QVN HTTP/1.1

Following is the response:

HTTP/1.1 200 OK

{
  "paginationContext": {
    "nextToken": null
  },
  "results": [
    {
      "deviceGroup": {
        "id": "amzn1.alexa.endpointGroup.kMbAbfF9JTDyE7c8Tg2DzBOWhzAmLMq4MZwlbjGJ9rZ8QPm6bmbKPijbwoziWof5SzbBHWu7LOBa6z2N6mB64g"
      }
    }
  ]
}

Include details for each device group

This example shows how to include details for each device group by using the expand=all parameter.

Following is the request:

GET /v1/deviceGroups?associatedUnits.id=amzn1.alexa.unit.did.GMCCVDN5EIN4PBFQMNRHT7U6H4RDMXNEYAIHYX4C1IVX3RARAEAZJU1KMAC74VFK00TPD0PWWITP991M4E6UE14KW2Q4BGM0X0PEMEHD&expand=all HTTP/1.1

Following is the response:

HTTP/1.1 200 OK

{
  "paginationContext": {
    "nextToken": null
  },
  "results": [
    {
      "deviceGroup": {
        "id": "amzn1.alexa.endpointGroup.kMbAbfF9JTDyE7c8Tg2DzBOWhzAmLMq4MZwlbjGJ9rZ8QPm6bmbKPijbwoziWof5SzbBHWu7LOBa6z2N6mB64g",
        "friendlyName": {
          "type": "PLAIN",       
          "value": {
            "text": "kitchen"
          }
        },
        "memberDevices": [
          {
            "id": "amzn1.alexa.endpoint.BmX5E58b3nEKsmwSwKs6NofAP9eNe3jFs9C5aa3Ui49CAnpmkwKiZ58OhdPrsMVzxjZkgn5TWrFioHkACNhAmNKximBGWTpfBzh1IpJIR14b0gfT83evGBCvMBf0HpAz9HEzBqnToo1NnSjBGUqpiFUr8FfrCa26bNYdqhsIZ8aNlOdmb8UK4dT2tQnYn52MFP9x4lkfGsXN93YIaI3ur42GxuvO5CFOBgJ8ALPf7UDCMadoZ3WM3db2cZ2EW92"
          }
        ],
        "associatedUnits": [
          {
            "id": "amzn1.alexa.unit.did.7RBKKY0AGCGS9WWGNGG6QLFJQ2U6XADPWRQCS15O7DWNO62U0AAHYF5B79I018JMGLFWQTRUHTGSI7BA7A9CEOD929TBP253R82V03R3"
          }
        ]
      }
    }
  ]
}

Request query parameters

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body parameters

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

Related topics

• Get Started with Alexa Smart Properties APIs
• REST API Reference
• About Alexa Smart Properties

Last updated: Feb 05, 2024