Endpoint API

Note: Sign in to the developer console to build or publish your skill.

Note: This API is only available to registered Alexa Smart Properties partners. For details, see Get Started with Alexa Smart Properties APIs.

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

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

Country	Endpoint
CA, US	`https://api.amazonalexa.com`
DE, ES, FR, IT, UK	`https://api.eu.amazonalexa.com`

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.

Operation	HTTP Method and URI
GET endpoints	`GET /v2/endpoints?owner=~caller`
GET an endpoint	`GET /v2/endpoints/{endpointId}?expand=all`
Query endpoints (advanced search)	`POST /v2/endpointQuery`
PUT associatedUnits	`PUT /v2/endpoints/{endpointId}/associatedUnits`
GET features/connectivity	`GET /v2/endpoints/{endpointId}/features/connectivity`
POST saveWifiConfigurations	`POST /credentiallocker/v2/saveWifiConfigurations` Note: This operation uses a different endpoint from the other operations in the Endpoints API.
POST addOrUpdateWifiConfigurations	`POST /v2/endpoints/endpointId/features/connectivity/addOrUpdateWifiConfigurations`
GET Wi-Fi installation status	`GET /v2/endpoints/endpointId/features/connectivity/addOrUpdateWifiConfigurations/submittedOperations/{operationId}`
GET features/color	`GET /v2/endpoints/{endpointId}/features/color`
POST features/color	`POST /v2/endpoints/{endpointId}/features/color/setColor`
GET features/brightness	`GET /v2/endpoints/{endpointId}/features/brightness`
POST features/brightness	`POST /v2/endpoints/{endpointId}/features/brightness/setBrightness`
GET features/colorTemperature	`GET /v2/endpoints/{endpointId}/features/colorTemperature`
POST features/colorTemperature	`POST /v2/endpoints/{endpointId}/features/colorTemperature/setColorTemperature`
GET features/power	`GET /v2/endpoints/{endpointId}/features/power`
POST features/power	`POST /v2/endpoints/{endpointId}/features/power/turnOn` `POST /v2/endpoints/{endpointId}/features/power/turnOff`
GET features/temperatureSensor	`GET /v2/endpoints/{endpointId}/features/temperatureSensor`
GET features/thermostat	`GET /v2/endpoints/{endpointId}/features/thermostat`
GET features/speaker	`GET /endpoints/{endpointID}/features/speaker`
POST features/speaker	`POST /v2/endpoints/{endpointId}/features/speaker/setVolume` `POST /v2/endpoints/{endpointId}/features/speaker/adjustVolume`
Query endpoint setting value	`GET /v2/endpoints/{endpointId}/settings/{settingName}`
Query endpoint single setting	`GET /v2/endpoints/{endpointId}/settings/{settingName}`
Query endpoint multiple settings	`GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults}`
GET address setting	`GET /v2/endpoints/{endpointId}/settings/address`
GET DoNotDisturb setting	`GET /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb`
GET Locales setting	`GET /v2/endpoints/{endpointId}/settings/System.locales`
GET WakeWords setting	`GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords`
GET WakeWordConfirmation setting	`GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation`
GET SpeechConfirmation setting	`GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation`
GET ErrorSuppression setting	`GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression`
GET SetupModePrivileges setting	`GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.setupModePrivileges`
GET MaximumVolumeLimit setting	`GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit`
GET TimeZone setting	`GET /v2/endpoints/{endpointId}/settings/System.timeZone`
GET TemperatureUnit setting	`GET /v2/endpoints/{endpointId}/settings/System.temperatureUnit`
GET DistanceUnits setting	`GET /v2/endpoints/{endpointId}/settings/System.distanceUnits`
GET AlexaCaptions setting	`GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.AlexaCaptions.enablement`
GET ClosedCaptions setting	`GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement`
GET Magnifier setting	`GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement`
GET ColorInversion setting	`GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement`
GET multiple settings	`GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults}`
GET FollowUp setting	`GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode`
GET speaking rate setting	`GET /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate`
Update endpoint setting value	`PUT /v2/endpoints/{endpointId}/settings/{settingName}`
POST address setting	`POST /v2/endpoints/{endpointId}/settings/address`
PUT DoNotDisturb setting	`PUT /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb`
PUT Locales setting	`PUT /v2/endpoints/{endpointId}/settings/System.locales`
PUT WakeWords setting	`PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords`
PUT WakeWordConfirmation setting	`PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation`
PUT SpeechConfirmation setting	`PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation`
PUT ErrorSuppression setting	`PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression`
PUT SetupModePrivileges setting	`PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.setupModePrivileges`
PUT MaximumVolumeLimit setting	`PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit`
PUT TimeZone setting	`PUT /v2/endpoints/{endpointId}/settings/System.timeZone`
PUT TemperatureUnit setting	`PUT /v2/endpoints/{endpointId}/settings/System.temperatureUnit`
PUT DistanceUnits setting	`PUT /v2/endpoints/{endpointId}/settings/System.distanceUnits`
PUT AlexaCaptions setting	`PUT /v2/endpoints/{endpointId}/settings/Accessibility.Captions.AlexaCaptions.enablement`
PUT ClosedCaptions setting	`PUT /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement`
PUT Magnifier setting	`PUT /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement`
PUT ColorInversion setting	`PUT /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement`
PUT FollowUp setting	`PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode`
PUT speaking rate setting	`PUT /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate`
Deregister endpoint	`POST /v2/endpoints/{endpointId}/deregister`
Change an endpoint's friendly name	`POST /v2/endpoints/{endpointId}/friendlyName`
Forget endpoint	`POST /v2/endpoints/{endpointId}/forget`
Delete all timers on endpoint	`POST /v1/alerts/timers?endpoint={endpointId}`

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.

Note: You can also get endpoints by using an advanced search. For details, see Query endpoints (advanced search).

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

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.

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

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

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

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

Request query parameters

Field	Description	Type	Required
`owner`	Filter endpoints to only those endpoints that the caller owns. The only value currently supported is `"~caller"`, that represents the customer information in the bearer token. Note: you must include either the `owner` filter or the `associatedUnits.id` filter.	String	Yes (Unless an `associatedUnits` or `serialNumber.value.text` filter is specified)
`associatedUnits.id`	Filter endpoints to only those endpoints that are associated with a particular unit.	String	Yes (Unless an `owner` or `serialNumber.value.text` filter parameter is specified)
`nextToken`	Token used for getting the next page of results. For details, see Handling Pagination in Query Results.	String	No
`maxResults`	Maximum number of results to display. The value of this parameter must be between 1 and 50. Default is 10.	Integer	No
`expand`	An attribute (or set of attributes) to include in the response. Current values supported: `all`, `feature:brightness`, `feature:color`, `feature:colorTemperature`, `feature:speaker`, `feature:temperatureSensor`, `feature:thermostat`, `feature:power`, and `feature:connectivity`. Note: You can provide multiple values for expand, for example, `expand=all&expand=feature.connectivity`.	String	No
`manufacturer.value.text`	Filter endpoints to only those endpoints whose `manufacturer.value.text` exactly matches the full text of the specified value. Note: To filter on this field, it must be included in the response. For example, `expand=All`.	String	No
`model.value.text`	Filter endpoints to only those endpoints whose `model.value.text` exactly matches the full text of the specified value.	String Note: To filter on this field, it must be included in the response. For example, `expand=All`.	No
`serialNumber.value.text`	Filter endpoints to only those endpoints whose `serialNumber.value.text` exactly matches the full text of the specified value. Note: To filter on this field, it must be included in the response. For example, `expand=All`.	String	Yes (Unless an `owner` or `associatedUnits` filter parameter is specified)
`friendlyName.value.text`	Filter endpoints to only those endpoints whose `friendlyName.value.text` exactly matches the full text of the specified value. Note: To filter on this field, it must be included in the response. For example, `expand=All`.	String	No
`connections.macAddress`	Filter endpoints to only those endpoints whose `macAddress` exactly matches the specified value. Note: To filter on this field, it must be included in the response. For example, `expand=All`.	String	No
`features[name:connectivity].properties[name:reachability].value.value`	Filter endpoints to only those endpoints whose `reachability` value exactly matches the specified value. Note: This requires that the feature is expanded, for example, `expand=feature:connectivity`. For an example of how to use this filter in an API call, see the following request example.	String	No
`displayCategories.primary.value`	Filter endpoints to only those endpoints with a primary display category matching the specified value.	String	No
`displayCategories.all.value`	Filter endpoints to only those endpoints with a display category matching the specified value.	String	No

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body parameters

Field	Description	Type	Required
`results`	List of endpoints returned in response to the query. Note: The ordering of this list might change depending on the query parameters provided in the request.	List	Yes
`id`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes
`manufacturer`	The endpoint manufacturer, as a NameValue object.	Object	No
`model`	The endpoint model, as a `NameValue` object.	Object	No
`serialNumber`	The endpoint serial number, as a `NameValue` object.	Object	No
`friendlyName`	The friendly name for the endpoint, as a `NameValue` object.	Object	No
`softwareVersion`	The software version for the endpoint, as a `NameValue` object.	Object	No
`connections`	The methods that an endpoint can use to connect to the internet and smart home hubs, represented as a list of Connection objects. If no connection is associated with the endpoint, this field is empty.	List	No
`creationTime`	The time when the endpoint resource was first created.	ISO 8601 Date	No
`features`	List of Feature objects for this endpoint.	List	No
`associatedUnits`	List of Unit objects for the units that the endpoint is associated with. Returned only if `expand=all` was specified in the request. If the endpoint isn't associated with any units, the list is empty.	List	No
`operations`	List of Operation for supported operations.	List	No
`displayCategories`	Display Categories object.
`paginationContext`	Pagination context object. If present, the response contains incomplete results. If omitted, all results were already returned.	Object	No

