Endpoint API

An endpoint represents an Alexa-connected device (like an Echo device) with which an Alexa customer can interact. In Alexa Smart Properties for hospitality, you manage your Echo devices using the Alexa Smart Properties for hospitality endpoint API. With this API, you can enumerate the devices owned by your Amazon Business account; view and change settings; and associate endpoints with specific rooms.

API endpoint

The endpoint of the Endpoint API is https://api.amazonalexa.com for North America properties or https://api.eu.amazonalexa.com for EU properties.

Authentication

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

Operations

The Endpoint API includes the following operations.

Get endpoints

The following operations enable you to get information about endpoints.

Get all endpoints

Gets the list of endpoints that you registered to your Amazon Business account.

This operation is available in the following countries.

Request

Call GET /v2/endpoints?owner=~caller to get the list of endpoints that you registered to your Amazon Business account.

Request format examples

Get all endpoints that aren't associated with a unit

The following example lists the endpoints owned by the caller that aren't associated with a unit. By default, the results aren't expanded.

This call only returns endpoints that are not associated with any units. To get all endpoints associated with a specific unit, see Get all endpoints associated with a unit.

GET /v2/endpoints?owner=~caller HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Response body example

{
   "results": [
      {
         "id": "amzn1.alexa.endpoint.A234ajd9..."
      },
      {
         "id": "amzn1.alexa.endpoint.X35as24a..."
      }
   ],
   "paginationContext": {
        "nextToken": "ABCD123"
   }
}

Include details for each endpoint

This example shows how to include details for each endpoint, use the following expand=all parameter.

GET /v2/endpoints?owner=~caller&expand=all HTTP/1.1

Response body example

{
   "results":[
      {
         "id":"amzn1.alexa.endpoint.A234ajd9...",
         "friendlyName":{
            "type":"PLAIN",
            "value":{
               "text":"Test's Echo"
            }
         },
         "manufacturer":{
            "type":"PLAIN",
            "value":{
               "text":"Amazon"
            }
         },
         "model":{
            "type":"PLAIN",
            "value":{
               "text":"Echo Dot (3rd generation)"
            }
         },
         "serialNumber":{
            "type":"PLAIN",
            "value":{
               "text":"Z0F0d0M5R7UBSNWT"
            }
         },
         "softwareVersion":{
            "type":"PLAIN",
            "value":{
               "text":"1"
            }
         },
         "connections":[
            {
               "type":"TCP_IP",
               "macAddress":"FE7SD227F2AC"
            }
         ],
         "creationTime": "2021-11-11T06:48:16Z",
         "features":[
            {
               "name":"speaker",
               "path":"/v2/endpoints/{endpointID}/features/speaker"
            },
            {
               "name":"connectivity",
               "path":"/v2/endpoints/{endpointID}/features/connectivity"
            }
         ],
         "associatedUnits": [
            {
               "id":"amzn1.alexa.unit.did.unitOne"
            }
         ],
         "operations": [
            {
               "name": "deregister",
               "path": "/v2/endpoints/{endpointID}/deregister"
            }
         ],
         "displayCategories": {
            "primary": {
               "value": "ALEXA_VOICE_ENABLED",
               "sources": [
                  "ENDPOINT_REPORTER"
               ]
            },
            "all": [
               {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               }
            ]
         }
      },
      {
         "id":"amzn1.alexa.endpoint.X35as24a...",
         "friendlyName":{
            "type":"PLAIN",
            "value":"Another Test's Echo"
         },
         "manufacturer":{
            "type":"PLAIN",
            "value":{
               "text":"Amazon"
            }
         },
         "model":{
            "type":"PLAIN",
            "value":{
               "text":"Echo Dot (3rd generation)"
            }
         },
         "serialNumber":{
            "type":"PLAIN",
            "value":{
               "text":"ABC0d0M5R7UBSDFG"
            }
         },
         "softwareVersion":{
            "type":"PLAIN",
            "value":{
               "text":"1"
            }
         },
         "connections":[
            {
               "type":"TCP_IP",
               "macAddress":"DGSD227D2AB"
            }
         ],
         "creationTime": "2021-11-11T06:48:16Z",
         "features":[
            {
               "name":"speaker",
               "path":"/v2/endpoints/{endpointID}/features/speaker"
            },
            {
               "name":"connectivity",
               "path":"/v2/endpoints/{endpointID}/features/connectivity"
            }
         ],
         "associatedUnits": [
            {
               "id":"amzn1.alexa.unit.did.unitOne"
            }
         ],
         "operations": [
            {
               "name": "deregister",
               "path": "/v2/endpoints/{endpointID}/deregister"
            }
         ],
         "displayCategories": {
            "primary": {
               "value": "ALEXA_VOICE_ENABLED",
               "sources": [
                  "ENDPOINT_REPORTER"
               ]
            },
            "all": [
               {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               }
            ]
         }
      }
  ],
  "paginationContext":{
     "nextToken":"ABCD123"
  }
}

