Endpoint API

About endpoints

An endpoint represents an Alexa-connected device (like an Echo device) with which an Alexa customer can interact. In Alexa for Residential, you manage your Echo devices using the /v2/endpoints APIs. With these APIs, you can enumerate the devices owned by your Amazon Business account; view and change settings; and associate endpoints with specific homes.

Enumerate endpoints

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

Request format examples

The following examples show how to use this call.

Enumerate endpoints that aren't associated with a unit

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

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

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

Enumerate endpoints associated with a unit

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

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

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.id filter parameter is present)
associatedUnits.id Filter endpoints to only those endpoints that are associated with a particular unit. String Yes (Unless an owner filter parameter is present)
nextToken Token used for getting the next page of results. String No
maxResults Maximum number of results to display. The value of this parameter must be between 1 and 10. Default is 10. Integer No
expand An attribute (or set of attributes) to include in the response. Current values supported: all, feature:speaker, 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 No
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

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. 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. String 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
features List of feature objects for this endpoint. List No
associatedUnits List of unit objects for the units that the endpoint is associated with. If the endpoint isn't associated with any units, the list is empty. List Yes
operations List of supported operations. List No
paginationContext Object containing pagination information. 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". String
value The name value, as a Value object. Object

Value object

Field Description Type
text The string value. String

Connection object

Field Description Type
type The type of connection. Currently the only supported value is TCP_IP. String
macAddress The unique identifier for the network interface controller. String

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

Unit object

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

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

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 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 device-to-unit association

POST associatedUnits

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

Request format

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

Request path parameters

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

Request body

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

Request body parameters

Field Description Type Required
associatedUnit The unit to be associated with the endpoint, as a Unit object. Object 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

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 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 the endpoint status

Once the associate API is called and a 200 code is returned, 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.

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

Request example

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

DELETE associatedUnits

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

Request format

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

Request path parameters

Field Description Type Required
endpointId The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}". String Yes
unitId The unit ID, in the format "amzn1.alexa.unit.did.{id}". 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 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 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 connectivity feature

GET features/connectivity

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

Request format

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

Request body

None.

Request path parameters

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",
            "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 Yes
timeOfSample The time when the property value was retrieved. Date Yes
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 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 speaker feature

GET features/speaker

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

Request format

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

Request body

None.

Request path parameters

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

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
value The current volume, for example, 42. Valid range is from 0 to 100. Integer Yes
timeOfSample The time when the property value was retrieved. Date Yes
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 speaker property: "DEVICE_UNREACHABLE" or "INTERNAL_ERROR". String Yes
message The name of the property, for example, "volume". String Yes

Operation object schema

Field Description Type Required
name The operation name: "setVolume" or "adjustVolume" String Yes
path The full path that can be used to set some of the speaker-feature properties. 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.
404 Not found The requested artifact wasn't found for the client.
429 Too many requests 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.

speaker operations

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

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

Request format

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

Request path parameters

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

Get endpoint setting value

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

Supported settings

The following settings are supported.

Setting Name Description Response Fields Response Field Description Response Field Type
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 support all wake words. List
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
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 is supported. 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

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

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

Get DoNotDisturb setting

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

Request format

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

Request path parameters

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.

Request format

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

Request path parameters

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

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

Response body value

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

Error response

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

Error response parameters

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.

Request format

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

Request path parameters

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 support all wake words.

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.

Request format

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

Request path parameters

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.

Request format

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

Request path parameters

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

Request format

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

Request path parameters

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.

Request format

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

Request path parameters

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.

Request format

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

Request path parameters

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.

Request format

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

Request path parameters

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.

Request format

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

Request path parameters

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.

Put endpoint setting value

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

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 support all wake words. List
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
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 is supported. If the list is empty ([]), no errors are suppressed. List
Alexa.ManagedDevice.Settings.setupModePrivileges Put the setupModePrivileges setting. This setting controls the end user's ability to put the 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 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

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

Request format

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

Response body

None.

Error response

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

Error response parameters

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.

Request format

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

Request path parameters

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": {
    "items": [
      {
        "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": {
    "items": [
      {
        "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 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.

Put DoNotDisturb setting

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

Request format

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

Request path parameters

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.

Request format

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

Request path parameters

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

Request body example

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

Request body value

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.

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.

Request format

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

Request path parameters

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"]. Alexa supported wake words are, ALEXA, AMAZON, COMPUTER, and ECHO. Currently you can only specify one wake word at a time. Note: Not all devices support all wake words.

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.

Request format

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

Request path parameters

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.

Request format

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

Request path parameters

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

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

Request format

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

Request path parameters

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

Request body example

   ["ALL_SETTINGS"]

Request body value

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

Response header

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

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

Request format

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

Request path parameters

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.

Request format

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.

Request format

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.

Request format

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.

Deregister endpoint

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

Request format

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

Request format

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

Request format

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