NameValue object

Field	Description	Type
`type`	The name value type. Currently the only supported value is `"PLAIN"`, indicating that the `value` property contains the plaintext value for this property.	String
`value`	The name value, as a `Value` object.	Object

Example

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

Value object

Field	Description	Type
`text`	The string value.	String

Connection object

Field	Description	Type
`type`	The type of connection. Following are the supported values: `TCP_IP`, `ZIGBEE`, and `UNKNOWN`.	String
`macAddress`	The unique identifier for the network interface controller.	String

Example

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

Feature object

Field	Description	Type
`type`	The name of the feature, for example, `"volume"` or `"speaker"`.	String
`path`	The full path to use for retrieving expand results of this feature, for example, `"/v2/endpoints/{endpointID}/features/speaker"`.	String

Example

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

Unit object

Field	Description	Type
`id`	The unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String

Example

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

Display categories object

Field	Description	Type
`primary`	The primary categories of the endpoint.	Display Category object.
`all`	All categories of the endpoint.	Array

Example

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

Display category object

Field	Description	Type
`value`	The category in string form.	String
`sources`	The source of this display category. "CUSTOMER" means the customer explicitly set this value. "ENDPOINT_REPORTER" means this value was reported as part of the original endpoint report.	Array

Example

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

Pagination context object

Field	Description	Type
`nextToken`	Use the value of `nextToken` in the next request as the continuation token (`nextToken` query parameter) to get the next page of results. For details, see Handling Pagination in Query Results.	String

Example

{
  "nextToken": "ABCD123"
}

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The access token is valid, but the user doesn't have the needed LWA scope permissions.
429	Too many requests	The request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received.
503	Service Unavailable	Service is temporarily unavailable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

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.

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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.

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

List all attributes and `speaker` feature

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

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request query parameters

Field	Description	Type	Required
`expand`	An attribute (or set of attributes) to include in the response. Current values supported: `all`, `feature:brightness`, `feature:color`, `feature:colorTemperature`, `feature:speaker`, `feature:temperatureSensor`, `feature:thermostat`, `feature:power`, and `feature:connectivity`. Note: You can provide multiple values for expand, for example, `expand=all&expand=feature.connectivity`.	String	No

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body parameters

Field	Description	Type	Required
`id`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes
`friendlyName`	The friendly name for the endpoint, as a NameValue object.	Object	Yes
`manufacturer`	The endpoint manufacturer, as a `NameValue` object.	Object	Yes
`model`	The endpoint model, as a `NameValue` object.	Object	yes
`serialNumber`	The endpoint serial number, as a `NameValue` object.	Object	Yes
`softwareVersion`	The software version for the endpoint, as a `NameValue` object.	Object	Yes
`connections`	The methods that an endpoint can use to connect to the internet and smart home hubs, represented as a list of Connection objects. If no connection is associated with the endpoint, this field is empty.	List	No
`creationTime`	The time when the endpoint resource was first created.	ISO 8601 Date	No
`features`	List of Feature objects for this endpoint.	List	No
`associatedUnits`	List of Unit objects for the units that the endpoint is associated with. Returned only if `expand=all` was specified in the request. If the endpoint isn't associated with any units, the list is empty.	List	No
`displayCategories`	Display Categories object.
`operations`	List of Operation objects for supported operations.	List	No

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type for the error. Present only if the request was valid but the service failed to execute the request. This field can be used by business logic.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Name	Description
200	Success	The request succeeded.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	Authentication failed.
404	Not Found	The endpoint in the path doesn't exist, or the endpoint ID is invalid.
429	Too Many Requests	The request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received.
503	Service Unavailable	Service is temporarily unavailable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request

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

Request header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`access token`	Header	LWA token.	String	Yes

Request body example

The following request queries endpoints in two units.

Copied to clipboard.

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

Copied to clipboard.

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

Copied to clipboard.

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

Parameter	Description	Type	Required
`query`	Object that provides filtering conditions for the query. The fields can be either `and` or `or` lists, which can encompass additional lists of `and`/`or` filtering conditions.	Object	Yes
`query.and[]`	Query that logically joins two or more parameters by using the `and` logical operator.	Array	No
`query.and[*].match`	Object that contains specific query fields whose values must exactly match the corresponding value in the returned endpoints. You can specify the following types of values: • `associatedUnits.id`: Unit ID by which to filter. Example: `amzn1.alexa.unit.did.unitOne`. • `manufacturer.value.text`: Alexa-enabled device manufacturer by which to filter. Example: `Amazon`. • `model.value.text`: Model of Alexa-enabled device by which to filter. Example: `Echo Dot (3rd generation)`.	Object	No
`query.or[]`	Query that logically joins two or more parameters by using the `or` logical operator.	Array	No
`query.or[*].match`	Object that contains specific query fields whose values must exactly match the corresponding value in the returned endpoints. You can specify the following types of values: • `associatedUnits.id`: Unit ID by which to filter. Example: `amzn1.alexa.unit.did.unitOne`. • `manufacturer.value.text`: Alexa-enabled device manufacturer by which to filter. Example: `Amazon`. • `model.value.text`: Model of Alexa-enabled device by which to filter. Example: `Echo Dot (3rd generation)`.	Object	No
`paginationContext`	Pagination context for the result.	Object	No
`paginationContext.nextToken`	Token to retrieve a specific page of the paginated results. If this token isn't present, the response contains the first page of results.	String	No
`paginationContext.maxResults`	Maximum number of results to return in the response body. This value must be greater than 1 and less than or equal to 10.	Number	No
`expand`	Array you use to expand endpoints by top-level attributes based on the specified group. Currently, all endpoint attributes are in the `all` group. Examples of `expand` values: • `feature:speaker` • `feature:connectivity` • `feature:power` • `feature:thermostat`	Array	Optional

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.

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

Parameter	Description	Type
`results`	List of endpoints returned in response to the query. The ordering of this list might change depending on the query parameters provided in the request.	Array
`id`	Endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String
`friendlyName`	Friendly name for the endpoint, as a `NameValue` object.	Object
`manufacturer`	Endpoint manufacturer, as a NameValue object.	Object
`model`	Endpoint model, as a `NameValue` object.	Object
`serialNumber`	Endpoint serial number, as a `NameValue` object.	Object
`softwareVersion`	Software version for the endpoint, as a `NameValue` object.	Object
`connections`	Methods that an endpoint can use to connect to the internet and smart home hubs, represented as a list of Connection objects. If no connection is associated with the endpoint, this field is empty.	Array
`creationTime`	Time when the endpoint resource was first created.	ISO 8601 Date
`features`	List of Feature objects for this endpoint.	Array
`associatedUnits`	List of Unit objects for the units that the endpoint is associated with. Returned only if `expand=all` was specified in the request. If the endpoint isn't associated with any units, the list is empty.	Array
`operations`	List of Operation objects for supported operations.	Array
`displayCategories`	Display Categories object.	Object
`paginationContext`	Pagination context object. If present, the response contains incomplete results. If omitted, all results were already returned.	Object

HTTP status codes

Status	Description
`200 OK`	The request succeeded.
`400 Bad Request`	The request is malformed or is missing any required parameters.
`401 Unauthorized`	Authorization token is invalid, expired, or doesn't have access to the resource.
`403 Forbidden`	The request couldn't complete because of the client doesn't have permission to perform the operation.
`404 Endpoint not found`	The requested endpoint wasn't found.
`429 Too Many Requests`	User has exceeded the permitted rate limit (specified number of requests per unit of time).
`500 Internal Server Error`	A server-side error occurred.
`503 Service Unavailable`	The service is temporarily unavailable.

Manage endpoint-to-unit association

Note: Setup mode is disabled when the endpoint is associated with a unit within a property. It's enabled when the endpoint is associated with the caller's default unit or when it's not associated with any unit.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

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

Request body using default unit ID wildcard

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

Request body parameters

Field	Description	Type	Required
List of Unit objects	The list of units to associate with the endpoint. Each element in the array is a unit ID, in the format `"amzn1.alexa.unit.did.{id}"`. To specify the caller's default unit, use the `"~caller.defaultUnitId"` wildcard. Currently an endpoint can only be associated with one unit at a time. Note: To remove an endpoint from a unit and return it to the caller's Amazon Business account, associate the endpoint with the caller's default unit.	Array	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

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

Response body parameters

Field	Description	Type	Required
`endpoint.id`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`. Note: When you change unit associations for an endpoint, the `endpointId` might change. If it changes, this field contains the new `endpointId`.	String	Yes
`associatedUnits`	List of Unit objects for the units that the endpoint is associated with. Currently an endpoint can only be associated with one unit at a time.	List	Yes
`associatedUnits[].id`	The unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type for the error. Present only if the request was valid but the service failed to execute the request. This field can be used by business logic.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	NO_SUCH_UNIT	No such unit	The unit provided in the body does not exist.
400	TOO_MANY_UNIT_ASSOCIATIONS	The request exceeds the maximum number of unit IDs.	The request exceeds the maximum number of unit IDs. Try specifying fewer unit IDs.
400	ENDPOINT_UNREACHABLE	The endpoint is unreachable.	The endpoint is offline. Modifying `associatedUnits` is not permitted because the device is unreachable.
400	ENDPOINT_NOT_SUPPORTED	Modifying `associatedUnits` is not supported for this endpoint.	Modifying `associatedUnits` is not supported for this device type.
400	TOO_FEW_UNIT_ASSOCIATIONS	The request specifies too few unit IDs.	You must provide at least one unit ID.
401	UNAUTHORIZED	Invalid or missing access token	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The client can list the resource but doesn't have permission to rename the resource.
404	NO_SUCH_ENDPOINT	Endpoint not found	The endpoint in the path doesn't exist, or the client doesn't have permission to list the resource.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled. Retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until you receive a non-429 response.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred. Retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until you receive a non-500 response.
503	SERVICE_UNAVAILABLE	Service Unavailable	The service is temporarily unavailable to handle the request.

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

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example

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

Response body parameters

Field	Description	Type	Required
`name`	The name of the property, in this case `"reachability"`.	String	Yes
`value`	`"OK"` if the endpoint is reachable, or `"UNREACHABLE"` otherwise.	String	No
`timeOfSample`	The time when the property value was retrieved.	Date	No
`error`	The presence of this field shows that an error occurred during property value retrieval.	Object	No

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The access token is valid, but the user doesn't have the needed LWA scope permissions.
429	Too many requests	The request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received.
503	Service Unavailable	Service is temporarily unavailable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, DE, ES, FR, IT, UK	US, CA, DE, ES, FR, IT, UK	US

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

Country	Endpoint
CA, US	`https://credential-locker-service.amazon.com`
DE, ES, FR, IT, UK	`https://credential-locker-service.amazon.eu`

