Endpoint API

About endpoints

An endpoint represents an Alexa-connected device (like an Echo device) with which an Alexa customer can interact. In Alexa for Hospitality, you manage your Echo devices using the Alexa 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.

Enumerate endpoints

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

Request format examples

The following examples show how to use this call.

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

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"
            }
         ],
         "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"
            }
         ]
      },
      {
         "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"
            }
         ],
         "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"
            }
         ]
      }
  ],
  "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"
                 }
             ],
             "features": [
                {
                    "name": "speaker",
                    "path": "/v2/endpoints/{endpointID}/features/speaker"
                },
                {
                    "name": "connectivity",
                    "properties": [
                       {
                           "name": "reachability",
                           "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"
                 }
             ]
         },
         {
             "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"
                 }
             ],
             "features": [
                 {
                     "name": "speaker",
                     "path": "/v2/endpoints/{endpointID}/features/speaker"
                 },
                 {
                     "name": "connectivity",
                     "properties": [
                        {
                            "name": "reachability",
                            "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"
                 }
             ]
         }
     ],
     "paginationContext": {
         "nextToken": "ABCD123"
     }
}

Enumerate endpoints associated with a unit

To enumerate 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"
            }
         ],
         "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"
            }
         ]
      }
}

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

Pagination context object

Example

{
  "nextToken": "ABCD123"
}

Error response

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

Error response parameters

HTTP response codes

Retrieve endpoint

Call GET /v2/endpoints/{endpointId}?expand=all to retrieve 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.

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"
      }
   ],
   "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"
      }
   ]
}

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"
      }
   ],
   "features":[
        {
           "name": "speaker",
            "properties": [
                {
                    "name": "volume",
                    "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"
      }
   ]
}

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

Manage endpoint-to-unit association

PUT associatedUnits

Call PUT /v2/endpoints/{endpointId}/associatedUnits to update the list of associated units for an endpoint. Currently an endpoint can only be associated with one unit at a time.

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.

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",
            "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.

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.

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.

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 speaker feature

GET features/speaker

Call GET /endpoints/{endpointID}/features/speaker to retrieve speaker-feature properties and their corresponding values of the specified endpoint.

Request format

GET /v2/endpoints/{endpointId}/features/speaker 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": "volume",
         "value": {
             "value": 42
         },
         "timeOfSample": "1970-01-01T00:00:00Z"
      }
   ],
   "operations": [
      {
         "name": "setVolume",
         "path": "/v2/endpoints/{endpointID}/features/speaker/setVolume"
      },
      {
         "name": "adjustVolume",
         "path": "/v2/endpoints/{endpointID}/features/speaker/adjustVolume"
      }
   ]
}

Partial success response example

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

{
    "properties": [
        {
            "name": "volume",
            "error": {
                "type": "{ErrorType}",
                "message": "{ErrorMessage}"
            }
        }
    ],
    "operations": [
        {
            "name": "setVolume",
            "path": "/v2/endpoints/<id>/features/speaker/setVolume"
        },
        {
            "name": "adjustVolume",
            "path": "/v2/endpoints/<id>/features/speaker/adjustVolume"
        }
    ]
}

Response body parameters

Property object schema

Error object schema

Operation object schema

HTTP response codes

POST features/speaker

Call POST /v2/endpoints/{endpointId}/features/speaker/setVolume to set speaker volume to the specified value on the specified endpoint.

Call POST /v2/endpoints/{endpointId}/features/speaker/adjustVolume to adjust speaker volume by the specified value on the specified endpoint.

Request format

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

Request path parameters

Request body example for setVolume

{
    "payload": {
        "volume": 42
    }
}

Request body parameters for setVolume

Request body example for adjustVolume

{
    "payload": {
        "volumeDelta": -42
    }
}

Request body parameters for adjustVolume

Response header

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

Response body

None.

Error response

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

Error response parameters

HTTP response codes

Query endpoint setting value

You can query the current value of a setting for an endpoint by calling GET /v2/endpoints/{endpointId}/settings/{settingName}.

Supported settings

The following settings are supported.

Request path parameters

Request body

None.

Response header

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

Response header parameters

Request format

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

Response body

  {value}

Error response

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

Error response parameters

GET address setting

Call GET /v2/endpoints/{endpointId}/settings/address to get the address where an endpoint is located. Alexa uses this setting for features like Local Search and Weather. For details, see Enhance Your Skill With Address Information.

Request format

GET /v2/endpoints/{endpointId}/settings/address 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

Response header parameters

Response body example

