Endpoint Settings REST API Reference

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

Use the Endpoint Settings REST API to view and update Alexa-connected endpoint settings, such device address, timezone, or do-not-disturb setting. You use the Endpoint Settings API along with the Endpoints REST API to view and change settings on devices owned by your Amazon Business account.

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

Important: When you update endpoint settings, the device must have an active connection to your Wi-Fi network and the internet for the update to complete successfully. The connection allows the device to complete an automatic reboot. Alexa Smart Properties retries the request for one hour.

API endpoint

Based on the country of your organization, set the Host parameter in the request header to one of the following API endpoints.

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). For details, see Manage API Access.

Operations

The Endpoint Settings API includes the following operations.

Operation	HTTP method and URI
Get multiple settings	`GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults}`
Get address setting	`GET /v2/endpoints/{endpointId}/settings/address`
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 ColorInversion setting	`GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement`
Get DistanceUnits setting	`GET /v2/endpoints/{endpointId}/settings/System.distanceUnits`
Get DoNotDisturb setting	`GET /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb`
Get ErrorSuppression setting	`GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression`
Get FollowUp setting	`GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode`
Get Locales setting	`GET /v2/endpoints/{endpointId}/settings/System.locales`
Get Magnifier setting	`GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement`
Get MaximumVolumeLimit setting	`GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit`
Get SetupModePrivileges setting	`GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.setupModePrivileges`
Get SpeakingRate setting	`GET /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate`
Get SpeechConfirmation setting	`GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation`
Get TemperatureUnit setting	`GET /v2/endpoints/{endpointId}/settings/System.temperatureUnit`
Get TimeFormat setting	`GET /v2/endpoints/{endpointId}/settings/Alexa.DataFormat.Time.timeFormat`
Get TimeZone setting	`GET /v2/endpoints/{endpointId}/settings/System.timeZone`
Get WakeWordConfirmation setting	`GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation`
Get WakeWords setting	`GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords`
Set address	`POST /v2/endpoints/{endpointId}/settings/address`
Update AlexaCaptions setting	`PUT /v2/endpoints/{endpointId}/settings/Accessibility.Captions.AlexaCaptions.enablement`
Update ClosedCaptions setting	`PUT /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement`
Update ColorInversion setting	`PUT /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement`
Update DistanceUnits setting	`PUT /v2/endpoints/{endpointId}/settings/System.distanceUnits`
Update DoNotDisturb setting	`PUT /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb`
Update ErrorSuppression setting	`PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression`
Update FollowUp setting	`PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode`
Update Locales setting	`PUT /v2/endpoints/{endpointId}/settings/System.locales`
Update Magnifier setting	`PUT /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement`
Update MaximumVolumeLimit setting	`PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit`
Update SpeakingRate setting	`PUT /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate`
Update SpeechConfirmation setting	`PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation`
Update TemperatureUnit setting	`PUT /v2/endpoints/{endpointId}/settings/System.temperatureUnit`
Update TimeFormat setting	`PUT /v2/endpoints/{endpointId}/settings/Alexa.DataFormat.Time.timeFormat`
Update TimeZone setting	`PUT /v2/endpoints/{endpointId}/settings/System.timeZone`
Update WakeWordConfirmation setting	`PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation`
Update WakeWords setting	`PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords`

Get multiple settings

Get the current values of more than one setting 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource and specify the settings in the query path. If you request multiple settings, the response might be paginated.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings?keys={settingName, settingName, ...}&nextToken={nextToken}&maxResults={maxResults}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`settingName`	Query	Comma separated list of setting names. You must specify at least one setting. Valid values: `Accessibility.Captions.AlexaCaptions.enablement`, `Accessibility.Captions.ClosedCaptions.enablement`, `Accessibility.Display.ColorInversion.enablement`, `Accessibility.Display.Magnifier.enablement`, `address`, `Alexa.DataFormat.Time.timeFormat`, `Alexa.DoNotDisturb.doNotDisturb`, `Alexa.ManagedDevice.Settings.errorSuppression`, `Alexa.ManagedDevice.Settings.maximumVolumeLimit`, `Alexa.ManagedDevice.Settings.setupModePrivileges`, `SpeechRecognizer.FollowUp`, `SpeechRecognizer.speechConfirmation`, `SpeechRecognizer.wakeWords`, `SpeechRecognizer.wakeWordConfirmation`, `System.distanceUnits`, `System.locales`, `System.temperatureUnit`, `System.timeZone`.	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. Default value: 100.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the requested settings for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The following example shows the response to a request for four settings: GET /v2/endpoints/{endpointId}/settings?keys=System.temperatureUnit,System.distanceUnits,Alexa.DoNotDisturb.doNotDisturb,System.timeZone.