Note that this endpoint is different from the other operations in the Endpoints API.

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

The following example shows the request body for WPAPSK.

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

The following example shows the request body for WPA2_EAP.

{
  "wifiConfigurations": [
    {
      "credentialConfiguration": {
        "eapAuthenticationMethod": "EAP_TLS",
        "certificateAuthority": {
          "providerName": "ALEXA_ENTERPRISE",
          "id": "amzn1.alexa.enterprise.certificateAuthority.did.EXAMPLE_ID_VALUE"
        },
        "authenticationServerCertificates": [
          "-----BEGIN CERTIFICATE-----\nCERTIFICATE_CONTENT\nMULTIPLE_LINES_WITH_LINE_BREAK_CHARACTERS\n-----END CERTIFICATE-----",
          "-----BEGIN CERTIFICATE-----\nCERTIFICATE_CONTENT\nMULTIPLE_LINES_WITH_LINE_BREAK_CHARACTERS\n-----END CERTIFICATE-----"
        ]
      },
      "ssid": "\"wifi-ssid\"",
      "keyManagement": "WPA2_EAP"
    }
  ]
}

Request body parameters

Field	Description	Type	Required
`credentialConfiguration.privateSharedKey`	Private shared key. Must be enclosed in double quotation marks.	String	Yes
`credentialConfiguration.eapAuthenticationMethod`	Identifies which EAP method will be used. Currently only EAP-TLS is supported.	String	Yes
`credentialConfiguration.certificateAuthority`	Identifies the certificate authority by its provider and the ID of the resource	Object	Yes
`credentialConfiguration.certificateAuthority.providerName`	Identifies the provider of the certificate issuer	String	Yes
`credentialConfiguration.certificateAuthority.id`	Identifies the ID of the certificate authority resource within the provider's system	String	Yes
`credentialConfiguration.authenticationServerCertificates`	List of certificates provided by the authentication server used to validate the identity of the WPA2-Enterprise network.	List	Yes
`ssid`	Wifi configuration network name. Must be enclosed in double quotation marks.	String	Yes
`keyManagement`	Wifi configuration security type. Accepted values: `NONE` for open networks `WPAPSK` for password-based Wi-Fi SSIDs `WPA2_EAP` for WPA2 Enterprise Wi-Fi	String	Yes

HTTP response codes

Status code	Type Description
200	OK	Successfully saved the Wi-Fi configurations.
400	BAD_REQUEST	The request is malformed or is missing one or more required parameters.
401	UNAUTHORIZED	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	The user isn't authorized to perform the operation.
500	INTERNAL_SERVER_ERROR	A service error occurred.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, UK, DE, FR, IT, ES	US, CA, UK, DE, FR, IT, ES	US

Note: The device will try to connect to the new Wi-Fi network and can go offline if the Wi-Fi network isn't available. The device will eventually connect to an available Wi-Fi network.

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID returned by the Get all endpoints call.	String	Yes

Request body format

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

Request body parameters

Field Description Type Required

Field	Description	Type	Required
ssid	Wifi configuration network name. Must be enclosed in double quotation marks. Must be the same value used in the call to `POST saveWifiConfigurations`.	String	Yes
keyManagement	Wifi configuration security type. Must be the same value used in the call to `POST saveWifiConfigurations`. Accepted values: `NONE` for open networks `WPAPSK` for password-based Wi-Fi SSIDs `WPA2_EAP` for WPA2 Enterprise Wi-Fi	String	Yes

ssid

Wifi configuration network name. Must be enclosed in double quotation marks. Must be the same value used in the call to POST saveWifiConfigurations.

String

Yes

keyManagement

Wifi configuration security type. Must be the same value used in the call to POST saveWifiConfigurations.
Accepted values:

NONE for open networks
WPAPSK for password-based Wi-Fi SSIDs
WPA2_EAP for WPA2 Enterprise Wi-Fi

String

Yes

Response body format

{
     "submittedOperationId": "{operationId}"
}

Response body parameters

Field	Description	Type	Required
`submittedOperationId`	An identifier to be used for retrieving the status of the operation	String	Yes

HTTP response codes

Status code	Type Description
202	OK	Successfully initiated the Wi-Fi installation operation and returned the `operationId` for tracking the status in the response body.
400	BAD_REQUEST	The request is malformed or is missing one or more required parameters.
400	INVALID_CA_CERTIFICATE	A certificate cannot be issued for this request as the certificate authority certificate will expire or has expired before the expiration time of the issued certificate.
400	INVALID_CA_STATUS	The certificate authority linked to this SSID is not in an ACTIVE state and will not be able to issue a certificate for this request.
400	ENDPOINT_NOT_SUPPORTED	Adding or updating Wi-Fi configurations remotely is not supported for the specified endpoint.
400	TOO_MANY_CONFIGURATIONS	Request must contain exactly one Wi-Fi configuration.
400	INVALID_CONFIGURATION	Request contains invalid Wi-Fi configuration format.
401	UNAUTHORIZED	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	The user isn't authorized to perform the operation.
404	NOT_FOUND	Either the device endpoint wasn't found, or the specified Wi-Fi configuration wasn't found.
404	NO_SUCH_ENDPOINT	Endpoint not found.
404	NO_SUCH_CONFIGURATION	No matching Wi-Fi configuration found.
500	INTERNAL_SERVER_ERROR	A service error occurred.
504	ENDPOINT_UNREACHABLE	The endpoint is offline or unreachable. Please retry after endpoint is online.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, UK, DE, FR, IT, ES	US, CA, UK, DE, FR, IT, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID. Must be the same ID that you used in the call to POST addOrUpdateWiFiConfigurations.	String	Yes
`operationId`	The operation ID. Must be the `submittedOperationId` value returned by the `POST addOrUpdateWifiConfigurations` call	String	Yes

Response body example

{
     "status": "TIMEOUT"
}

Response body parameters

Field	Description	Type	Required
`status`	The status of specified `addOrUpdateWifiConfigurations` operation, as a Status object.	Object	Yes

Status object schema

Field	Description	Type	Required
status	Value of status. The valid values are: `SUCCESS`: Wi-Fi configurations are successfully installed on device. This doesn't provide information about device connection status to specified Wi-Fi configuration. `FAILURE`: There is an error during message delivery to device or installation on device. The detailed internal errors aren't going to be provided. Retry the operation. `TIMEOUT`: The operation timed out. The device is offline, or it failed to return a response. The actual installation state is unknown. Retry the operation. `IN_PROGRESS`: The operation is still in progress.	String	Yes

HTTP response codes

Status code	Type Description
200	OK	The operation returned the status value successfully.
300	RESOURCE_SPLIT	The endpoint ID has changed, but the underlying resource is still the same. The response body contains a URI reference for the new endpoint ID, for example, `/v2/endpoints/{newId}`.
301	ENDPOINT_REMOVED	The endpoint Id has changed, but the underlying resource is still the same. The response body contains a URI reference for the new endpoint ID, for example, `/v2/endpoints/{newId}`.
303	ENDPOINT_MERGED	The endpoint has been merged with another, causing the underlying resource to change. The response body contains a URI reference for the new endpoint ID, for example, `/v2/endpoints/{newId}`.
400	BAD_REQUEST	The request is malformed or is missing one or more required parameters.
401	UNAUTHORIZED	The LWA token is expired.
403	FORBIDDEN	The user isn't authorized to perform the operation for the specified endpoint.
404	NOT_FOUND	The specified `endpointId` or `addOrUpdateWifiConfigurations` request doesn't exist, or the request status is no longer available.
500	INTERNAL_SERVER_ERROR	A service error occurred.
503	Service Unavailable	Service is temporarily unavailable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Success response header

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Note: Both properties and operations lists are required parameters, but the contents of each object list depends on whether or not the client has permissions to view the data.

Field	Description	Type	Required
`properties`	List of color properties. Currently only `color` is supported. Each property object is a polymorphic type. The contents of the list depend on whether or not the client has permissions to view the data.	List of Property objects	Yes, but may be empty
`operations`	List of objects defining the color operations available for the specified endpoint.	List of Operation objects	Yes

Property object schema

Field	Description	Type	Required
`name`	The name of the property. Currently the only supported value is `"color"`.	String	Yes
`type`	The type of property object. There are three supported values: `RETRIEVABLE` - Alexa is able to retrieve the value of the property. `NOT_RETRIEVABLE` - Retrieval is not supported for property. A retry will not succeed. `ERROR` - Alexa is unable to retrieve the value of the property due to an error. A retry may succeed.	String	Yes
`value`	The current color. For details, see Capability Property Schemas.	String	No
`timeOfSample`	The time when the property value was retrieved.	Date	No
`error`	The presence of this field shows that an error occurred during property value retrieval.	Object	No

Error response