{
    "address": {
        "addressLine1": "221 Baker Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Sunnyvale",
        "stateOrRegion": "California",
        "districtOrCounty": "",
        "postalCode": "94085",
        "countryCode": "US"
    }
}

Response body parameters

Address object

HTTP response codes

GET DoNotDisturb setting

Call GET /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb to get the DoNotDisturb setting. This setting prevents notifications and proactive experiences (calls, etc.) from disturbing the user.

Request format

GET /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb 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

Response header parameters

Response body example

   true

Response body value

A Boolean value: true if the DoNotDisturb setting is enabled, or false otherwise.

Error response

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

Error response parameters

HTTP response codes

GET Locales setting

Call GET /v2/endpoints/{endpointId}/settings/System.locales to get the user's preferred locales. In the context of an Alexa device, this setting controls which languages the Alexa-enabled device is expected to understand and respond with.

Request format

GET /v2/endpoints/{endpointId}/settings/System.locales 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

Response header parameters

Response body example

   ["en-US", "es-US"]

Response body value

A list of up to two locale strings. First element in the list is the preferred locale. Not all skill types are available in all locales.

Error response

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

Error response parameters

HTTP response codes

GET WakeWords setting

Call GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords to get the WakeWords setting. This setting controls what alternative wake words the user can say to wake up Alexa.

Request format

GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords 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

Response header parameters

Response body example

   ["ALEXA"]

Response body value

A list of the currently enabled wake words, for example, ["ALEXA"]. Alexa supported wake words are, ALEXA, AMAZON, COMPUTER, and ECHO. Currently you can only specify one wake word at a time. Note: Not all devices support all wake words.

Error response

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

Error response parameters

HTTP response codes

GET SpeechConfirmation setting

Call GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation to get the end-of-request sound. This setting allows the user to specify whether they want a short tone to play at the end of their request to Alexa to indicate that Alexa has finished listening to and capturing the request.

Request format

GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation 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

Response header parameters

Response body example

   "NONE"

Response value

The current speech confirmation setting. Alexa supported speech confirmation settings are "TONE" and "NONE".

Error response

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

Error response parameters

HTTP response codes

GET ErrorSuppression setting

Call GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression to get the list of error suppressions. This setting controls whether the device plays error audio cues (brief, distinctive sounds) for certain errors.

Request format

GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression 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

Response header parameters

Response body example

   ["CONNECTIVITY"]

Response body value

The list of error suppressions. Currently the only supported value is ["CONNECTIVITY"]. An empty list shows that no errors are suppressed.

Error response

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

Error response parameters

HTTP response codes

GET SetupModePrivileges setting

Call GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.setupModePrivileges to get the list of setup mode privileges. This setting controls the end user's ability to put a device into configuration mode via the setup mode process (for example, by long-pressing the Action button).

Request format

GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.setupModePrivileges 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

Response header parameters

Response body example

   ["ALL_SETTINGS"]

Response body value

The list of setup mode privileges. Alexa supported list of setup mode privileges is, ["ALL_SETTINGS"]. ["ALL_SETTINGS"] allows the end user to put a device into setup mode. An empty list ([]) shows that setup mode is disabled.

Error response

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

Error response parameters

HTTP response codes

GET MaximumVolumeLimit setting

Call GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit to get the maximum volume limit.

Request format

GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit 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

Response header parameters

Response body example

   42

Response body value

An integer value from 0 to 100, inclusive.

Error response

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

Error response parameters

HTTP response codes

GET TimeZone setting

Call GET /v2/endpoints/{endpointId}/settings/System.timeZone to get the time zone.

Request format

GET /v2/endpoints/{endpointId}/settings/System.timeZone 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

Response header parameters

Response body example

   "America/Los_Angeles"

Response body value

A time zone string, following the Olson format defined in the Timezone Database. For example: "America/Los_Angeles".

Error response

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

Error response parameters

HTTP response codes

GET TemperatureUnit setting

Call GET /v2/endpoints/{endpointId}/settings/System.temperatureUnit to get the temperature scale (Celsius or Fahrenheit) setting.

Request format

GET /v2/endpoints/{endpointId}/settings/System.temperatureUnit 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

Response header parameters

Response body example

   "CELSIUS"

Response body value

A temperature unit string: "CELSIUS" or "FAHRENHEIT".

Error response

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

Error response parameters

HTTP response codes

GET DistanceUnits setting

Call GET /v2/endpoints/{endpointId}/settings/System.distanceUnits to get the distance units (Metric or Imperial) setting.

Request format

GET /v2/endpoints/{endpointId}/settings/System.distanceUnits 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

Response header parameters

Response body example

   "METRIC"

Response body value