Include connectivity for each endpoint

To include connectivity details for each endpoint, use the following expand=feature:connectivity parameter.

GET /v2/endpoints?owner=~caller&expand=all&expand=feature:connectivity

Response body example

{
     "results": [
         {
             "id": "amzn1.alexa.endpoint.A234ajd9...",
             "friendlyName": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Test's Echo"
                 }
             },
             "manufacturer": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Amazon"
                 }
             },
             "model": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Echo Dot (3rd generation)"
                 }
             },
             "serialNumber": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Z0F0d0M5R7UBSNWT"
                 }
             },
             "softwareVersion": {
                 "type": "PLAIN",
                 "value": {
                     "text": "1"
                 }
             },
             "connections": [
                 {
                     "type": "TCP_IP",
                     "macAddress": "FE7SD227F2AC"
                 }
             ],
             "creationTime": "2021-11-11T06:48:16Z",
             "features": [
                {
                    "name": "speaker",
                    "path": "/v2/endpoints/{endpointID}/features/speaker"
                },
                {
                    "name": "connectivity",
                    "properties": [
                       {
                           "name": "reachability",
                           "type": "RETRIEVABLE",
                           "value": {
                               "value": "OK"
                           },
                           "timeOfSample": "2020-08-30T18:22:15.295Z"
                       }
                   ]
                }
            ],
            "associatedUnits": [
               {
                  "id":"amzn1.alexa.unit.did.unitOne"
               }
            ],
            "operations": [
              {
                  "name": "deregister",
                  "path": "/v2/endpoints/{endpointID}/deregister"
               }
            ],
            "displayCategories": {
               "primary": {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               },
               "all": [
                  {
                     "value": "ALEXA_VOICE_ENABLED",
                     "sources": [
                        "ENDPOINT_REPORTER"
                     ]
                  }
               ]
            }
         },
         {
             "id": "amzn1.alexa.endpoint.X35as24a...",
             "friendlyName": {
                 "type": "PLAIN",
                 "value": "Another Test's Echo"
             },
             "manufacturer": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Amazon"
                 }
             },
             "model": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Echo Dot (3rd generation)"
                 }
             },
             "serialNumber": {
                 "type": "PLAIN",
                 "value": {
                     "text": "ABC0d0M5R7UBSDFG"
                 }
             },
             "softwareVersion": {
                 "type": "PLAIN",
                 "value": {
                     "text": "1"
                 }
             },
             "connections": [
                 {
                     "type": "TCP_IP",
                     "macAddress": "DGSD227D2AB"
                 }
             ],
             "creationTime": "2021-11-11T06:48:16Z",
             "features": [
                 {
                     "name": "speaker",
                     "path": "/v2/endpoints/{endpointID}/features/speaker"
                 },
                 {
                     "name": "connectivity",
                     "properties": [
                        {
                            "name": "reachability",
                            "type": "RETRIEVABLE",
                            "value": {
                                "value": "UNREACHABLE"
                            },
                            "timeOfSample": "2020-08-30T18:22:15.295Z"
                        }
                    ]
                 }
             ],
             "associatedUnits": [
                {
                   "id":"amzn1.alexa.unit.did.unitOne"
                }
             ],
             "operations": [
                 {
                     "name": "deregister",
                     "path": "/v2/endpoints/{endpointID}/deregister"
                 }
             ],
             "displayCategories": {
               "primary": {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               },
               "all": [
                  {
                     "value": "ALEXA_VOICE_ENABLED",
                     "sources": [
                        "ENDPOINT_REPORTER"
                     ]
                  }
               ]
            }
         }
     ],
     "paginationContext": {
         "nextToken": "ABCD123"
     }
}

Get all endpoints associated with a unit

To get all endpoints associated with a particular unitId that the caller has permission to access, provide the associatedUnits.id={unitId} parameter.

GET /v2/endpoints?associatedUnits.id={unitId}&expand=all

Response body example