HTTP/1.1 {ErrorCode}

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

Error object schema

Field	Description	Type	Required
`type`	Type of error encountered during property retrieval, for example, `ENDPOINT_UNREACHABLE`, `ENDPOINT_BUSY`. For valid error types, see Error type values.	String	Yes
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	BAD_REQUEST	Bad Request	The request is invalid due to: {detailed reason}.
401	UNAUTHORIZED	Authentication Failure	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The user isn't authorized to perform the operation.
404	NOT_FOUND	Not Found	The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	ENDPOINT_UNREACHABLE	Service Unavailable	The endpoint isn't reachable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes
`operation`	The operation to perform: `setColor`.	String	Yes

Request body example for `setColor`

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

Request body parameters for `setColor`

Field	Description	Type	Required
`payload`	Payload wrapper object	Object	Yes
`payload.color`	Color object. For details, see Capability Property Schemas.	Object	Yes
`payload.color.hue`	Hue value	Double	Yes
`payload.color.saturation`	Saturation value	Double	Yes
`payload.color.brightness`	Brightness value	Double	Yes

Success response header

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	Type of error encountered, for example, `ENDPOINT_UNREACHABLE`, `ENDPOINT_BUSY`. Present only if the request was valid but the request failed to execute successfully. For valid error types, see Error type values.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	BAD_REQUEST	Bad Request	The request is invalid due to: {detailed reason}.
401	UNAUTHORIZED	Authentication Failure	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The user isn't authorized to perform the operation.
404	NOT_FOUND	Not Found	The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	ENDPOINT_UNREACHABLE	Service Unavailable	The endpoint isn't reachable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Success response header

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Note: Both properties and operations lists are required parameters, but the contents of each object list depends on whether or not the client has permissions to view the data.

Field	Description	Type	Required
`properties`	List of brightness properties. Currently only `brightness` is supported. Each property object is a polymorphic type. The contents of the list depend on whether or not the client has permissions to view the data.	List of Property objects	Yes, but may be empty
`operations`	List of objects defining the brightness operations available for the specified endpoint.	List of Operation objects	Yes

Property object schema

Field	Description	Type	Required
`name`	The name of the property. Currently the only supported value is `"brightness"`.	String	Yes
`type`	The type of property object. There are three supported values: `RETRIEVABLE` - Alexa is able to retrieve the value of the property. `NOT_RETRIEVABLE` - Retrieval is not supported for property. A retry will not succeed. `ERROR` - Alexa is unable to retrieve the value of the property due to an error. A retry may succeed.	String	Yes
`value`	The current brightness level. Valid values are from 0 to 100, inclusive. For details, see Capability Property Schemas.	String	No
`timeOfSample`	The time when the property value was retrieved.	Date	No
`error`	The presence of this field shows that an error occurred during property value retrieval.	Object	No

Error response

HTTP/1.1 {ErrorCode}

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

Error object schema

Field	Description	Type	Required
`type`	Type of error encountered during property retrieval, for example, `ENDPOINT_UNREACHABLE`, `ENDPOINT_BUSY`. For valid error types, see Error type values.	String	Yes
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	BAD_REQUEST	Bad Request	The request is invalid due to: {detailed reason}.
401	UNAUTHORIZED	Authentication Failure	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The user isn't authorized to perform the operation.
404	NOT_FOUND	Not Found	The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	ENDPOINT_UNREACHABLE	Service Unavailable	The endpoint isn't reachable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes
`operation`	The operation to perform: `setBrightness`.	String	Yes

Request body example for `setBrightness`

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

Request body parameters for `setBrightness`

Field	Description	Type	Required
`payload`	Payload wrapper object	Object	Yes
`payload.brightness`	Brightness value. Valid values are from 0 to 100, inclusive. For details, see Capability Property Schemas.	Integer	Yes

Request body example for `adjustBrightness`

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

Request body parameters for `adjustBrightness`

Field	Description	Type	Required
`payload`	Payload wrapper object	Object	Yes
`payload.brightnessDelta`	Brightness delta value. Valid values are from -100 to 100, inclusive. For details, see Capability Property Schemas.	Integer	Yes

Success response header

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Success response body

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

Partial success response example

HTTP/1.1 503 Service Unavailable

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

Error response

HTTP/1.1 {ErrorCode}

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

Error object schema

Field	Description	Type	Required
`type`	Type of error encountered, for example, `ENDPOINT_UNREACHABLE`, `ENDPOINT_BUSY`. Present only if the request was valid but the request failed to execute successfully. For valid error types, see Error type values.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	BAD_REQUEST	Bad Request	The request is invalid due to: {detailed reason}.
401	UNAUTHORIZED	Authentication Failure	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The user isn't authorized to perform the operation.
404	NOT_FOUND	Not Found	The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	ENDPOINT_UNREACHABLE	Service Unavailable	The endpoint isn't reachable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Success response header

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Note: Both properties and operations lists are required parameters, but the contents of each object list depends on whether or not the client has permissions to view the data.

Field	Description	Type	Required
`properties`	List of color temperature properties. Currently only `colorTemperatureInKelvin` is supported. Each property object is a polymorphic type. The contents of the list depend on whether or not the client has permissions to view the data.	List of Property objects	Yes, but may be empty
`operations`	List of objects defining the color temperature operations available for the specified endpoint.	List of Operation objects	Yes, but may be empty

Property object schema

Field	Description	Type	Required
`name`	The name of the property. Currently the only supported value is `"colorTemperatureInKelvin"`.	String	Yes
`type`	The type of property object. There are three supported values: `RETRIEVABLE` - Alexa is able to retrieve the value of the property. `NOT_RETRIEVABLE` - Retrieval is not supported for property. A retry will not succeed. `ERROR` - Alexa is unable to retrieve the value of the property due to an error. A retry may succeed.	String	Yes
`value`	The current color temperature value in Kelvin, from 1000 to 10000, inclusive.	Integer	No
`timeOfSample`	The time when the property value was retrieved.	Date	No
`error`	The presence of this field shows that an error occurred during property value retrieval.	Object	No

Error response

HTTP/1.1 {ErrorCode}

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

Error object schema

Field	Description	Type	Required
`type`	Type of error encountered during property retrieval, for example, `ENDPOINT_UNREACHABLE`, `ENDPOINT_BUSY`. For valid error types, see Error type values.	String	Yes
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	BAD_REQUEST	Bad Request	The request is invalid due to: {detailed reason}.
401	UNAUTHORIZED	Authentication Failure	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The user isn't authorized to perform the operation.
404	NOT_FOUND	Not Found	The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	ENDPOINT_UNREACHABLE	Service Unavailable	The endpoint isn't reachable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes
`operation`	The operation to perform: `setColorTemperature`, `increaseColorTemperature`, or `decreaseColorTemperature`.	String	Yes

Request body example for `setColorTemperature`

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

Request body parameters for `setColorTemperature`

Field	Description	Type	Required
`payload`	Payload wrapper object	Object	Yes
`payload.colorTemperatureInKelvin`	Color temperature value. From 1000 to 10000, inclusive.	Integer	Yes

Success response header

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Success response body

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

Partial success response example

HTTP/1.1 503 Service Unavailable

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

Error response

HTTP/1.1 {ErrorCode}

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

Error object schema

Field	Description	Type	Required
`type`	Type of error encountered, for example, `ENDPOINT_UNREACHABLE`, `ENDPOINT_BUSY`. Present only if the request was valid but the request failed to execute successfully. For valid error types, see Error type values.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	BAD_REQUEST	Bad Request	The request is invalid due to: {detailed reason}.
401	UNAUTHORIZED	Authentication Failure	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The user isn't authorized to perform the operation.
404	NOT_FOUND	Not Found	The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	ENDPOINT_UNREACHABLE	Service Unavailable	The endpoint isn't reachable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Note: Both properties and operations lists are required parameters, but the contents of each object list depends on whether or not the client has permissions to view the data.

Field	Description	Type	Required
`properties`	List of power-feature properties, such as power state. Each property object is a polymorphic type. For example, a `powerState` property object represents the state of the endpoint's power state at the time of sample.	List of Property objects	Yes
`operations`	List of objects defining the power-feature operations available for the specified endpoint.	List of Operation objects	Yes

Property object schema

Field	Description	Type	Required
`name`	The name of the property. Currently the only supported value is `"powerState"`.	String	Yes
`type`	The type of property object. There are three supported values: `RETRIEVABLE` - Alexa is able to retrieve the value of the property. `NOT_RETRIEVABLE` - Retrieval is not supported for property. A retry will not succeed. `ERROR` - Alexa is unable to retrieve the value of the property due to an error. A retry may succeed.	String	Yes
`value`	The current power state: `ON` or `OFF`.	String	No
`timeOfSample`	The time when the property value was retrieved.	Date	No
`error`	The presence of this field shows that an error occurred during property value retrieval.	Object	No

Error object schema

Field	Description	Type	Required
`type`	Type of error encountered during retrieval of the property: `"DEVICE_UNREACHABLE"` or `"INTERNAL_ERROR"`.	String	Yes
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

Operation object schema

Field	Description	Type	Required
`name`	The operation name. For the power feature, this is `"turnOn"` or `"turnOff"`.	String	Yes
`path`	The full path that can be used to set the feature properties.	String	Yes

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	BAD_REQUEST	Bad Request	The request is invalid due to: {detailed reason}.
401	UNAUTHORIZED	Authentication Failure	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The user isn't authorized to perform the operation.
404	NOT_FOUND	Not Found	The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	ENDPOINT_UNREACHABLE	Service Unavailable	The endpoint isn't reachable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes
`operation`	The operation to perform: `turnOn` or `turnOff`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	BAD_REQUEST	Bad Request	The request is invalid due to: {detailed reason}.
401	UNAUTHORIZED	Authentication Failure	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The user isn't authorized to perform the operation.
404	NOT_FOUND	Not Found	The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	ENDPOINT_UNREACHABLE	Service Unavailable	The endpoint isn't reachable.

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.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request body