A distance unit string: "METRIC" or "IMPERIAL".

Error response

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

Error response parameters

HTTP response codes

GET AlexaCaptions setting

Call GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.AlexaCaptions.enablement to get the Alexa caption setting.

This setting controls whether a multimedia device displays the following information:

• Alexa captions, which provide the text version of what Alexa speaks via SpeechSynthesizer. All domains that use Alexa Voice Service (AVS) should provide captions.
• The captions that accompany AudioPlayer directives.

Request format

GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.AlexaCaptions.enablement 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

Response header parameters

Response body example

   "ENABLED"

Response body value

A string representing the current value of this setting: "ENABLED" or "DISABLED".

Error response

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

Error response parameters

HTTP response codes

GET ClosedCaptions setting

Call GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement to get the closed caption setting.

This setting controls whether a multimedia device displays closed captions for video content.

Request format

GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement 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

Response header parameters

Response body example

   "ENABLED"

Response body value

A string representing the current value of this setting: "ENABLED" or "DISABLED".

Error response

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

Error response parameters

HTTP response codes

GET Magnifier setting

Call GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement to get the device magnifier setting.

This setting gives the device user the ability to enlarge items on the screen to improve readability.

Request format

GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement 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

Response header parameters

Response body example

   "ENABLED"

Response body value

A string representing the current value of this setting: "ENABLED" or "DISABLED".

Error response

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

Error response parameters

HTTP response codes

GET ColorInversion setting

Call GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement to get the screen color inversion setting.

This setting gives the device user the ability to invert the screen display colors to improve readability.

Request format

GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement 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

Response header parameters

Response body example

   "ENABLED"

Response body value

A string representing the current value of this setting: "ENABLED" or "DISABLED".

Error response

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

Error response parameters

HTTP response codes

Update endpoint setting value

You can update the current value of most settings for an endpoint by calling PUT /v2/endpoints/{endpointId}/settings/{settingName}. One exception is the address setting, which uses POST.

Supported settings

The following settings are supported.

Request path parameters

Request body example

   {value}

Response header

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

Response header parameters

Request format

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

Response body

None.

Error response

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

Error response parameters

POST address setting

Call POST /v2/endpoints/{endpointId}/settings/address to set the address where an endpoint is located. Alexa uses this setting for features like Local Search and Weather. For details, see Enhance Your Skill With Address Information.

Request format

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

Request path parameters

Request body example

{
    "address": {
        "addressLine1": "221 Baker Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Sunnyvale",
        "stateOrRegion": "California",
        "districtOrCounty": "",
        "postalCode": "94085",
        "countryCode": "US"
    }
}

Request body parameters

Address object

Response header

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

Response header example

Host: api.amazonalexa.com
X-Amzn-RequestId: 6006f07b-539f-4924-869a-2f8bcf60bdf6
Content-Type: application/json
Location: /v2/endpoints/{endpoint-id}/settings/address

Response header parameters

Response body parameters

The addressSuggestions and addressErrors parameters are mutually exclusive.

Success response body example

{
    "address": {
        "addressLine1": "221 Baker Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Sunnyvale",
        "stateOrRegion": "California",
        "districtOrCounty": "",
        "postalCode": "94085",
        "countryCode": "US"
    }
}

Error response body example: 400 address suggestions

If the request is malformed or is missing any required parameters, the operation returns a list of address suggestions, sorted in descending order of confidence.

{
  "addressSuggestions": [
      {
        "address": {
          "addressLine1":"221 Baker Ave",
          "addressLine2": "",
          "addressLine3": "",
          "city":"Sunnyvale",
          "stateOrRegion":"California",
          "districtOrCounty": "",
          "postalCode":"94085",
          "countryCode":"US"
        }
      } 
  ],
  "code": 400,
  "description": "The input address is invalid. Suggested valid addresses are included in the response."
}

Error response body example: 400 address errors

If the request is malformed or is missing any required parameters, the operation returns a list of address errors.

{
  "addressErrors": [
      {
        "code": "FIELD_REQUIRED|FIELD_INVALID",
        "subCode": "ADDRESS_STREET_INCOMPLETE|...",
        "message": "{human-readable message}",
        "element": "ADDRESS_1|ADDRESS_2|..."
      }
    ],
  "code": 400,
  "description": "The input address is invalid. The list of errors is included in the response."
}

Address errors object

Address error code values

Address error subCode values

Address element values

HTTP response codes

PUT DoNotDisturb setting

Call PUT /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb to update the DoNotDisturb setting. This call prevents notifications and proactive experiences (calls, etc.) from disturbing the user.

Request format