{

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

Response body properties

Property	Description	Type
`settings`	Unordered list of requested setting values.	Array of objects
`settings[].key`	Setting name from request.	String
`settings[].value`	Setting value.	String
`errors`	(Optional) List of errors that occurred. Not included when all setting values retrieved successfully.	Array of objects
`errors[].key`	Setting name from request.	String
`errors[].status`	HTTP status code.	String
`errors[].code`	Identifies the error.	String
`errors[].message`	Human readable error message. Use for debugging and logging purposes only. You must not share it with the customer. No business logic should depend on the content of the error message.	String
`paginationContext`	(Optional) Wrapper for `nextToken`. Included when the response is paginated.	Object
`paginationContext.nextToken`	Identifies the next set of setting values to return. Use this value for the `nextToken` parameter in a subsequent Get multiple settings request.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the requested settings on the specified endpoint. If an individual setting fails, the response includes an `error` property.
`204 No content`	Setting exists, but the setting value is empty.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get address setting

Get the address setting for the specified endpoint. 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

To get the address, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/address
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

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

Response body properties

Property	Description	Type
`address`	Address of the specified endpoint.	Address object

HTTP status codes

Status	Description
`200 OK`	Response body contains the address setting for the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get AlexaCaptions setting

Get the Alexa caption setting for the specified endpoint.

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

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

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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.AlexaCaptions.enablement 
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the Alexa captions setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

"ENABLED"

Response body properties

Type	Description
String	Current value of the Alexa captions setting on the specified endpoint. Valid values: `DISABLED`, `ENABLED`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get ClosedCaptions setting

Get the closed caption setting for the specified endpoint. 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the closed captions setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

"ENABLED"

Response body properties

Type	Description
String	Current value of the closed captions setting on the specified endpoint. Valid values: `DISABLED`, `ENABLED`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get ColorInversion setting

Get the screen color inversion setting for the specified endpoint. 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the screen color inversion setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

"ENABLED"

Response body properties

Type	Description
String	Current value of the color inversion setting on the specified endpoint. Valid values: `DISABLED`, `ENABLED`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get DistanceUnits setting

Get the distance units (metric or imperial) setting 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/System.distanceUnits
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the distance units setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

"METRIC"

Response body properties

Type	Description
String	Current value of the distance units setting on the specified endpoint. Valid values: `IMPERIAL`, `METRIC`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get DoNotDisturb setting

Get the DoNotDisturb setting for the specified endpoint. This setting prevents notifications and proactive experiences, such as calls, from disturbing the user.

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

This operation is available in the following countries.

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

Request

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the do-not-disturb setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

true

Response body properties

Type	Description
Boolean	Current value of the do-not-disturb setting on the specified endpoint. If `true`, the do-not-disturb is on.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get ErrorSuppression setting

Get the list of errors that Alexa suppresses for the specified endpoint. This setting controls whether the device plays error audio cues, such as brief, distinctive sounds, when errors occur.

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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the error suppression setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

["CONNECTIVITY"]

Response body properties

Type	Description
Array of strings	List of errors suppressed on the specified endpoint. Valid values: `CONNECTIVITY`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get FollowUp setting

Get the follow-up mode setting for the specified endpoint. If enabled, this setting allows 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the follow-up mode setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

true

Response body properties

Type	Description
Boolean	Current value of the follow-up mode setting on the specified endpoint.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get Locales setting

Get the preferred locales for the specified endpoint. For Alexa-enabled devices, this setting controls which languages Alexa understands and responds with.

Note: If the setting includes more than one language, the first language in the list is the primary language for the device. Alexa displays text on Alexa-enabled devices with a screen in the primary language.

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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/System.locales
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the list of locales for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

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

Response body properties

Type	Description
Array of strings	List of up to two locale strings. The first element in the list is the preferred locale. Valid values: `ar-SA`, `de-DE`, `en-AU`, `en-CA`, `en-GB`, `en-IN`, `en-US`, `es-ES`, `es-MX`, `es-US`, `fr-CA`, `fr-FR`, `hi-IN`, `it-IT`, `ja-JP`, and `pt-BR`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get Magnifier setting

Get the magnifier setting for the specified endpoint. This setting gives the user the ability to enlarge items on Alexa-devices with a 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the magnifier setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

"ENABLED"

Response body properties

Type	Description
String	Current value of the magnifier setting on the specified endpoint. Valid values: `DISABLED`, `ENABLED`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get MaximumVolumeLimit setting

Get the maximum volume-limit setting 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the maximum volume-limit setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

Response body properties

Type	Description
Integer	Current value of the maximum volume-limit setting on the specified endpoint. Valid values: 0–100.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get SetupModePrivileges setting

Get the list of setup-mode privileges for the specified endpoint. This setting controls the user's ability to put a device into configuration mode by using 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.setupModePrivileges
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the list of setup-mode privileges for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

 ["ALL_SETTINGS"]

Response body properties

Type	Description
Array of strings	Current list of setup-mode privileges on the specified endpoint. An empty list shows that setup-mode is disabled for the endpoint. Valid values: `ALL_SETTINGS`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get SpeakingRate setting

Get the speaking-rate setting for the specified endpoint. This setting slows or increases Alexa's speech output to a preferred pace on an Alexa-enabled device.

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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the speaking-rate setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

0.75

Response body properties

Type	Description
Number	Current value of the speaking-rate setting on the specified endpoint. Default: `1` Valid values: `0.75`, `0.85`, `1`, `1.25`, `1.5`, `1.75`, `2`

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get SpeechConfirmation setting

Get the end-of-request sound setting for the specified endpoint. 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the end-of-request sound setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

"NONE"

Response body properties

Type	Description
String	Current value of the end-of-request speech confirmation setting on the specified endpoint. Valid values: `NONE`, `TONE`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get TemperatureUnit setting

Get the temperature scale setting 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/System.temperatureUnit
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the temperature scale setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

"FAHRENHEIT"

Response body properties

Type	Description
String	Current value of the temperature scale setting on the specified endpoint. Valid values: `CELSIUS`, `FAHRENHEIT`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get TimeFormat setting

Get the clock time-format setting 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/Alexa.DataFormat.Time.timeFormat
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the clock time-format setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

"24_HOURS"

Response body properties

Type	Description
String	Current value of the clock time-format setting on the specified endpoint. Valid values: `12_HOURS`, `24_HOURS`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get TimeZone setting

Get the time zone setting 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/System.timeZone
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the time zone setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

"America/Los_Angeles"

Response body properties

Type	Description
String	Current time zone setting on the specified endpoint. Formatted in the Olson time zone format. For more details, see Timezone Database.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get WakeWordConfirmation setting

Get the start-of-request wake-word confirmation setting for the specified endpoint. This setting specifies whether to play an audible tone 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the start-of-request wake-word confirmation setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

"NONE"

Response body properties

Type	Description
String	Current value of the start-of-request wake-word confirmation setting on the specified endpoint. Valid values: `NONE`, `TONE`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get WakeWords setting

Get the list of wake words enabled for the specified endpoint. This setting specifies the list of alternative wake words that 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

To get the setting, you make a GET request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the wake-word setting for the specified endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

["ALEXA"]

Response body properties

Type	Description
Array of strings	Current value of the wake-word setting on the specified endpoint. At this time, the list can contain one entry. Not all devices and locales support all wake words. `COMPUTER` isn't supported in France (`fr-FR`). Valid values: `ALEXA`, `AMAZON`, `COMPUTER`, `ECHO`.

HTTP status codes

Status	Description
`200 OK`	Response body contains the current value of the setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Set address

Set the address to the location of the endpoint. Alexa uses this setting for features like local search and weather. For details, see Enhance Your Skill With Address Information.

Note: The country of the address should match the country where you created your organization. For example, if an organization manages UK properties, set only UK addresses for endpoints within that organization.

This operation is available in the following countries.

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

Request

To create an address for the endpoint, you make a POST request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

POST /v2/endpoints/{endpointId}/settings/address
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

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

Request body properties

Property	Description	Type	Required
`address`	Address of the specified endpoint.	Address object	Yes

Response

A successful response returns HTTP 201 Created, along with device address. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The following example shows a successful address creation response.

When the address lookup finds differences from the address given in the request, the response includes address suggestions. In this example, the postal code is different from the postal code in the request.

When the request is missing any required parameters or malformed, the response includes address errors. In this example, the response code is HTTP 400 Bad Request.

Response body properties

Property	Description	Type
`address`	Address of the specified endpoint. Included on success	Address object
`addressSuggestions`	(Optional) List of address suggestions in descending order of confidence. Included for `Status 400 Bad Request`.	Array of Address objects
`addressErrors`	(Optional) List of address errors. Included for `Status 400 Bad Request`.	Array of objects
`addressErrors.code`	Error code that indicates whether a required address property is missing or an address property is invalid. The element name is specified by the `element` property. Valid values: `ELEMENT_REQUIRED`, `ELEMENT_INVALID`.	String
`addressErrors.Subcode`	Additional information about why an address property is invalid. For more details, see Address subCode values. Valid values: `ADDRESS_PRIMARY_RANGE_MISSING_OR_INVALID`, `ADDRESS_STREET_INCOMPLETE`, `ADDRESS_LINES_JUNK_DATA`, `ADDRESS_FIELD_LENGTH_HIGH`, `ADDRESS_CITY_INVALID`, `ADDRESS_COUNTY_INVALID`, `ADDRESS_STATE_INVALID`, `ADDRESS_ZIP_INVALID`, `ADDRESS_STREET_NOT_FOUND`, `ADDRESS_MULTIBYTE_CHARACTERS`, `ADDRESS_DOOR_LEVEL_INFO_MISSING`, `FIELD_EMPTY`.	String
`addressErrors.message`	Human readable error message. Use for debugging purposes only.	String
`addressErrors.element`	Address property to which the error applies. For more details, see Address element values Valid values: `ADDRESS_1`, `ADDRESS_2`, `ADDRESS_3`, `STREET_NAME`, `BUILDING_NUMBER`, `COMPLEMENT`, `NEIGHBORHOOD`, `CITY`, `STATE`, `COUNTRY`, `ZIP`, `COUNTY`, `COUNTRY_CODE`.	String

HTTP status codes

Status	Description
`201 Created`	Response body contains the address setting on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update AlexaCaptions setting

Update the Alexa caption setting on the specified endpoint.

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

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

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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/Accessibility.Captions.AlexaCaptions.enablement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

"ENABLED"

Request body properties

Type	Description	Required
String	Identifies the Alexa captions value to set on the specified endpoint. Valid values: `DISABLED`, `ENABLED`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update ClosedCaptions setting

Update the closed caption setting for the specified endpoint. 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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

"ENABLED"

Request body properties

Type	Description	Required
String	Identifies the closed captions value to set on the specified endpoint. Valid values: `DISABLED`, `ENABLED`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update ColorInversion setting

Update the screen color inversion setting for the specified endpoint. 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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

"ENABLED"

Request body properties

Type	Description	Required
String	Identifies the color inversion value to set on the specified endpoint. Valid values: `DISABLED`, `ENABLED`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update DistanceUnits setting

Update the distance units (metric or imperial) setting for the specified endpoint.

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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/System.distanceUnits
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

"METRIC"

Request body properties

Type	Description	Required
String	Identifies the Alexa distance units value to set on the specified endpoint. Valid values: `IMPERIAL`, `METRIC`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update DoNotDisturb setting

Update the DoNotDisturb setting for the specified endpoint. This setting prevents notifications and proactive experiences, such as call, 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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

true

Request body properties

Type	Description	Required
Boolean	Identifies the value of the do-not-disturb value to set on the specified endpoint. Set to `true` to turn on do-not-disturb. Set to `false` to turn off do-not-disturb.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update ErrorSuppression setting

Update the list of errors that Alexa suppresses for the specified endpoint. This setting controls whether the device plays error audio cues, such as brief, distinctive sounds, when errors occur.

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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

["CONNECTIVITY"]

Request body properties

Type	Description	Required
Array of strings	List of errors to suppress on the specified endpoint. Valid values: `CONNECTIVITY`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update FollowUp setting

Update the follow-up mode setting for the specified endpoint. If enabled, this setting allows 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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

false

Request body properties

Type	Description	Required
Boolean	Identifies the follow-up mode value to set on the specified endpoint. Set to `true` to turn on follow-up mode. Set to `false` to turn off follow-up mode.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update Locales setting

Update the preferred locales for the specified endpoint. For Alexa-enabled devices, this setting controls which languages Alexa understands and responds 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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/System.locales
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

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

Request body properties

Type	Description	Required
Array of strings	Locales to set on the specified endpoint. List of up to two locale strings. The first element in the list is the preferred locale. Valid values: `ar-SA`, `de-DE`, `en-AU`, `en-CA`, `en-GB`, `en-IN`, `en-US`, `es-ES`, `es-MX`, `es-US`, `fr-CA`, `fr-FR`, `hi-IN`, `it-IT`, `ja-JP`, and `pt-BR`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update Magnifier setting

Update the magnifier setting for the specified endpoint. This setting gives the user the ability to enlarge items on Alexa-devices with a 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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

"ENABLED"

Request body properties

Type	Description	Required
String	Identifies the magnifier value to set on the specified endpoint. Valid values: `DISABLED`, `ENABLED`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update MaximumVolumeLimit setting

Update the maximum volume-limit setting for the specified endpoint.

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

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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

Request body properties

Type	Description	Required
Integer	Identifies the maximum volume-limit value to set on the specified endpoint. Valid values: 0–100.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update SpeakingRate setting

Update the speaking-rate setting for the specified endpoint. This setting adjusts Alexa's speech to a preferred pace on an Alexa-enabled device.

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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

0.85

Request body properties

Type	Description	Required
Number	Identifies the speaking-rate value to set on the specified endpoint. Default: `1` Valid values: `0.75`, `0.85`, `1`, `1.25`, `1.5`, `1.75`, `2`	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update SpeechConfirmation setting

Update the end-of-request sound confirmation setting for the specified endpoint. 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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

"TONE"

Request body properties

Type	Description	Required
String	Identifies the end-of-request speech confirmation value to set on the specified endpoint. Valid values: `NONE`, `TONE`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update TemperatureUnit setting

Update the temperature scale setting for the specified endpoint

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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/System.temperatureUnit
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

"CELSIUS"

Request body properties

Type	Description	Required
String	Identifies the temperature scale value to set on the specified endpoint. Valid values: `CELSIUS`, `FAHRENHEIT`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update TimeFormat setting

Update the clock time-format setting for the specified endpoint.

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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/Alexa.DataFormat.Time.timeFormat
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

"12_HOURS"

Request body properties

Type	Description	Required
String	Identifies the clock time-format value to set on the specified endpoint. Valid values: `12_HOURS`, `24_HOURS`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update TimeZone setting

Update the time zone setting for the specified endpoint.

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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/System.timeZone
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

"America/New_York"

Request body properties

Type	Description	Required
String	Identifies the time zone value to set on the specified endpoint. Formatted in the Olson time zone format. For more details, see Timezone Database.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update WakeWordConfirmation setting

Update the start-of-request wake-word confirmation setting for the specified endpoint. This setting specifies whether to play an audible tone 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

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

"TONE"

Request body properties

Type	Description	Required
String	Identifies the start-of-request wake-word confirmation value to set on the specified endpoint. Valid values: `NONE`, `TONE`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update WakeWords setting

Update the list of wake words enabled for the specified endpoint. This setting specifies the list of alternative wake words that the user can say to wake up Alexa.

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

This operation is available in the following countries.

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

Request

To update the setting, you make a PUT request to the /v2/endpoints/{endpointId}/settings resource.

Request path and header example

Copied to clipboard.

PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

["ECHO"]

Request body properties

Type	Description	Required
String	Identifies the wake-word value to set on the specified endpoint. At this time, the list can contain one entry. Not all devices and locales support all wake words. `COMPUTER` isn't supported in France (`fr-FR`). Valid values: `ALEXA`, `AMAZON`, `COMPUTER`, `ECHO`.	Yes

Response

A successful response returns HTTP 204 No content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No content`	Setting applied successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`405 Method Not Allowed`	Indicates that the resource doesn't support the specified setting.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Object definitions

The Endpoint Settings API defines the following object definitions and property values.

Address

The Address object describes the location of the specified endpoint device.

Property	Description	Type	Required
`addressLine1`	First line of the address. You can set this property to an empty string.	String	Yes
`addressLine2`	Second line of the address. You can set this property to an empty string.	String	Yes
`addressLine3`	Third line of the address. You can set this property to an empty string.	String	Yes
`city`	City name.	String	Yes
`stateOrRegion`	Abbreviation for the state, province, or region associated with the endpoint. You can set this property to an empty string for non-US countries.	String	Yes
`districtOrCounty`	District or county associated with the endpoint. You can set this property to an empty string for non-US countries.	String	Yes
`postalCode`	Postal code or zip code.	String	Yes
`countryCode`	Two-letter country or region code.	String	Yes

Address subCode values

The subCode property provides additional information about why an address element isn't valid. The following table lists the subCode values.

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, or state.
`ADDRESS_STREET_NOT_FOUND`	The street wasn't 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

The following table lists the valid values for the address element property.

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

Was this page helpful?

Provide feedback

Last updated: frontmatter-missing