None.

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example

{
   "name": "temperatureSensor",
   "properties": [
      {
         "name": "temperature",
         "type": "RETRIEVABLE",
         "value": {
            "value": 68.0,
            "scale": "FAHRENHEIT"
         },
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      },
   ]
}

Supported Property Values

Field	Description	Type	Required
`temperature.value`	The temperature reported by the sensor.	temperature Object	No

Temperature

Field	Description	Type
`value`	The temperature.	Double
`scale`	The scale of the temperature.	A temperature scale string.

Example temperature value

{
    "value": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
    }
}

Temperature scales

Value	Description
`CELSIUS`	The Celsius temperature scale.
`FAHRENHEIT`	The Fahrenheit temperature scale.
`KELVIN`	The Kelvin temperature scale.

GET `features/thermostat`

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request body

None.

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example (Single Setpoint Thermostat)

{
   "name": "thermostat",
   "properties": [
      {
         "name": "thermostatMode",
         "type": "RETRIEVABLE",
         "value": {
            "value": "HEAT"
         },
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      },
      {
         "name": "targetSetpoint",
         "type": "RETRIEVABLE",
         "value": {
            "value": 68.0,
            "scale": "FAHRENHEIT"
         },
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      },
   ],
   "operations": [
      {
         "name": "setThermostatMode",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/setThermostatMode"
      },
      {
         "name": "setTargetSetpoint",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/setTargetSetpoint"
      },
      {
         "name": "adjustTargetSetpoint",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/adjustTargetSetpoint"
      }
   ],
   "configuration": {
      "supportedModes": [
         "HEAT",
         "COOL",
         "AUTO"
      ]
   }
}

Response body example (Dual Setpoint Thermostat)

{
   "name": "thermostat",
   "properties": [
      {
         "name": "thermostatMode",
         "type": "RETRIEVABLE",
         "value": {
            "value": "HEAT"
         },
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      },
      {
         "name": "lowerSetpoint",
         "type": "RETRIEVABLE",
         "value": {
            "value": 68.0,
            "scale": "FAHRENHEIT"
         },
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      },
      {
         "name": "upperSetpoint",
         "type": "RETRIEVABLE",
         "value": {
            "value": 73.0,
            "scale": "FAHRENHEIT"
         },
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      }
   ],
   "operations": [
      {
         "name": "setThermostatMode",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/setThermostatMode"
      },
      {
         "name": "setTargetSetpoint",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/setTargetSetpoint"
      }
   ],
   "configuration": {
      "supportedModes": [
         "HEAT",
         "COOL",
         "AUTO"
      ]
   }
}

Supported Property Values

Field	Description	Type	Required
`targetSetpoint.value`	The target temperature of a single-setpoint thermostat.	temperature Object	No
`lowerSetpoint.value`	The lower setpoint of a dual-setpoint thermostat.	temperature Object	No
`upperSetpoint.value`	The upper setpoint of a dual-setpoint thermostat.	temperature Object	No
`thermostatMode.value`	The mode of a thermostat.	thermostatMode String	No

Temperature

Field	Description	Type
`value`	The temperature.	Double
`scale`	The scale of the temperature.	A temperature scale string.

Example temperature value

{
    "value": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
    }
}

Temperature scales

Value	Description
`CELSIUS`	The Celsius temperature scale.
`FAHRENHEIT`	The Fahrenheit temperature scale.
`KELVIN`	The Kelvin temperature scale.

ThermostatMode Values

Value	Description
`AUTO`	Indicates automatic heating or cooling based on the current temperature and the setpoint.
`COOL`	Indicates cooling mode.
`HEAT`	Indicates heating mode.
`ECO`	Indicates economical mode.
`OFF`	Indicates that heating and cooling is off, but the device might still have power.

Supported Configuration

Field	Description	Type	Required
supportedModes	The modes that the device supports.	Array thermostatMode Strings	yes

Feature Operations

Supported Operations

Field	Description
`adjustTargetSetpoint`	Adjust the target set point of a single set point thermostat by a specified value.
`setTargetSetpoint`	Set the thermostat to a specified set point(s).
`setThermostatMode`	Set the mode of the thermostat.

adjustTargetSetpoint

Call POST /v2/endpoints/{endpointId}/features/thermostat/adjustTargetSetpoint to adjust the target set point of a single set point thermostat by a specified value.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body payload

Field	Description	Type	Required
`targetSetpointDelta`	The amount by which the thermostat should adjust the set point.	temperature Object	Yes

Example Request

POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/adjustTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer 
{
   "payload": {
      "targetSetpointDelta": {
         "value": -2.0,
         "scale": "CELSIUS"
      }
   }
}

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	BAD_REQUEST	Bad Request	The request is invalid due to: {detailed reason}.
401	UNAUTHORIZED	Authentication Failure	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The user isn't authorized to perform the operation.
404	NOT_FOUND	Not Found	The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	ENDPOINT_UNREACHABLE	Service Unavailable	The endpoint isn't reachable.

setTargetSetpoint

Call POST /v2/endpoints/{endpointId}/features/thermostat/setTargetSetpoint to set the thermostat to a specified set point(s).

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body payload

Field	Description	Type	Required
`targetSetpoint`	target set point for a single setpoint thermostat	temperature Object	Yes (for a single setpoint thermostat)
`lowerSetpoint`	lower set point for a dual setpoint thermostat	temperature Object	Yes (for a dual setpoint thermostat)
`upperSetpoint`	upper set point for a dual setpoint thermostat	temperature Object	Yes (for a dual setpoint thermostat)

Example Request (Single Setpoint)

POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/setTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer 
{
   "payload": {
      "targetSetpoint": {
         "value": 21.0,
         "scale": "CELSIUS"
      }
   }
}

Example Request (Dual Setpoint)

POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/setTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer 
{
   "payload": {
      "lowerSetpoint": {
         "value": 68.0,
         "scale": "FAHRENHEIT"
      },
      "upperSetpoint": {
         "value": 72.0,
         "scale": "FAHRENHEIT"
      }
   }
}

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	BAD_REQUEST	Bad Request	The request is invalid due to: {detailed reason}.
401	UNAUTHORIZED	Authentication Failure	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The user isn't authorized to perform the operation.
404	NOT_FOUND	Not Found	The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	ENDPOINT_UNREACHABLE	Service Unavailable	The endpoint isn't reachable.

setThermostatMode

Call POST /v2/endpoints/{endpointId}/features/thermostat/setThermostatMode to set the mode of the thermostat.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body payload

Field	Description	Type	Required
`thermostatMode`	The mode to set the thermostat to.	thermostatMode String	Yes (for a single setpoint thermostat)

Example Request (Dual Setpoint)

POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/setTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer 
{
   "payload": {
      "thermostatMode": "HEAT"
   }
}

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	BAD_REQUEST	Bad Request	The request is invalid due to: {detailed reason}.
401	UNAUTHORIZED	Authentication Failure	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The user isn't authorized to perform the operation.
404	NOT_FOUND	Not Found	The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint.
429	TOO_MANY_REQUESTS	Too Many Requests	The request was throttled.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	ENDPOINT_UNREACHABLE	Service Unavailable	The endpoint isn't reachable.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example

