Endpoint API


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

JP

https://api.fe.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

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.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

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.

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

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

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

US, UK, FR, CA, IT, DE, ES, JP

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.

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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.

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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.

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

GET /v2/endpoints/{endpointId}?expand=all&expand=feature:speaker 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
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

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.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, CA, DE, ES, FR, IT, UK, JP

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

JP

https://credential-locker-service.amazon.jp

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

US, CA, UK, DE, FR, IT, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, CA, UK, DE, FR, IT, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

US, UK, FR, CA, IT, DE, ES, JP

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

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

US, UK, FR, CA, IT, DE, JP

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

US, UK, FR, CA, IT, DE, ES, JP

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

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

US, UK, FR, CA, IT, DE, JP

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

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/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, JP

US, UK, FR, CA, IT, DE, ES, JP

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

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

US, UK, FR, CA, IT, DE, JP

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

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/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, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

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

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, JP

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

US, UK, FR, CA, IT, DE, ES, JP

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

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

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

US, UK, FR, CA, IT, DE, ES, JP

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

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

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

   42

Response body value

An integer value from 0 to 100, inclusive.

Error response

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

Error response parameters

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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:

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, CA, IT, DE, ES, JP

US, UK, CA, FR, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, CA, FR, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, CA, FR, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, CA, FR, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, JP

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

US, UK, FR, CA, IT, DE, JP

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

US, UK, FR, CA, IT, DE, JP

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

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, JP

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, JP

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, JP

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

   42

Request body value

An integer value from 0 to 100, inclusive.

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
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, JP

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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:

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, CA, IT, DE, JP

US, UK, CA, FR, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, CA, FR, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, CA, FR, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, CA, FR, IT, DE, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

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

US, UK, FR, CA, IT, DE, ES, JP

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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?

Last updated: Feb 13, 2024