{
   "results":[
      {
         "id":"amzn1.alexa.endpoint.A234ajd9...",
         "friendlyName":{
            "type":"PLAIN",
            "value": {
               "text":"Test's Echo"
            }
         },
         "manufacturer":{
            "type":"PLAIN",
            "value": {
                "text": "Amazon"
            }
         },
         "model":{
            "type":"PLAIN",
            "value": {
                "text":"Echo Dot (3rd generation)"
            }
         },
         "serialNumber":{
            "type":"PLAIN",
            "value": {
                "text":"Z0F0d0M5R7UBSNWT"
            }
         },
         "softwareVersion":{
            "type":"PLAIN",
            "value": {
                "text":"1"
            }
         },
         "connections":[
            {
               "type":"TCP_IP",
               "macAddress":"FE7SD227F2AC"
            }
         ],
         "creationTime": "2021-11-11T06:48:16Z",
         "features":[
            {
               "name":"speaker",
               "path":"/v2/endpoints/{endpointID}/features/speaker"
            },
            {
               "name":"connectivity",
               "path":"/v2/endpoints/{endpointID}/features/connectivity"
            }
         ],
         "associatedUnits":[
            {
               "id":"amzn1.alexa.unit.did.unitOne"
            }
         ],
         "operations": [
            {
               "name": "deregister",
               "path": "/v2/endpoints/{endpointID}/deregister"
            }
         ],
         "displayCategories": {
            "primary": {
               "value": "ALEXA_VOICE_ENABLED",
               "sources": [
                  "ENDPOINT_REPORTER"
               ]
            },
            "all": [
               {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               }
            ]
         }
      }
}

Request query parameters

Response header

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

Response body parameters

NameValue object

Example

"model": {
    "type": "PLAIN",
    "value": {
        "text":"Amazon Echo"
    }

Value object

Connection object

Example

{
  "type": "TCP_IP",
  "macAddress": "141AC1534151"
}

Feature object

Example

{
    "name": "speaker",
    "path" : "/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/speaker"
}

Unit object

Example

{
  "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
}

Display categories object

Example

"displayCategories": {
   "primary": {
      "value": "ALEXA_VOICE_ENABLED",
      "sources": [
         "ENDPOINT_REPORTER"
      ]
   },
   "all": [
      {
         "value": "ALEXA_VOICE_ENABLED",
         "sources": [
            "ENDPOINT_REPORTER"
         ]
      }
   ]
}

Display category object

Example

{
  "value": "LIGHT",
  "sources": ["CUSTOMER", "ENDPOINT_REPORTER"]
}

Pagination context object

Example

{
  "nextToken": "ABCD123"
}

Error response

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

Error response parameters

HTTP response codes

Get an endpoint

Gets an endpoint and list values for all endpoint attributes the caller has permission to access.

The caller must have access to the endpoint. This request doesn't require filtering parameters such as owner.

This operation is available in the following countries.

Request

Call GET /v2/endpoints/{endpointId}?expand=all to retrieve an endpoint and list values for all endpoint attributes the caller has permission to access.

Request format examples

The following examples show how to use this call.

List endpoint ID only

The following example lists only the endpoint ID for the endpoint.

GET /v2/endpoints/{endpointId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

{
    "id": "amzn1.alexa.endpoint.A234ajd9..."
}

List all attributes

The following example lists all the endpoint's attributes.

GET /v2/endpoints/{endpointId}?expand=all HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Response body example

{
   "id":"amzn1.alexa.endpoint.ABC123...",
   "friendlyName":{
      "type":"PLAIN",
      "value":{
         "text":"white echo"
      }
   },
   "manufacturer":{
      "type":"PLAIN",
      "value":{
         "text":"Amazon"
      }
   },
   "model":{
      "type":"PLAIN",
      "value":{
         "text":"Echo Dot (3rd generation)"
      }
   },
   "serialNumber":{
      "type":"PLAIN",
      "value":{
         "text":"G0922M09951706JS"
      }
   },
   "softwareVersion":{
      "type":"PLAIN",
      "value":{
         "text":"4262172036"
      }
   },
   "connections":[
      {
         "type":"TCP_IP",
         "macAddress":"141AC1534151"
      }
   ],
   "associatedUnits":[
      {
         "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
      }
   ],
   "creationTime": "2021-11-11T06:48:16Z",
   "features":[
      {
         "name":"speaker",
         "path":"/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/speaker"
      },
      {
         "name":"connectivity",
         "path":"/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/connectivity"
      }
   ],
   "operations":[
      {
         "name":"deregister",
         "path":"/v2/endpoints/amzn1.alexa.endpoint.ABC123.../deregister"
      }
   ],
   "displayCategories": {
      "primary": {
         "value": "ALEXA_VOICE_ENABLED",
         "sources": [
            "ENDPOINT_REPORTER"
         ]
      },
      "all": [
         {
            "value": "ALEXA_VOICE_ENABLED",
            "sources": [
               "ENDPOINT_REPORTER"
            ]
         }
      ]
   }
}

List all attributes and speaker feature

The following example lists all the endpoint's attributes and the speaker feature.

GET /v2/endpoints/{endpointId}?expand=all&expand=feature:speaker HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Response body example

{
   "id":"amzn1.alexa.endpoint.ABC123...",
   "friendlyName":{
      "type":"PLAIN",
      "value":{
         "text":"white echo"
      }
   },
   "manufacturer":{
      "type":"PLAIN",
      "value":{
         "text":"Amazon"
      }
   },
   "model":{
      "type":"PLAIN",
      "value":{
         "text":"Echo Dot (3rd generation)"
      }
   },
   "serialNumber":{
      "type":"PLAIN",
      "value":{
         "text":"G0922M09951706JS"
      }
   },
   "softwareVersion":{
      "type":"PLAIN",
      "value":{
         "text":"4262172036"
      }
   },
   "connections":[
      {
         "type":"TCP_IP",
         "macAddress":"141AC1534151"
      }
   ],
   "associatedUnits":[
      {
         "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
      }
   ],
   "creationTime": "2021-11-11T06:48:16Z",
   "features":[
        {
           "name": "speaker",
            "properties": [
                {
                    "name": "volume",
                    "type": "RETRIEVABLE",
                    "value": {
                        "value": 40
                    },
                    "timeOfSample": "2021-02-26T01:48:31.225Z"
                }
            ],
            "operations": [
                {
                    "name": "adjustVolume",
                    "path": "/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/speaker/adjustVolume"
                },
                {
                    "name": "setVolume",
                    "path": "/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/speaker/setVolume"
                }
            ]
      },
      {
         "name":"connectivity",
         "path":"/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/connectivity"
      }
   ],
   "operations":[
      {
         "name":"deregister",
         "path":"/v2/endpoints/amzn1.alexa.endpoint.ABC123.../deregister"
      }
   ],
   "displayCategories": {
      "primary": {
         "value": "ALEXA_VOICE_ENABLED",
         "sources": [
            "ENDPOINT_REPORTER"
         ]
      },
      "all": [
         {
            "value": "ALEXA_VOICE_ENABLED",
            "sources": [
               "ENDPOINT_REPORTER"
            ]
         }
      ]
   }
}

Request path parameters

Request query parameters

Response header

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

Query endpoints (advanced search)

Call POST /v2/endpointQuery to get a list of endpoints that meet the conditions that you specify. This operation supports queries by unit, manufacturer, and model.

You can construct the query with multiple AND or OR clauses. For example, you can search for endpoints that satisfy the following conditions: (unit ID = amzn1.alexa.unit.unitOne OR amzn1.alexa.unit.unitTwo) AND a manufacturer name of someManufacturer.

This operation is available in the following countries.

Request

To query endpoints, you make a POST request to the /v2/endpointQuery resource.

Request header example

POST /v2/endpointQuery HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Request body example

The following request queries endpoints in two units.

{
  "query": {
    "or": [
      {
        "match": {
          "associatedUnits.id": "amzn1.alexa.unit.did.unitOne"
        }
      },
      {
        "match": {
          "associatedUnits.id": "amzn1.alexa.unit.did.unitTwo"
        }
      }
    ]
  },
  "paginationContext": {
    "maxResults": 50,
    "nextToken": "WncIu8IrscO..."
  },
  "expand": [
    "all", "feature:connectivity"
  ]
}

The following request queries endpoints in two units, filtered by device manufacturer.

{
  "query": {
    "and": [
      {
        "or": [
          {
            "match": {
               "associatedUnits.id": "amzn1.alexa.unit.did.unitOne"
            }
          },
          {
            "match": {
               "associatedUnits.id": "amzn1.alexa.unit.did.unitTwo"
            }
          }
        ]
      },
      {
        "match": {
          "manufacturer.value.text": "Amazon"
        }
      }
    ]
  },
  "paginationContext": {
    "maxResults": 50,
    "nextToken": "WncIu8IrscO..."
  },
  "expand": [
    "all", "feature:power"
  ]
}

The following request queries endpoints in two units, filtered by device manufacturer and model.

{
  "query": {
    "and": [
      {
        "or": [
          {
            "match": {
               "associatedUnits.id": "amzn1.alexa.unit.did.unitOne"
            }
          },
          {
            "match": {
               "associatedUnits.id": "amzn1.alexa.unit.did.unitTwo"
            }
          }
        ]
      },
      {
        "match": {
          "manufacturer.value.text": "Amazon"
        }
      },
      {
        "match": {
          "model.value.text": "Echo Dot (3rd generation)"
        }
      }
    ]
  },
  "paginationContext": {
    "maxResults": 50,
    "nextToken": "WncIu8IrscO..."
  },
  "expand": [
    "all", "feature:power"
  ]
}

Request body parameters

Response

A successful response returns HTTP 200.

Response body example

The following example shows a result of using this operation with feature:connectivity in the expand array.

Response body example

{
     "results": [
         {
             "id": "amzn1.alexa.endpoint.A234ajd9...",
             "friendlyName": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Test's Echo"
                 }
             },
             "manufacturer": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Amazon"
                 }
             },
             "model": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Echo Dot (3rd generation)"
                 }
             },
             "serialNumber": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Z0F0d0M5R7UBSNWT"
                 }
             },
             "softwareVersion": {
                 "type": "PLAIN",
                 "value": {
                     "text": "1"
                 }
             },
             "connections": [
                 {
                     "type": "TCP_IP",
                     "macAddress": "FE7SD227F2AC"
                 }
             ],
             "creationTime": "2021-11-11T06:48:16Z",
             "features": [
                {
                    "name": "speaker",
                    "path": "/v2/endpoints/{endpointID}/features/speaker"
                },
                {
                    "name": "connectivity",
                    "properties": [
                       {
                           "name": "reachability",
                           "type": "RETRIEVABLE",
                           "value": {
                               "value": "OK"
                           },
                           "timeOfSample": "2020-08-30T18:22:15.295Z"
                       }
                   ]
                }
            ],
            "associatedUnits": [
               {
                  "id":"amzn1.alexa.unit.did.unitOne"
               }
            ],
            "operations": [
              {
                  "name": "deregister",
                  "path": "/v2/endpoints/{endpointID}/deregister"
               }
            ],
            "displayCategories": {
               "primary": {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               },
               "all": [
                  {
                     "value": "ALEXA_VOICE_ENABLED",
                     "sources": [
                        "ENDPOINT_REPORTER"
                     ]
                  }
               ]
            }
         },
         {
             "id": "amzn1.alexa.endpoint.X35as24a...",
             "friendlyName": {
                 "type": "PLAIN",
                 "value": "Another Test's Echo"
             },
             "manufacturer": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Amazon"
                 }
             },
             "model": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Echo Dot (3rd generation)"
                 }
             },
             "serialNumber": {
                 "type": "PLAIN",
                 "value": {
                     "text": "ABC0d0M5R7UBSDFG"
                 }
             },
             "softwareVersion": {
                 "type": "PLAIN",
                 "value": {
                     "text": "1"
                 }
             },
             "connections": [
                 {
                     "type": "TCP_IP",
                     "macAddress": "DGSD227D2AB"
                 }
             ],
             "creationTime": "2021-11-11T06:48:16Z",
             "features": [
                 {
                     "name": "speaker",
                     "path": "/v2/endpoints/{endpointID}/features/speaker"
                 },
                 {
                     "name": "connectivity",
                     "properties": [
                        {
                            "name": "reachability",
                            "type": "RETRIEVABLE",
                            "value": {
                                "value": "UNREACHABLE"
                            },
                            "timeOfSample": "2020-08-30T18:22:15.295Z"
                        }
                    ]
                 }
             ],
             "associatedUnits": [
                {
                   "id":"amzn1.alexa.unit.did.unitOne"
                }
             ],
             "operations": [
                 {
                     "name": "deregister",
                     "path": "/v2/endpoints/{endpointID}/deregister"
                 }
             ],
             "displayCategories": {
               "primary": {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               },
               "all": [
                  {
                     "value": "ALEXA_VOICE_ENABLED",
                     "sources": [
                        "ENDPOINT_REPORTER"
                     ]
                  }
               ]
            }
         }
     ],
     "paginationContext": {
         "nextToken": "ABCD123"
     }
}