{
   "properties": [
      {
         "name": "volume",
         "type": "RETRIEVABLE",
         "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",
            "type": "RETRIEVABLE",
            "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

Note: Both properties and operations lists are required parameters, but the contents of each object list depends on whether or not the client has permissions to view the data.

Field	Description	Type	Required
`properties`	List of speaker-feature properties, such as volume. Each property object is a polymorphic type. For example, a volume property object represents the state of the endpoint's speaker volume at the time of sample.	List of Property objects	Yes
`operations`	List of objects defining the speaker-feature operations available for the specified endpoint.	List of Operation objects	Yes

Property object schema

Field	Description	Type	Required
`name`	The name of the property. Currently the only supported value is `"volume"`.	String	Yes
`type`	The type of property object. There are three supported values: `RETRIEVABLE` - Alexa is able to retrieve the value of the property. `NOT_RETRIEVABLE` - Retrieval is not supported for property. A retry will not succeed. `ERROR` - Alexa is unable to retrieve the value of the property due to an error. A retry may succeed.	String	Yes
`value`	The current volume, for example, 42. Valid range is from 0 to 100.	Integer	No
`timeOfSample`	The time when the property value was retrieved.	Date	No
`error`	The presence of this field shows that an error occurred during property value retrieval.	Object	No

Error object schema

Field	Description	Type	Required
`type`	Type of error encountered during retrieval of the property: `"DEVICE_UNREACHABLE"` or `"INTERNAL_ERROR"`.	String	Yes
`message`	The name of the property, for example, `"volume"`.	String	Yes

HTTP response codes

Status code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The access token is valid, but the user doesn't have the needed LWA scope permissions.
404	Not found	The requested artifact wasn't found for the client.
429	Too many requests	The request was throttled because the server is too busy.
500	Internal Server Error	The request couldn't be handled because of an internal service error. Retry after one second, but don't retry more than one time.
503	Service Unavailable	Service is temporarily unavailable.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes
`operation`	One of DAAPI operation exposed on the speaker-feature for the specified endpoint: `setVolume` or `adjustVolume`.	String	Yes

Request body example for `setVolume`

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

Request body parameters for `setVolume`

Field	Description	Type	Required
`volume`	The absolute volume to set endpoint's speaker volume to. Valid range is 0 to 100.	String	Yes

Request body example for `adjustVolume`

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

Request body parameters for `adjustVolume`

Field	Description	Type	Required
`volumeDelta`	The relative volume to adjust the endpoint's speaker volume by. Valid range is -100 to 100. If the volume of the endpoint is already set to '20', and `adjustVolume` operation is invoked to adjust the endpoint volume by '-30', the endpoint volume is set to 0. Similarly, if the volume of the endpoint is already set to '20' and `adjustVolume` operation is invoked to adjust the endpoint volume by '90', the endpoint volume is set to 100.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Name	Description
202	Accepted	The request succeeded.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The access token is valid, but the user doesn't have the needed LWA scope permissions.
404	Not found	The requested artifact wasn't found for the client.
429	Too many requests	The request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error. Retry after one second, but don't retry more than one time.
503	Service Unavailable	The server is temporarily unavailable.

Query endpoint setting value

You can query the current value of a setting for an endpoint by calling GET /v2/endpoints/{endpointId}/settings/{settingName}. You can also query the current values of multiple settings for an endpoint by calling GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults}.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Supported settings

The following settings are supported.

Setting Name	Description	Response Fields	Response Field Description	Response Field Type
`address`	Get the `address` setting.	`address`	Address setting for the endpoint.	Object
`Alexa.DoNotDisturb.doNotDisturb`	Get the `DoNotDisturb` setting. This setting prevents notifications and proactive experiences (calls, etc.) from disturbing the user.	`enabled`	`true` if the `DoNotDisturb` setting is enabled, or `false` otherwise.	Boolean
`System.locales`	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.	`locales`	List of locale strings. Up to two locales can be specified. First element in the list is the preferred locale. Not all skill types are available in all locales.	List
`SpeechRecognizer.wakeWords`	Get the `WakeWords` setting. This setting controls what alternative wake words can be used to wake up Alexa.	`wakeWords`	List of 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 and locales support all wake words. COMPUTER isn't supported in France (fr-FR).	List
`SpeechRecognizer.wakeWordConfirmation`	Get the `wakeWordConfirmation` setting. This setting enables the user to specify whether they want an audible tone to play in addition to the visual indicator when Alexa detects the wake word. The tone indicates that Alexa is now listening and capturing the request.	`wakeWordConfirmation`	The current wake word confirmation setting. Alexa-supported wake word confirmation settings are `TONE` and `NONE`.	String
`SpeechRecognizer.speechConfirmation`	Get the `speechConfirmation` setting. This setting allows the user to specify whether they want a short tone to play at the end of their request to Alexa. The tone indicates that Alexa has finished listening to and capturing the request.	`speechConfirmation`	The current speech confirmation setting. Alexa supported speech confirmation settings are "TONE" and "NONE".	String
`SpeechRecognizer.FollowUp`	Get the follow-up mode setting. This setting enables Alexa to listen for a subsequent request from the user without requiring the user to say the wake word.	`FollowUp`	`true` if follow-up mode is enabled, or `false` otherwise.	Boolean
`Alexa.ManagedDevice.Settings.errorSuppression`	Get the `errorSuppression` setting. This setting controls whether the device plays error audio cues (brief, distinctive sounds) for certain errors.	`errorSuppression`	List of error suppressions. Currently the only supported value is `CONNECTIVITY`. If the list is empty ([]), no errors are suppressed.	List
`Alexa.ManagedDevice.Settings.setupModePrivileges`	Get the `setupModePrivileges` setting. 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).	`setupModePrivileges`	A 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.	List
`Alexa.ManagedDevice.Settings.maximumVolumeLimit`	Get the `maximumVolumeLimit` setting.	`maximumVolumeLimit`	A number from 0 to 100, inclusive.	Integer
`System.timeZone`	Get the `timeZone` setting.	`timeZone`	A time zone string, following the Olson format defined in the Timezone Database. For example: `"America/Los_Angeles"`.	String
`System.temperatureUnit`	Get the `temperatureUnit` setting.	`temperatureUnit`	A temperature string, `"CELSIUS"` or `"FAHRENHEIT"`.	String
`System.distanceUnits`	Get the `distanceUnits` setting.	`distanceUnits`	A distance unit string, `"METRIC"` or `"IMPERIAL"`.	String
`Accessibility.Captions.AlexaCaptions.enablement`	Get the `AlexaCaptions` setting. Note: Captions aren't supported in the UK (en-GB) or France (fr-FR).	`AlexaCaptions`	`"ENABLED"` or `"DISABLED"`.	String
`Accessibility.Captions.ClosedCaptions.enablement`	Get the `ClosedCaptions` setting. Note: Captions aren't supported in the UK (en-GB) or France (fr-FR).	`ClosedCaptions`	`"ENABLED"` or `"DISABLED"`.	String
`Accessibility.Display.Magnifier.enablement`	Get the `Magnifier` setting. Note: Magnifiers aren't supported in the UK (en-GB) or France (fr-FR).	`Magnifier`	`"ENABLED"` or `"DISABLED"`.	String
`Accessibility.Display.ColorInversion.enablement`	Get the `ColorInversion` setting. Note: Color inversion isn't supported in the UK (en-GB) or France (fr-FR).	`ColorInversion`	`"ENABLED"` or `"DISABLED"`.	String

Query endpoint single setting

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

Query endpoint multiple settings

You can query the current values of multiple settings for an endpoint by calling GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults}.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request query parameters

Field	Description	Type	Required
`keys`	Comma separated setting names to query.	String	Yes
`nextToken`	The token client uses to query the next page.	String	No
`maxResults`	The maximum result client asks for this page.	String	No

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Response body

Field	Description	Type	Required
`paginationContext`	An object with property of `nextToken`. This is for client to pass in for the subsequent request for next page. `nextToken` being absent means this is the final page.	String	No
`settings`	An array consist of objects with 2 properties: `key` and `value`. There is no specific guaranteed order for returned settings.	String	No
`errors`	An array consist of objects with each containing properties of `key`, `status`, `code` and `message`. `errors` being absent means all queries finish correctly with results filled in `settings`.	String	No

{
    "paginationContext": {
        "nextToken": "{nextToken}"
    },
    "settings": [
        {
            "key": "{settingName1}",
            "value": {value1}
        },
        {
            "key": "{settingName2}",
            "value": {value2}
        },
        ...
    ],
    "errors": [
        {
            "status": {status3},
            "key": "{settingName3}",
            "code": "{code3}",
            "message": "{message3}"
        },
        {
            "status": {status4},
            "key": "{settingName4}",
            "code": "{code4}",
            "message": "{message4}"
        },
        ...
    ]
}

Error response

HTTP/1.1 {ErrorCode}
{
    "code": "{ErrorCode}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type	Required
`code`	The error code.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example

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

Response body parameters

Field	Description	Type	Required
`address`	The device address.	Address	Yes

Address object

Parameter	Description	Type	Required
`addressLine1`	The first line of the address.	String	Yes
`addressLine2`	The second line of the address.	String	Yes, may be empty string
`addressLine3`	The third line of the address.	String	Yes, may be empty string
`city`	The city for the endpoint specified in the request.	String	Yes
`stateOrRegion`	Abbreviation for the state, province or region associated with the endpoint specified in the request. This value may be an empty string for non-US countries.	String	Yes
`districtOrCounty`	The district or county associated with the device. This value may be an empty string for non-US countries.	String	Yes
`postalCode`	The postal code for the endpoint specified in the request.	String	Yes
`countryCode`	The two-letter country/region code for the endpoint specified in the request.	String	Yes

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
503	Service Unavailable	Service is temporarily unavailable.

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.

Note: When an Alexa-enabled device is in DoNotDisturb mode, proactive suggestion campaigns only appear when the user has interacted with Alexa recently. After a few minutes of no interaction with Alexa, the device returns to showing the clock.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

Note: For language pairs, the first language in the pair is the primary language for the device. As such, the text displayed on devices with screens uses the first language in the pair.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body examples

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

   ["en-US", "fr-FR"]

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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 and locales support all wake words. COMPUTER isn't supported in France (fr-FR).

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

GET WakeWordConfirmation setting

Call GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation to update the start-of-request sound setting. This setting enables the user to specify whether they want an audible tone to play in addition to the visual indicator when Alexa detects the wake word. The tone indicates that Alexa is now listening and capturing the request.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example

   "NONE"

Response value

The current wake word confirmation setting. Alexa-supported wake word confirmation settings are TONE and NONE.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested artifact wasn't found for the client.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

GET MaximumVolumeLimit setting

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example

Response body value

An integer value from 0 to 100, inclusive.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

GET TimeZone setting

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

GET TemperatureUnit setting

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

GET DistanceUnits setting

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, IT, DE, ES	US, UK, CA, FR, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, IT, DE, ES	US, UK, CA, FR, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, IT, DE, ES	US, UK, CA, FR, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, IT, DE, ES	US, UK, CA, FR, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

GET multiple settings

Call GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults} to get the values of multiple settings.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request query parameters

Field	Description	Type	Required
`keys`	Comma separated setting names to query.	String	Yes
`nextToken`	The token client uses to query the next page.	String	No
`maxResults`	The maximum result client asks for this page.	String	No

Request body

None.

Request example

GET /v2/endpoints/{endpointId}/settings?keys=System.temperatureUnit,System.distanceUnits,Alexa.DoNotDisturb.doNotDisturb,System.timeZone HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body errors

When the HTTP response code is 200, there is chance the query on individual setting fails, in which case there are errors in response body with details included.

Status	Code	Description
204	NO_CONTENT	The setting exists, but it doesn't have a value.
403	ACCESS_DENIED	The access to the specific setting is unauthorized.
404	INVALID_KEY	Setting key doesn't exist or is invalid.
500	INTERNAL_SERVER_ERROR	The query on specific setting couldn't be handled because of an internal service error.

Response body example

