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

To specify the caller's default unit, use the ~caller.defaultUnitId wildcard.

GET /v2/endpoints?associatedUnits.id=~caller.defaultUnitId&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

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}

POST associatedUnits

Call POST /v2/endpoints/{endpointId}/associatedUnits to associate an endpoint with a unit. An endpoint can only be associated with one unit at a time.

Request format

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

Request path parameters

Request body

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

Request body parameters

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

DELETE associatedUnits

Call DELETE /v2/endpoints/{endpointId}/associatedUnits/{unitId} to disassociate an endpoint from a unit.

Request format

DELETE /v2/endpoints/{endpointId}/associatedUnits/{unitId} 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

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

speaker operations

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

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

PUT /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 example

   true

Request body value

A Boolean value: true to enable the DoNotDisturb setting, or false otherwise.

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

Put Locales setting

Call PUT /v2/endpoints/{endpointId}/settings/System.locales to update the locale setting. 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

PUT /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 example

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

Request body value

List of locale strings. Specify at least one and no more than two locales. The first element in the list specifies the preferred locale. The following locales are supported: de-DE, en-AU, en-CA, en-GB, en-IN, en-US, es-ES, es-MX, fr-FR, fr-CA, hi-IN, it-IT, ja-JP, pt-BR. Not all skill types are available in all locales.

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

Put WakeWords setting

Call PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords to update the WakeWords setting. This setting controls what alternative wake words can be used to wake up Alexa.

The supported wake words are: ALEXA, AMAZON, COMPUTER, and ECHO. Currently you can only specify one wake word at a time. Not all devices support all wake words.

Request format

PUT /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 example

   ["ALEXA"]

Request body value

List of wake words, for example, ["ALEXA"].

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

Put SpeechConfirmation setting

Call PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation to update the end-of-request sound setting. 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

PUT /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 example

   "NONE"

Request body value

A string containing the desired speech confirmation setting. Alexa supported speech confirmation settings are "TONE" and "NONE".

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

Put ErrorSuppression setting

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

Request format

PUT /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 example

   ["CONNECTIVITY"]

Request body value

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

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

Put SetupModePrivileges setting

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

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

Request path parameters

Request body example

   ["ALL_SETTINGS"]

Request body value

List of setup mode privileges. Currently the only supported setup mode privilege is ["ALL_SETTINGS"]. ["ALL_SETTINGS"] allows the end user to put a device into setup mode. An empty list ([]) shows that setup mode is to be disabled.

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

Put MaximumVolumeLimit setting

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

Request format

PUT /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 example

   42

Request body value

An integer value from 0 to 100, inclusive.

Response header

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