The following example shows a result of using this operation to find endpoints for the associatedUnits.id.

Response body example

{
   "results":[
      {
         "id":"amzn1.alexa.endpoint.A234ajd9...",
         "friendlyName":{
            "type":"PLAIN",
            "value": {
               "text":"Test's Echo"
            }
         },
         "manufacturer":{
            "type":"PLAIN",
            "value": {
                "text": "Amazon"
            }
         },
         "model":{
            "type":"PLAIN",
            "value": {
                "text":"Echo Dot (3rd generation)"
            }
         },
         "serialNumber":{
            "type":"PLAIN",
            "value": {
                "text":"Z0F0d0M5R7UBSNWT"
            }
         },
         "softwareVersion":{
            "type":"PLAIN",
            "value": {
                "text":"1"
            }
         },
         "connections":[
            {
               "type":"TCP_IP",
               "macAddress":"FE7SD227F2AC"
            }
         ],
         "creationTime": "2021-11-11T06:48:16Z",
         "features":[
            {
               "name":"speaker",
               "path":"/v2/endpoints/{endpointID}/features/speaker"
            },
            {
               "name":"connectivity",
               "path":"/v2/endpoints/{endpointID}/features/connectivity"
            }
         ],
         "associatedUnits":[
            {
               "id":"amzn1.alexa.unit.did.unitOne"
            }
         ],
         "operations": [
            {
               "name": "deregister",
               "path": "/v2/endpoints/{endpointID}/deregister"
            }
         ],
         "displayCategories": {
            "primary": {
               "value": "ALEXA_VOICE_ENABLED",
               "sources": [
                  "ENDPOINT_REPORTER"
               ]
            },
            "all": [
               {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               }
            ]
         }
      }
}

Response body parameters

HTTP status codes

Manage endpoint-to-unit association

PUT associatedUnits

Call PUT /v2/endpoints/{endpointId}/associatedUnits to update the list of associated units for an endpoint. You also use this API to disassociate endpoints from units.

Keep in mind the following important details:

• The endpoint must have an active connection when changing unit associations. Keep the device powered on and online for one minute after successfully calling this API.
• Currently, an endpoint can only be associated with one unit at a time.
• After you associate a device to a room, the friendly name of the device might change. For example, "Mary's device" might change to "Guest's device."
• To disassociate an endpoint from a room, call PUT /v2/endpoints/{endpointId}/associatedUnits, and specify your default unit wildcard "~caller.defaultUnitId".
• You should only apply settings after a device is associated with a unit. Any settings that have been applied to a device are cleared when its unit association is updated. After you call the PUT associatedUnits API and receive a 200 return code, you should confirm that the endpoint was successfully restarted. See Query the endpoint status.
• When you change unit associations for an endpoint, the endpointId might change. The new endpointId is returned in the response.

This operation is available in the following countries.

Request format

PUT /v2/endpoints/{endpointId}/associatedUnits HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body

[
  {
    "id": "amzn1.alexa.unit.did.{id}"
  }
]

Request body using default unit ID wildcard

[
  {
    "id": "~caller.defaultUnitId"
  }
]

Request body parameters

Response header

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

Response body

{
    "endpoint": {
        "id": "amzn1.alexa.endpoint.ABC123...",
        "associatedUnits": [{
            "id": "amzn1.alexa.unit.did.ZXY987..."
        }]
    }
}

Response body parameters

Error response

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

Error response parameters

HTTP response codes

Query the endpoint status

After you've called the PUT associatedUnits API and received a 200 code, the process to associate the endpoint with the unit is complete on the cloud side. However, the physical endpoint must complete an automatic reboot to complete the endpoint-to-unit association on the endpoint side. There are no steps required to automatically reboot the endpoint.

To check if the endpoint has successfully rebooted, you can poll for the connectivity status of the endpoint. We recommend a polling interval of 2 minutes or greater.

When this API returns an endpointId, the endpoint has successfully rebooted and reconnected to the network.

Request example

GET /v2/endpoints?associatedUnits.id=amzn1.alexa.unit.did.foo&connections.macAddress=00:11:22:AA:BB:33:44:55&features[name:connectivity].properties[name:reachability].value.value=OK HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Manage connectivity feature

GET features/connectivity

Call GET /v2/endpoints/{endpointId}/features/connectivity to get states and attributes related to connectivity of the endpoint.

This operation is available in the following countries.

Request format

GET /v2/endpoints/{endpointId}/features/connectivity  HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Response header

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

Response body example

{
    "properties": [
        {
            "name": "reachability",
            "type": "RETRIEVABLE",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2020-07-20T00:00:00Z"
        }
    ]
}

Response body parameters

Error response

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

Error response parameters

HTTP response codes

Manage Wi-Fi settings

Manage Wi-Fi configuration for Alexa endpoints and track status. To use these requests, you'll need an LWA token with "credential_locker::wifi_management" and "alexa::enterprise:management" scopes.

POST saveWifiConfigurations

Call POST /credentiallocker/v2/saveWifiConfigurations to save Wi-Fi configurations for later use with an endpoint.

This operation is available in the following countries.

Request format

POST /credentiallocker/v2/saveWifiConfigurations HTTP/1.1
Host: credential-locker-service.amazon.com
x-amz-access-token: {LWA Token}
Content-Type: application/json
Authorization: Bearer {LWA Token}

Request body format

{
    "wifiConfigurations": [{
        "credentialConfiguration": {
            "privateSharedKey": "\"wifi-password\""
        },
        "ssid": "\"wifi-ssid\"",
        "keyManagement": "WPAPSK"
    }]
}

Request body parameters

HTTP response codes

POST addOrUpdateWifiConfigurations

Call POST /v2/endpoints/endpointId/features/connectivity/addOrUpdateWifiConfigurations to associate saved Wi-Fi configurations with an endpoint. You can associate up to 32 Wi-Fi configurations with each endpoint.

This operation is available in the following countries.

Request format

POST /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer {LWA Token}
Content-Type: application/json

Request path parameters

Request body format

{
    "payload": {
        "wifiConfigurations": [{
            "ssid": "\"wifi-ssid\"",
            "keyManagement": "WPAPSK"
        }]
    }
}

Request body parameters

Response body format

{
     "submittedOperationId": "{operationId}"
}

Response body parameters

HTTP response codes

GET Wi-Fi installation status

Call GET /v2/endpoints/endpointId/features/connectivity/addOrUpdateWifiConfigurations/submittedOperations/{operationId} to get the status of an addOrUpdateWifiConfigurations operation.

This operation is available in the following countries.

Request format

GET /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations/submittedOperations/{operationId} HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer {LWA Token}

Request path parameters

Response body example

{
     "status": "TIMEOUT"
}

Response body parameters

Status object schema

HTTP response codes

Manage smart home features

GET features/color

Call GET /v2/endpoints/{endpointId}/features/color to get color properties and available operations for the specified endpoint. For color property details, see Capability Property Schemas.

This operation is available in the following countries.

Request format

GET /v2/endpoints/{endpointId}/features/color HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Success response header

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

Response body example

{
   "properties": [
      {
         "name": "color",
         "type": "RETRIEVABLE",
         "value": {
            "hue": 20,
            "saturation": 0.5,
            "brightness": 0.7
         },
         "timeOfSample": "1970-01-01T00:00:00Z"
      }
   ],
   "operations": [
      {
         "name": "setColor",
         "path": "/v2/endpoints/{id}/features/color/setColor"
      }
   ]
}

Partial success response body example

Following is an example showing the response returned when an error occurs during color property retrieval.

{
    "properties": [
        {
            "name": "color",
            "type": "ERROR",
            "error": {
                "type": "",
                "message": ""
            }
        }
    ],
    "operations": [
        {
            "name": "setColor",
            "path": "/v2/endpoints/{id}/features/color/setColor"
        }
    ]
}

Response body parameters

Property object schema

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

POST features/color

Call POST /v2/endpoints/{endpointId}/features/color/setColor to set color properties for the specified endpoint. For color property details, see Capability Property Schemas.

This operation is available in the following countries.

Request format

POST /v2/endpoints/{endpointId}/features/color/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body example for setColor

{
    "payload": {
        "color": {
            "hue": 20,
            "saturation": 0.75,
            "brightness": 0.34
        }
    }
}

Request body parameters for setColor

Success response header

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

Success response body

If the operation is completely successful, there is no response body.

Partial success response example

The HTTP/1.1 503 Service Unavailable response indicates that the request was sent successfully, but Alexa received an error response from the endpoint reporter. Examples of endpoint errors: the endpoint is offline, the endpoint battery level is too low, etc.

HTTP/1.1 503 Service Unavailable

{
    "type": "",
    "message": ""
}

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

GET features/brightness

Call GET /v2/endpoints/{endpointId}/features/brightness to get the brightness setting and available operations for the specified endpoint. For brightness property details, see Capability Property Schemas.

This operation is available in the following countries.

Request format

GET /v2/endpoints/{endpointId}/features/brightness HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Success response header

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

Response body example

{
   "properties": [
      {
         "name": "brightness",
         "type": "RETRIEVABLE",
         "value": {
            "value": 50
         },
         "timeOfSample": "1970-01-01T00:00:00Z"
      }
   ],
   "operations": [
       {
          "name": "setBrightness",
          "path": "/v2/endpoints/{id}/features/brightness/setBrightness"
       },
       {
          "name": "adjustBrightness",
          "path": "/v2/endpoints/{id}/features/brightness/adjustBrightness"
       }
   ]
}

Partial success response body example

Following is an example showing the response returned when an error occurs during brightness property retrieval.

{
    "properties": [
        {
            "name": "brightness",
            "type": "ERROR",
            "error": {
                "type": "",
                "message": ""
            }
        }
    ],
    "operations": [
        {
            "name": "setBrightness",
            "path": "/v2/endpoints/{id}/features/brightness/setBrightness"
        },
        {
            "name": "adjustBrightness",
            "path": "/v2/endpoints/{id}/features/brightness/adjustBrightness"
        }
    ]
}

Response body parameters

Property object schema

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

POST features/brightness

Call POST /v2/endpoints/{endpointId}/features/brightness/setBrightness to set the brightness level for the specified endpoint. Call POST /v2/endpoints/{endpointId}/features/brightness/adjustBrightness to change the brightness level for the specified endpoint by a specified amount.

For brightness property details, see Capability Property Schemas.

This operation is available in the following countries.

Request format

POST /v2/endpoints/{endpointId}/features/brightness/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body example for setBrightness

{
    "payload": {
        "brightness": 50
    }
}

Request body parameters for setBrightness

Request body example for adjustBrightness

{
    "payload": {
        "brightnessDelta": 10
    }
}

Request body parameters for adjustBrightness

Success response header

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

Success response body

If the operation is completely successful, there is no response body.

Partial success response example

The HTTP/1.1 503 Service Unavailable response indicates that the request was sent successfully, but Alexa received an error response from the endpoint reporter. Examples of endpoint errors: the endpoint is offline, the endpoint battery level is too low, etc.

HTTP/1.1 503 Service Unavailable

{
    "type": "",
    "message": ""
}

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

GET features/colorTemperature

Call GET /v2/endpoints/{endpointId}/features/colorTemperature to get color temperature properties and available operations for the specified endpoint.

This operation is available in the following countries.

Request format

GET /v2/endpoints/{endpointId}/features/colorTemperature HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Success response header

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

Response body example

{
   "properties": [
      {
         "name": "colorTemperatureInKelvin",
         "type": "RETRIEVABLE",
         "value": {
            "value": "2700"
         },
         "timeOfSample": "1970-01-01T00:00:00Z"
      }
   ],
   "operations": [
      {
          "name": "setColorTemperature",
          "path": "/v2/endpoints/{id}/features/colorTemperature/setColorTemperature"
      },
      {
         "name": "increaseColorTemperature",
         "path": "/v2/endpoints/{id}/features/colorTemperature/increaseColorTemperature"
      },
      {
         "name": "decreaseColorTemperature",
         "path": "/v2/endpoints/{id}/features/colorTemperature/decreaseColorTemperature"
      }
   ]
}

Partial success response body example

Following is an example showing the response returned when an error occurs during colorTemperature property retrieval.

{
    "properties": [
        {
            "name": "colorTemperatureInKelvin",
            "type": "ERROR",
            "error": {
                "type": "",
                "message": ""
            }
        }
    ],
    "operations": [
        {
            "name": "setColorTemperature",
            "path": "/v2/endpoints/{id}/features/colorTemperature/setColorTemperature"
        },
        {
           "name": "increaseColorTemperature",
           "path": "/v2/endpoints/{id}/features/colorTemperature/increaseColorTemperature"
        },
        {
          "name": "decreaseColorTemperature",
          "path": "/v2/endpoints/{id}/features/colorTemperature/decreaseColorTemperature"
        }
    ]
}

Response body parameters

Property object schema

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

POST features/colorTemperature

Call POST /v2/endpoints/{endpointId}/features/colorTemperature/setColorTemperature to set the color temperature value for the specified endpoint.

Call POST /v2/endpoints/{endpointId}/features/colorTemperature/increaseColorTemperature to increase the color temperature value for the specified endpoint. This call adjusts the color temperature but doesn't specify a value to change by; that is up to the implementing service or the manufacturer. This call has no request body.

Call POST /v2/endpoints/{endpointId}/features/colorTemperature/decreaseColorTemperature to decrease the color temperature value for the specified endpoint. This call adjusts the color temperature but doesn't specify a value to change by; that is up to the implementing service or the manufacturer. This call has no request body.

This operation is available in the following countries.

Request format

POST /v2/endpoints/{endpointId}/features/colorTemperature/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body example for setColorTemperature

{
    "payload": {
        "colorTemperatureInKelvin": 2700
    }
}

Request body parameters for setColorTemperature

Success response header

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

Success response body

If the operation is completely successful, there is no response body.

Partial success response example

The HTTP/1.1 503 Service Unavailable response indicates that the request was sent successfully, but Alexa received an error response from the endpoint reporter. Examples of endpoint errors: the endpoint is offline, the endpoint battery level is too low, etc.

HTTP/1.1 503 Service Unavailable

{
    "type": "",
    "message": ""
}

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

GET features/power

Call GET /v2/endpoints/{endpointId}/features/power to get power feature properties and their corresponding values for the specified endpoint.

This operation is available in the following countries.

Request format

GET /v2/endpoints/{endpointId}/features/power HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Response header

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

Response body example

{
   "properties": [
      {
         "name": "powerState",
         "type": "RETRIEVABLE",
         "value": {
             "value": "ON"
         },
         "timeOfSample": "1970-01-01T00:00:00Z"
      }
   ],
   "operations": [
      {
         "name": "turnOn",
         "path": "/v2/endpoints/{endpointID}/features/power/turnOn"
      },
      {
         "name": "turnOff",
         "path": "/v2/endpoints/{endpointID}/features/power/turnOff"
      }
   ]
}

Partial success response example

Following is an example showing the response returned when an error occurs during powerState property retrieval.

{
    "properties": [
        {
            "name": "powerState",
            "type": "ERROR",
            "error": {
                "type": "{ErrorType}",
                "message": "{ErrorMessage}"
            }
        }
    ],
    "operations": [
        {
            "name": "turnOn",
            "path": "/v2/endpoints/{id}/features/power/turnOn"
        },
        {
            "name": "turnOff",
            "path": "/v2/endpoints/{id}/features/power/turnOff"
        }
    ]
}

Response body parameters

Property object schema

Error object schema

Operation object schema

HTTP response codes

POST features/power

Call POST /v2/endpoints/{endpointId}/features/power/turnOn to turn on the endpoint's power.

Call POST /v2/endpoints/{endpointId}/features/power/turnOff to turn off the endpoint's power.

This operation is available in the following countries.

Request format

POST /v2/endpoints/{endpointId}/features/power/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body

None.

Response header

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

GET features/temperatureSensor

Call GET /v2/endpoints/{endpointId}/features/temperatureSensor to get temperatureSensor feature properties and their corresponding values for the specified endpoint.

This operation is available in the following countries.