{
    "paginationContext": {},
    "settings": [
        {
            "key": "System.distanceUnits",
            "value": "IMPERIAL"
        },
        {
            "key": "System.temperatureUnit",
            "value": "CELSIUS"
        }
    ],
    "errors": [
        {
            "status": 204,
            "key": "System.timeZone",
            "code": "NO_CONTENT",
            "message": "Setting value is empty"
        },
        {
            "status": 403,
            "key": "Alexa.DoNotDisturb.doNotDisturb",
            "code": "ACCESS_DENIED",
            "message": "The access to the specific setting is unauthorized"
        }
    ]
}

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

GET `FollowUp` setting

Call GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode to get the follow-up mode setting. Valid values: true or false. This setting enables Alexa to listen for a subsequent request from the user without requiring the user to say the wake word.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example

   true

Response body value

The current follow-up mode setting: true or false.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

GET speaking rate setting

Call GET /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate to get the speaking rate setting.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example

   0.75

Response body value

The response body contains the speaking rate.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Supported settings

The following settings are supported.

Setting Name	Description	Request Fields	Request Field Description	Request Field Type
`address`	Post the `address` setting.	`address`	The device address.	Object
`Alexa.DoNotDisturb.doNotDisturb`	Put the `DoNotDisturb` setting. This setting prevents notifications and proactive experiences (calls, etc.) from disturbing the user.	`enabled`	`true` if the `DoNotDisturb` setting is enabled, or `false` otherwise.	Boolean
`System.locales`	Put 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.	`locales`	List of locale strings. You can specify up to two locales. First element in the list is the preferred locale. Not all skill types are available in all locales.	List
`SpeechRecognizer.wakeWords`	Put the `WakeWords` setting. This setting controls what alternative wake words the user can say to wake up Alexa.	`wakeWords`	List of 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 and locales support all wake words. COMPUTER isn't supported in France (fr-FR).	List
`SpeechRecognizer.wakeWordConfirmation`	Put the `wakeWordConfirmation` setting. This setting enables the user to specify whether they want an audible tone to play in addition to the visual indicator when Alexa detects the wake word. The tone indicates that Alexa is now listening and capturing the request.	`wakeWordConfirmation`	The desired wake word confirmation setting. Alexa-supported wake word confirmation settings are "TONE" and "NONE".	String
`SpeechRecognizer.speechConfirmation`	Put the `speechConfirmation` setting. This setting allows the user to specify whether they want a short tone to play at the end of their request to Alexa. The tone indicates that Alexa has finished listening to and capturing the request.	`speechConfirmation`	The current speech confirmation setting. Alexa supported speech confirmation settings are "TONE" and "NONE".	String
`SpeechRecognizer.FollowUp`	Put the follow-up mode setting. This setting enables Alexa to listen for a subsequent request from the user without requiring the user to say the wake word.	`FollowUp`	`true` if follow-up mode is enabled, or `false` otherwise.	Boolean
`Alexa.ManagedDevice.Settings.errorSuppression`	Put the `errorSuppression` setting. This setting controls whether the device plays error audio cues (brief, distinctive sounds) for certain errors.	`errorSuppression`	List of error suppressions. Currently the only supported value is `CONNECTIVITY`. If the list is empty ([]), no errors are suppressed.	List
`Alexa.ManagedDevice.Settings.maximumVolumeLimit`	Put the `maximumVolumeLimit` setting.	`maximumVolumeLimit`	A number from 0 to 100, inclusive.	Integer
`System.timeZone`	Put the `timeZone` setting.	`timeZone`	A time zone string, following the Olson format defined in the Timezone Database. For example: `"America/Los_Angeles"`.	String
`System.temperatureUnit`	Put the `temperatureUnit` setting.	`temperatureUnit`	A temperature string, `"CELSIUS"` or `"FAHRENHEIT"`.	String
`System.distanceUnits`	Put the `distanceUnits` setting.	`distanceUnits`	A distance unit string, `"METRIC"` or `"IMPERIAL"`.	String
`Accessibility.Captions.AlexaCaptions.enablement`	Put the `AlexaCaptions` setting. Note: Captions aren't supported in the UK (en-GB) or France (fr-FR).	`AlexaCaptions`	`"ENABLED"` or `"DISABLED"`.	String
`Accessibility.Captions.ClosedCaptions.enablement`	Put the `ClosedCaptions` setting. Note: Captions aren't supported in the UK (en-GB) or France (fr-FR).	`ClosedCaptions`	`"ENABLED"` or `"DISABLED"`.	String
`Accessibility.Display.Magnifier.enablement`	Put the `Magnifier` setting. Note: Magnifiers aren't supported in the UK (en-GB) or France (fr-FR).	`Magnifier`	`"ENABLED"` or `"DISABLED"`.	String
`Accessibility.Display.ColorInversion.enablement`	Put the `ColorInversion` setting. Note: Color inversion isn't supported in the UK (en-GB) or France (fr-FR).	`ColorInversion`	`"ENABLED"` or `"DISABLED"`.	String

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   {value}

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

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.

Note: The country of the address should match the country your organization was created for. For example, if an organization was created to manage UK properties, only UK addresses should be set for endpoints within that organization.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

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

Request body parameters

Field	Description	Type	Required
`address`	The device address.	Address	Yes

Address object

Parameter	Description	Type	Required
`addressLine1`	The first line of the address.	String	Yes
`addressLine2`	The second line of the address.	String	Yes, may be empty string
`addressLine3`	The third line of the address.	String	Yes, may be empty string
`city`	The city for the endpoint specified in the request.	String	Yes
`stateOrRegion`	Abbreviation for the state, province or region associated with the endpoint specified in the request. This value may be an empty string for non-US countries.	String	Yes
`districtOrCounty`	The district or county associated with the device. This value may be an empty string for non-US countries.	String	Yes
`postalCode`	The postal code for the endpoint specified in the request.	String	Yes
`countryCode`	The two-letter country/region code for the endpoint specified in the request.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes
`Location`	Relative path to the created address.	String	Yes

Response body parameters

The addressSuggestions and addressErrors parameters are mutually exclusive.

Parameter	Description	Type	Required
`address`	The device address.	Address	Yes for 201, optional for 400
`addressSuggestions`	Address suggestions, if the input address was invalid.	List of address suggestions	Optional for 400
`addressErrors`	Address errors, if the input address was invalid.	List of address errors	Optional for 400

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

Parameter	Description	Type	Required
`code`	Error code	Enum	No
`subCode`	Additional information about why an address element is invalid.	Enum	No
`message`	Human-readable message	String	No
`element`	Address element to which the error applies.	Enum	No

Address error code values

`code` value	Description
`ELEMENT_REQUIRED`	A required element is missing. The element name is specified by the element field.
`ELEMENT_INVALID`	The value in a field is invalid. The element name is specified by the element field.

Address error subCode values

`subCode` value	Description
`ADDRESS_PRIMARY_RANGE_MISSING_OR_INVALID`	The address number was not valid.
`ADDRESS_STREET_INCOMPLETE`	The street address was not complete.
`ADDRESS_LINES_JUNK_DATA`	The address line field contains junk data.
`ADDRESS_FIELD_LENGTH_HIGH`	The length of the address field is greater than allowed.
`ADDRESS_CITY_INVALID`	There is no city of that name in the specified state.
`ADDRESS_COUNTY_INVALID`	The specified county is incorrect.
`ADDRESS_STATE_INVALID`	The specified state is incorrect.
`ADDRESS_ZIP_INVALID`	The specified zip code is incorrect for the specified street, city and/or state.
`ADDRESS_STREET_NOT_FOUND`	The street was not found in the specified city.
`ADDRESS_MULTIBYTE_CHARACTERS`	The field has multi-byte characters.
`ADDRESS_DOOR_LEVEL_INFO_MISSING`	The address door-level info is missing.
`FIELD_EMPTY`	A required field was empty.

Address element values

Address element	Description
`ADDRESS_1`	First line of the address.
`ADDRESS_2`	Second line of the address, if any.
`ADDRESS_3`	Third line of the address, if any.
`STREET_NAME`	Street name present in the address.
`BUILDING_NUMBER`	Building number.
`COMPLEMENT`	Number for smaller units in a building, such as an apartment number.
`NEIGHBORHOOD`	Neighborhoods are smaller regions of city.
`CITY`	City or municipality that contains the address.
`STATE`	U.S. state or possession that contains the address.
`COUNTRY`	Country that contains the address.
`ZIP`	5-digit or 9-digit zip code of the address.
`COUNTY`	County that contains the address.
`COUNTRY_CODE`	Country code of the address.

HTTP response codes

Status Code	Name	Description
201	Accepted	The request succeeded.
400	Bad Request (INVALID_REQUEST)	The request is malformed, is missing one or more required parameters, or the address is invalid and there is an address suggestion. For details, see Error response body example: 400 address suggestions and Error response body example: 400 address errors.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
429	Too many requests	Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
503	Service Unavailable	Service is temporarily unavailable.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   true

Request body value

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

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested artifact wasn't found for the client.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

Note: For language pairs, the first language in the pair is the primary language for the device. As such, the text displayed on devices with screens uses the first language in the pair.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body examples

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

   ["en-US", "fr-FR"]

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: en-CA, en-GB, en-US, fr-FR, and fr-CA. This API also supports the following language pairs: en-US/fr-FR, fr-FR/en-US, en-CA/fr-CA, and fr-CA/en-CA. Not all skill types are available in all locales.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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. Note: Not all devices and locales support all wake words. COMPUTER isn't supported in France (fr-FR).

Note: Before you can update the WakeWords setting for a device, you must set the Locales setting. For details, see Put Locales setting.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   ["ALEXA"]

Request body value

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

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

PUT WakeWordConfirmation setting

Call PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation to update the start-of-request sound setting. This setting enables the user to specify whether they want an audible tone to play in addition to the visual indicator when Alexa detects the wake word. The tone indicates that Alexa is now listening and capturing the request.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   "NONE"

Request body value

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

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

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

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

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

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested artifact wasn't found for the client.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

PUT MaximumVolumeLimit setting

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Note: This operation works on the following devices: Echo (2nd Gen), Echo (3rd Gen), Echo (4th Gen), Echo Dot (2nd Gen), Echo Dot (3rd Gen), Echo Dot (4th Gen), Echo Dot (3rd Gen), Echo Dot with Clock(3rd Gen), Echo Dot with Clock (4th Gen), Echo Dot with Clock (5th Gen), Echo Pop, Echo Show 5 (3rd Gen).

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

Request body value

An integer value from 0 to 100, inclusive.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

PUT TimeZone setting

Call PUT /v2/endpoints/{endpointId}/settings/System.timeZone to update the time zone.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   "America/Los_Angeles"

Request body value

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

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

PUT TemperatureUnit setting

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   "CELSIUS"

Request body value

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

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

PUT DistanceUnits setting

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, UK, FR, CA, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   "METRIC"

Request body value

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

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

PUT AlexaCaptions setting

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, IT, DE	US, UK, CA, FR, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   "ENABLED"

Request body value

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

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

PUT ClosedCaptions setting

Call PUT /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement to update the Alexa caption setting.

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, IT, DE	US, UK, CA, FR, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   "ENABLED"

Request body value

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

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

PUT Magnifier setting

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

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

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, IT, DE	US, UK, CA, FR, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   "ENABLED"

Request body value

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

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

PUT ColorInversion setting

Call PUT /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.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, IT, DE	US, UK, CA, FR, IT, DE	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   "ENABLED"

Request body value

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

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Response header parameters

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

PUT `FollowUp` setting

Call PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode to update the follow-up mode setting. Valid values: true or false. This setting enables Alexa to listen for a subsequent request from the user without requiring the user to say the wake word.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   false

Request body value

The new follow-up mode setting: true or false.

Response header

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

PUT speaking rate setting

Call PUT /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate to update the speaking rate setting.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body example

   0.75

Request body value

The new speaking rate setting. Accepted values: 0.75, 0.85, 1, 1.25, 1.5, 1.75, and 2. The default setting is 1.

Response header

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED)	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested endpoint wasn't found.
405	Method Not Allowed	The device doesn't support the setting.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

Deregister endpoint

Call POST /v2/endpoints/{endpointId}/deregister to deregister an endpoint from your Amazon Business account.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request body

None.

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Response body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The access token is valid, but the user doesn't have the needed LWA scope permissions.
429	Too many requests	The request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received.
500	Internal Server Error	The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received.
503	Service Unavailable	Service is temporarily unavailable.

Change an endpoint's friendly name

Call POST /v2/endpoints/{endpointId}/friendlyName to change the friendly name for an endpoint. Alexa uses the friendly name for all GUI and VUI experiences. Customers can use the friendly name to control an endpoint, for example, "Alexa, turn on {friendlyName}."

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body format

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

Request body example

{
  "type": "PLAIN",
  "value": {
    "text": "My Light"
  }
}

Request body parameters

Field	Description	Type	Required
`type`	The name value type. Currently the only supported value is `"PLAIN"`.	String	Yes
`value`	A Value object containing the friendly name for the endpoint.	Value	Yes

Value object

Field	Description	Type	Required
`text`	The friendly name string. The string must consist of 1 to 128 Unicode (UTF-8) characters and must not contain special characters or punctuation (except for apostrophes). The following rules apply. * Characters must be numbers, letters (Chinese characters and non-Roman letters are permitted), spaces, or apostrophes. * Names must contain at least one number or letter.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Error response body format

{
     "type" :  "{errorType}" ,
     "message" :  "{errorMessage}"
}

Error response parameters

Field	Description	Type	Required
`type`	The error type for the error. Present only if the request was valid but the service failed to execute the request. This field can be used by business logic.	String	No
`message`	The error message for the error. The error message is exposed only for debugging/logging purposes. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status code	Type	Message	Description
200	OK	The request succeeded.
400	INVALID_FRIENDLY_NAME	The input friendly name has the following problems: {problemString}	The request is missing one or more required parameters, or one or more parameter values aren't valid.
400	DUPLICATE_NAME	The input friendly name is already assigned to another device.	Friendly names must be unique.
401	UNAUTHORIZED	Invalid or missing access token	The LWA token is missing, expired, or invalid.
403	FORBIDDEN	Forbidden	The client can list the resource but doesn't have permission to rename the resource.
404	NO_SUCH_ENDPOINT	Endpoint not found	The endpoint in the path doesn't exist, or the client does not have permission to list the resource.
429	TOO_MANY_REQUESTS	Too Many Requests	Request was throttled. Retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until you receive a non-429 response.
500	INTERNAL_SERVER_ERROR	Internal Service Error	A service error occurred.
503	SERVICE_UNAVAILABLE	Service Unavailable	The service is temporarily unavailable to handle the request.

Forget endpoint

Call POST /v2/endpoints/{endpointId}/forget to forget an endpoint.

Note: This call only applies to Alexa's representation of the endpoint. It doesn't propagate back to the entity that reported the endpoint to Alexa (for example, a smart home skill). To ensure the endpoint is not automatically reconnected to Alexa, remove it from the reporter. For example, for endpoints that are reported by a manufacturer's smart home skill, remove the endpoint from the manufacturer's app before calling forget.

Note: Don't use this API to disassociate an endpoint from a room. To disassociate an endpoint from a room, use PUT associatedUnits.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES	US, UK, FR, CA, IT, DE, ES	US

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Error response body format

{
    "message": "{errorMessage}"
}

Error response parameters

Field	Description	Type	Required
`message`	The error message for the error.	String	No

HTTP response codes

Status code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request is missing one or more required parameters, or one or more parameter values aren't valid.
401	Unauthorized	The LWA token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
404	Not found	The requested resource wasn't found, or the client doesn't have access to it.
429	Too many requests	Request was throttled. Don't perform automatic retries. Wait until the service has recovered, and then retry the operation.
500	Internal Server Error	A service error occurred. Retry after one second, backing off exponentially with jitter until a 256-second wait. Retry every 256 seconds thereafter until you receive a non-500 response.
503	Service Unavailable	The service is temporarily unavailable to handle the request.

Delete all timers for an endpoint

Call DELETE /v1/alerts/timers?endpoint={endpointId} to delete all timers on an endpoint. To delete timers on all endpoints in a unit, see [Delete all timers for a unit] (../alexa-smart-properties/unit-api.html#delete-all-timers-for-unit)

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	CA,DE, ES, FR, IT, US, UK	CA,DE, ES, FR, IT, US, UK	None

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

DELETE /v1/alerts/timers?endpoint={endpointId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: {LWA Token}

Request body

None.

Request parameters

Field	Description	Type	Required
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response

Upon successful deletion, the server returns an HTTP 204 No Content status response. A successful payload doesn't contain a body.

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

Error response

HTTP/1.1 {ErrorCode}
Content-Type: application/json

{
    "errors": [{
        "type": "{ErrorType}",
        "endpointId": "{EndpointId}",
        "message": "{ErrorMessage}"
    }]
}

Error response parameters

Field	Description	Type	Required
`type`	The error name, such as `DEVICE_UNREACHABLE`.	String	No
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	No
`message`	The error message for the error. The error message appears only for debugging/logging purposes. You must not share it with the user. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Timers were successfully deleted on the endpoint. Note that this status code is returned even if the endpoint has no timers to delete.
400	BAD_REQUEST	The request is malformed or is missing one or more required parameters.
401	UNAUTHORIZED	The authentication token is invalid or doesn't have access to the resource.
403	FORBIDDEN	The user doesn't have permission to perform the operation, or the unit doesn't exist.
404	NOT FOUND	The requested resource wasn't found, or the client doesn't have access to it.
500	INTERNAL_SERVER_ERROR	The request couldn't be handled because of an internal service error.
504	DEVICE_NOT_REACHABLE	The device is offline or unreachable.

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023

Endpoint API

API endpoint

Authentication

Operations

Get endpoints

Get all endpoints

Request

Request format examples

Get all endpoints that aren't associated with a unit

Include details for each endpoint

Include connectivity for each endpoint

Get all endpoints associated with a unit

Request query parameters

Response header

Response body parameters

NameValue object

Example

Value object

Connection object

Example

Feature object

Example

Unit object

Example

Display categories object

Example

Display category object

Example

Pagination context object

Example

Error response

Error response parameters

HTTP response codes

Get an endpoint

Request

Request format examples

List endpoint ID only

List all attributes

List all attributes and speaker feature

Request path parameters

Request query parameters

Response header

Response body parameters

Error response

Error response parameters

HTTP response codes

Query endpoints (advanced search)

Request

Request header example

Request path and header parameters

Request body example

Request body parameters

Response

Response body example

Response body parameters

HTTP status codes

Manage endpoint-to-unit association

PUT associatedUnits

Request format

Request path parameters

Request body

Request body using default unit ID wildcard

Request body parameters

Response header

Response body

Response body parameters

Error response

Error response parameters

HTTP response codes

Query the endpoint status

Request example

Manage connectivity feature

GET features/connectivity

Request format

Request body

Request path parameters

Response header

Response body example

Response body parameters

Error response

List all attributes and `speaker` feature

PUT `associatedUnits`

Manage `connectivity` feature

GET `features/connectivity`

POST `saveWifiConfigurations`

POST `addOrUpdateWifiConfigurations`

GET `features/color`

POST `features/color`

Request body example for `setColor`

Request body parameters for `setColor`

GET `features/brightness`

POST `features/brightness`

Request body example for `setBrightness`

Request body parameters for `setBrightness`

Request body example for `adjustBrightness`

Request body parameters for `adjustBrightness`