Endpoint API
An endpoint represents an Alexa-connected device (like an Echo device) with which an Alexa customer can interact. In Alexa Smart Properties, you manage your Echo devices using the Alexa Smart Properties endpoint API. With this API, you can enumerate the devices owned by your Amazon Business account; view and change settings; and associate endpoints with specific rooms.
API endpoint
In the request header, set Host
to one of the following, depending on the region of your organization:
Country | Endpoint |
---|---|
CA, US |
|
DE, ES, FR, IT, UK |
|
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).
Operations
The Endpoint API includes the following operations.
Operation | HTTP Method and URI |
---|---|
| |
| |
| |
| |
| |
Note: This operation uses a different endpoint from the other operations in the Endpoints API.
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
Get endpoints
The following operations enable you to get information about endpoints.
Get all endpoints
Gets the list of endpoints that you registered to your Amazon Business account.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request
Call GET /v2/endpoints?owner=~caller
to get the list of endpoints that you registered to your Amazon Business account.
Request format examples
Get all endpoints that aren't associated with a unit
The following example lists the endpoints owned by the caller that aren't associated with a unit. By default, the results aren't expanded.
This call only returns endpoints that are not associated with any units. To get all endpoints associated with a specific unit, see Get all endpoints associated with a unit.
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints?owner=~caller HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Include details for each endpoint
This example shows how to include details for each endpoint, use the following expand=all
parameter.
GET /v2/endpoints?owner=~caller&expand=all HTTP/1.1
Include connectivity for each endpoint
To include connectivity
details for each endpoint, use the following expand=feature:connectivity
parameter.
GET /v2/endpoints?owner=~caller&expand=all&expand=feature:connectivity
Get all endpoints associated with a unit
To get all endpoints associated with a particular unitId
that the caller has permission to access, provide the associatedUnits.id={unitId}
parameter.
GET /v2/endpoints?associatedUnits.id={unitId}&expand=all
Request query parameters
Field | Description | Type | Required |
---|---|---|---|
owner |
Filter endpoints to only those endpoints that the caller owns. The only value currently supported is "~caller" , that represents the customer information in the bearer token.Note: you must include either the owner filter or the associatedUnits.id filter. |
String | Yes (Unless an associatedUnits or serialNumber.value.text filter is specified) |
associatedUnits.id |
Filter endpoints to only those endpoints that are associated with a particular unit. | String | Yes (Unless an owner or serialNumber.value.text filter parameter is specified) |
nextToken |
Token used for getting the next page of results. For details, see Handling Pagination in Query Results. | String | No |
maxResults |
Maximum number of results to display. The value of this parameter must be between 1 and 50. Default is 10. | Integer | No |
expand |
An attribute (or set of attributes) to include in the response. Current values supported: all , feature:brightness , feature:color , feature:colorTemperature , feature:speaker , feature:temperatureSensor , feature:thermostat , feature:power , and feature:connectivity .Note: You can provide multiple values for expand, for example, expand=all&expand=feature.connectivity . |
String | No |
manufacturer.value.text |
Filter endpoints to only those endpoints whose manufacturer.value.text exactly matches the full text of the specified value.Note: To filter on this field, it must be included in the response. For example, expand=All . |
String | No |
model.value.text |
Filter endpoints to only those endpoints whose model.value.text exactly matches the full text of the specified value. |
String Note: To filter on this field, it must be included in the response. For example, expand=All . |
No |
serialNumber.value.text |
Filter endpoints to only those endpoints whose serialNumber.value.text exactly matches the full text of the specified value.Note: To filter on this field, it must be included in the response. For example, expand=All . |
String | Yes (Unless an owner or associatedUnits filter parameter is specified) |
friendlyName.value.text |
Filter endpoints to only those endpoints whose friendlyName.value.text exactly matches the full text of the specified value.Note: To filter on this field, it must be included in the response. For example, expand=All . |
String | No |
connections.macAddress |
Filter endpoints to only those endpoints whose macAddress exactly matches the specified value.Note: To filter on this field, it must be included in the response. For example, expand=All . |
String | No |
features[name:connectivity].properties[name:reachability].value.value |
Filter endpoints to only those endpoints whose reachability value exactly matches the specified value.Note: This requires that the feature is expanded, for example, expand=feature:connectivity . For an example of how to use this filter in an API call, see the following request example. |
String | No |
displayCategories.primary.value |
Filter endpoints to only those endpoints with a primary display category matching the specified value. | String | No |
displayCategories.all.value |
Filter endpoints to only those endpoints with a display category matching the specified value. | String | No |
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body parameters
Field | Description | Type | Required |
---|---|---|---|
results |
List of endpoints returned in response to the query. Note: The ordering of this list might change depending on the query parameters provided in the request. |
List | Yes |
id |
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}" . |
String | Yes |
manufacturer |
The endpoint manufacturer, as a NameValue object. | Object | No |
model |
The endpoint model, as a NameValue object. |
Object | No |
serialNumber |
The endpoint serial number, as a NameValue object. |
Object | No |
friendlyName |
The friendly name for the endpoint, as a NameValue object. |
Object | No |
softwareVersion |
The software version for the endpoint, as a NameValue object. |
Object | No |
connections |
The methods that an endpoint can use to connect to the internet and smart home hubs, represented as a list of Connection objects. If no connection is associated with the endpoint, this field is empty. | List | No |
creationTime |
The time when the endpoint resource was first created. | ISO 8601 Date | No |
features |
List of Feature objects for this endpoint. | List | No |
associatedUnits |
List of Unit objects for the units that the endpoint is associated with. Returned only if expand=all was specified in the request. If the endpoint isn't associated with any units, the list is empty. |
List | No |
operations |
List of Operation for supported operations. | List | No |
displayCategories |
Display Categories object. | ||
paginationContext |
Pagination context object. If present, the response contains incomplete results. If omitted, all results were already returned. | Object | No |
NameValue object
Field | Description | Type |
---|---|---|
type |
The name value type. Currently the only supported value is "PLAIN" , indicating that the value property contains the plaintext value for this property. |
String |
value |
The name value, as a Value object. |
Object |
Example
"model": {
"type": "PLAIN",
"value": {
"text":"Amazon Echo"
}
Value object
Field | Description | Type |
---|---|---|
text |
The string value. | String |
Connection object
Field | Description | Type |
---|---|---|
type |
The type of connection. Following are the supported values: TCP_IP , ZIGBEE , and UNKNOWN . |
String |
macAddress |
The unique identifier for the network interface controller. | String |
Example
{
"type": "TCP_IP",
"macAddress": "141AC1534151"
}
Feature object
Field | Description | Type |
---|---|---|
type |
The name of the feature, for example, "volume" or "speaker" . |
String |
path |
The full path to use for retrieving expand results of this feature, for example, "/v2/endpoints/{endpointID}/features/speaker" . |
String |
Example
{
"name": "speaker",
"path" : "/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/speaker"
}
Unit object
Field | Description | Type |
---|---|---|
id |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String |
Example
{
"id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
}
Display categories object
Field | Description | Type |
---|---|---|
primary |
The primary categories of the endpoint. | Display Category object. |
all |
All categories of the endpoint. | Array |
Example
"displayCategories": {
"primary": {
"value": "ALEXA_VOICE_ENABLED",
"sources": [
"ENDPOINT_REPORTER"
]
},
"all": [
{
"value": "ALEXA_VOICE_ENABLED",
"sources": [
"ENDPOINT_REPORTER"
]
}
]
}
Display category object
Field | Description | Type |
---|---|---|
value |
The category in string form. | String |
sources |
The source of this display category. "CUSTOMER" means the customer explicitly set this value. "ENDPOINT_REPORTER" means this value was reported as part of the original endpoint report. | Array |
Example
{
"value": "LIGHT",
"sources": ["CUSTOMER", "ENDPOINT_REPORTER"]
}
Pagination context object
Field | Description | Type |
---|---|---|
nextToken |
Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. |
String |
Example
{
"nextToken": "ABCD123"
}
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
400 | Bad Request | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The access token is valid, but the user doesn't have the needed LWA scope permissions. |
429 | Too many requests | The request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received. |
503 | Service Unavailable | Service is temporarily unavailable. |
Get an endpoint
Gets an endpoint and list values for all endpoint attributes the caller has permission to access.
The caller must have access to the endpoint. This request doesn't require filtering parameters such as owner
.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request
Call GET /v2/endpoints/{endpointId}?expand=all
to retrieve an endpoint and list values for all endpoint attributes the caller has permission to access.
Request format examples
The following examples show how to use this call.
List endpoint ID only
The following example lists only the endpoint ID for the endpoint.
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
{
"id": "amzn1.alexa.endpoint.A234ajd9..."
}
List all attributes
The following example lists all the endpoint's attributes.
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}?expand=all HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
List all attributes and speaker
feature
The following example lists all the endpoint's attributes and the speaker
feature.
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}?expand=all&expand=feature:speaker HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request query parameters
Field | Description | Type | Required |
---|---|---|---|
expand |
An attribute (or set of attributes) to include in the response. Current values supported: all , feature:brightness , feature:color , feature:colorTemperature , feature:speaker , feature:temperatureSensor , feature:thermostat , feature:power , and feature:connectivity .Note: You can provide multiple values for expand, for example, expand=all&expand=feature.connectivity . |
String | No |
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body parameters
Field | Description | Type | Required |
---|---|---|---|
id |
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}" . |
String | Yes |
friendlyName |
The friendly name for the endpoint, as a NameValue object. | Object | Yes |
manufacturer |
The endpoint manufacturer, as a NameValue object. |
Object | Yes |
model |
The endpoint model, as a NameValue object. |
Object | yes |
serialNumber |
The endpoint serial number, as a NameValue object. |
Object | Yes |
softwareVersion |
The software version for the endpoint, as a NameValue object. |
Object | Yes |
connections |
The methods that an endpoint can use to connect to the internet and smart home hubs, represented as a list of Connection objects. If no connection is associated with the endpoint, this field is empty. | List | No |
creationTime |
The time when the endpoint resource was first created. | ISO 8601 Date | No |
features |
List of Feature objects for this endpoint. | List | No |
associatedUnits |
List of Unit objects for the units that the endpoint is associated with. Returned only if expand=all was specified in the request. If the endpoint isn't associated with any units, the list is empty. |
List | No |
displayCategories |
Display Categories object. | ||
operations |
List of Operation objects for supported operations. | List | No |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type for the error. Present only if the request was valid but the service failed to execute the request. This field can be used by business logic. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
HTTP response codes
Status code | Name | Description |
---|---|---|
200 | Success | The request succeeded. |
400 | Bad Request | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | Authentication failed. |
404 | Not Found | The endpoint in the path doesn't exist, or the endpoint ID is invalid. |
429 | Too Many Requests | The request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received. |
503 | Service Unavailable | Service is temporarily unavailable. |
Query endpoints (advanced search)
Call POST /v2/endpointQuery
to get a list of endpoints that meet the conditions that you specify. This operation supports queries by unit, manufacturer, and model.
You can construct the query with multiple AND or OR clauses. For example, you can search for endpoints that satisfy the following conditions: (unit ID = amzn1.alexa.unit.unitOne
OR amzn1.alexa.unit.unitTwo
) AND a manufacturer name of someManufacturer
.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request
To query endpoints, you make a POST
request to the /v2/endpointQuery
resource.
Request header example
POST /v2/endpointQuery HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
String |
Yes |
Request body example
The following request queries endpoints in two units.
{
"query": {
"or": [
{
"match": {
"associatedUnits.id": "amzn1.alexa.unit.did.unitOne"
}
},
{
"match": {
"associatedUnits.id": "amzn1.alexa.unit.did.unitTwo"
}
}
]
},
"paginationContext": {
"maxResults": 50,
"nextToken": "WncIu8IrscO..."
},
"expand": [
"all", "feature:connectivity"
]
}
The following request queries endpoints in two units, filtered by device manufacturer.
{
"query": {
"and": [
{
"or": [
{
"match": {
"associatedUnits.id": "amzn1.alexa.unit.did.unitOne"
}
},
{
"match": {
"associatedUnits.id": "amzn1.alexa.unit.did.unitTwo"
}
}
]
},
{
"match": {
"manufacturer.value.text": "Amazon"
}
}
]
},
"paginationContext": {
"maxResults": 50,
"nextToken": "WncIu8IrscO..."
},
"expand": [
"all", "feature:power"
]
}
The following request queries endpoints in two units, filtered by device manufacturer and model.
{
"query":{
"and":[
{
"or":[
{
"match":{
"associatedUnits.id":"amzn1.alexa.unit.did.unitOne"
}
},
{
"match":{
"associatedUnits.id":"amzn1.alexa.unit.did.unitTwo"
}
}
]
},
{
"match":{
"manufacturer.value.text":"Amazon"
}
},
{
"match":{
"model.value.text":"Echo Dot (3rd generation)"
}
}
]
},
"paginationContext":{
"maxResults":50,
"nextToken":"WncIu8IrscO..."
},
"expand":[
"all",
"feature:power"
]
}
Request body parameters
Parameter | Description | Type | Required |
---|---|---|---|
|
Object that provides filtering conditions for the query. The fields can be either |
Object |
Yes |
|
Query that logically joins two or more parameters by using the |
Array |
No |
|
Object that contains specific query fields whose values must exactly match the corresponding value in the returned endpoints. You can specify the following types of values: |
Object |
No |
|
Query that logically joins two or more parameters by using the |
Array |
No |
|
Object that contains specific query fields whose values must exactly match the corresponding value in the returned endpoints. You can specify the following types of values: |
Object |
No |
|
Pagination context for the result. |
Object |
No |
|
Token to retrieve a specific page of the paginated results. If this token isn't present, the response contains the first page of results. |
String |
No |
|
Maximum number of results to return in the response body. This value must be greater than 1 and less than or equal to 10. |
Number |
No |
|
Array you use to expand endpoints by top-level attributes based on the specified group. Currently, all endpoint attributes are in the |
Array |
Optional |
Response
A successful response returns HTTP 200
.
Response body example
The following example shows a result of using this operation with feature:connectivity
in the expand
array.
The following example shows a result of using this operation to find endpoints for the associatedUnits.id
.
Response body parameters
Parameter | Description | Type |
---|---|---|
|
List of endpoints returned in response to the query. The ordering of this list might change depending on the query parameters provided in the request. |
Array |
|
Endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
|
Friendly name for the endpoint, as a |
Object |
|
Endpoint manufacturer, as a NameValue object. |
Object |
|
Endpoint model, as a |
Object |
|
Endpoint serial number, as a |
Object |
|
Software version for the endpoint, as a |
Object |
|
Methods that an endpoint can use to connect to the internet and smart home hubs, represented as a list of Connection objects. If no connection is associated with the endpoint, this field is empty. |
Array |
|
Time when the endpoint resource was first created. |
ISO 8601 Date |
|
List of Feature objects for this endpoint. |
Array |
|
List of Unit objects for the units that the endpoint is associated with. Returned only if |
Array |
|
List of Operation objects for supported operations. |
Array |
|
Display Categories object. |
Object |
|
Pagination context object. If present, the response contains incomplete results. If omitted, all results were already returned. |
Object |
HTTP status codes
Status | Description |
---|---|
|
The request succeeded. |
|
The request is malformed or is missing any required parameters. |
|
Authorization token is invalid, expired, or doesn't have access to the resource. |
|
The request couldn't complete because of the client doesn't have permission to perform the operation. |
|
The requested endpoint wasn't found. |
|
User has exceeded the permitted rate limit (specified number of requests per unit of time). |
|
A server-side error occurred. |
|
The service is temporarily unavailable. |
Manage endpoint-to-unit association
PUT associatedUnits
Call PUT /v2/endpoints/{endpointId}/associatedUnits
to update the list of associated units for an endpoint. You also use this API to disassociate endpoints from units.
Keep in mind the following important details:
- The endpoint must have an active connection when changing unit associations. Keep the device powered on and online for one minute after successfully calling this API.
- Currently, an endpoint can only be associated with one unit at a time.
- After you associate a device to a room, the friendly name of the device might change. For example, "Mary's device" might change to "Guest's device."
- To disassociate an endpoint from a room, call
PUT /v2/endpoints/{endpointId}/associatedUnits
, and specify your default unit wildcard"~caller.defaultUnitId"{{ }}
. - You should only apply settings after a device is associated with a unit. Any settings that have been applied to a device are cleared when its unit association is updated. After you call the PUT
associatedUnits
API and receive a 200 return code, you should confirm that the endpoint was successfully restarted. See Query the endpoint status. - When you change unit associations for an endpoint, the
endpointId
might change. The newendpointId
is returned in the response.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/associatedUnits HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
[
{
"id": "amzn1.alexa.unit.did.{id}"
}
]
Request body using default unit ID wildcard
[
{
"id": "~caller.defaultUnitId"
}
]
Request body parameters
Field | Description | Type | Required |
---|---|---|---|
List of Unit objects | The list of units to associate with the endpoint. Each element in the array is a unit ID, in the format "amzn1.alexa.unit.did.{id}" . To specify the caller's default unit, use the "~caller.defaultUnitId" wildcard. Currently an endpoint can only be associated with one unit at a time.Note: To remove an endpoint from a unit and return it to the caller's Amazon Business account, associate the endpoint with the caller's default unit. |
Array | Yes |
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
{
"endpoint": {
"id": "amzn1.alexa.endpoint.ABC123...",
"associatedUnits": [{
"id": "amzn1.alexa.unit.did.ZXY987..."
}]
}
}
Response body parameters
Field | Description | Type | Required |
---|---|---|---|
endpoint.id |
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}" . Note: When you change unit associations for an endpoint, the endpointId might change. If it changes, this field contains the new endpointId . |
String | Yes |
associatedUnits |
List of Unit objects for the units that the endpoint is associated with. Currently an endpoint can only be associated with one unit at a time. | List | Yes |
associatedUnits[].id |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String | Yes |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type for the error. Present only if the request was valid but the service failed to execute the request. This field can be used by business logic. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | NO_SUCH_UNIT | No such unit | The unit provided in the body does not exist. |
400 | TOO_MANY_UNIT_ASSOCIATIONS | The request exceeds the maximum number of unit IDs. | The request exceeds the maximum number of unit IDs. Try specifying fewer unit IDs. |
400 | ENDPOINT_UNREACHABLE | The endpoint is unreachable. | The endpoint is offline. Modifying associatedUnits is not permitted because the device is unreachable. |
400 | ENDPOINT_NOT_SUPPORTED | Modifying associatedUnits is not supported for this endpoint. |
Modifying associatedUnits is not supported for this device type. |
400 | TOO_FEW_UNIT_ASSOCIATIONS | The request specifies too few unit IDs. | You must provide at least one unit ID. |
401 | UNAUTHORIZED | Invalid or missing access token | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The client can list the resource but doesn't have permission to rename the resource. |
404 | NO_SUCH_ENDPOINT | Endpoint not found | The endpoint in the path doesn't exist, or the client doesn't have permission to list the resource. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. Retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until you receive a non-429 response. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. Retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until you receive a non-500 response. |
503 | SERVICE_UNAVAILABLE | Service Unavailable | The service is temporarily unavailable to handle the request. |
Query the endpoint status
After you've called the PUT associatedUnits
API and received a 200 code, the process to associate the endpoint with the unit is complete on the cloud side. However, the physical endpoint must complete an automatic reboot to complete the endpoint-to-unit association on the endpoint side. There are no steps required to automatically reboot the endpoint.
To check if the endpoint has successfully rebooted, you can poll for the connectivity status of the endpoint. We recommend a polling interval of 2 minutes or greater.
When this API returns an endpointId
, the endpoint has successfully rebooted and reconnected to the network.
Request example
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints?associatedUnits.id=amzn1.alexa.unit.did.foo&connections.macAddress=00:11:22:AA:BB:33:44:55&features[name:connectivity].properties[name:reachability].value.value=OK HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Manage connectivity
feature
GET features/connectivity
Call GET /v2/endpoints/{endpointId}/features/connectivity
to get states and attributes related to connectivity of the endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/features/connectivity HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request body
None.
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
{
"properties": [
{
"name": "reachability",
"type": "RETRIEVABLE",
"value": {
"value": "OK"
},
"timeOfSample": "2020-07-20T00:00:00Z"
}
]
}
Response body parameters
Field | Description | Type | Required |
---|---|---|---|
name |
The name of the property, in this case "reachability" . |
String | Yes |
value |
"OK" if the endpoint is reachable, or "UNREACHABLE" otherwise. |
String | No |
timeOfSample |
The time when the property value was retrieved. | Date | No |
error |
The presence of this field shows that an error occurred during property value retrieval. | Object | No |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
HTTP response codes
Status code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
400 | Bad Request | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The access token is valid, but the user doesn't have the needed LWA scope permissions. |
429 | Too many requests | The request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received. |
503 | Service Unavailable | Service is temporarily unavailable. |
Manage Wi-Fi settings
Manage Wi-Fi configuration for Alexa endpoints and track status. To use these requests, you'll need an LWA token with "credential_locker::wifi_management"
and "alexa::enterprise:management"
scopes.
POST saveWifiConfigurations
Call POST /credentiallocker/v2/saveWifiConfigurations
to save Wi-Fi configurations for later use with an endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, DE, ES, FR, IT, UK |
US, CA, DE, ES, FR, IT, UK |
US |
In the request header, set Host
to one of the following, depending on the region of your organization:
Country | Endpoint |
---|---|
CA, US |
|
DE, ES, FR, IT, UK |
|
Note that this endpoint is different from the other operations in the Endpoints API.
Request format
POST /credentiallocker/v2/saveWifiConfigurations HTTP/1.1
Host: credential-locker-service.amazon.com
x-amz-access-token: {LWA Token}
Content-Type: application/json
Authorization: Bearer {LWA Token}
Request body format
The following example shows the request body for WPAPSK.
{
"wifiConfigurations": [
{
"credentialConfiguration": {
"privateSharedKey": "\"wifi-password\""
},
"ssid": "\"wifi-ssid\"",
"keyManagement": "WPAPSK"
}
]
}
The following example shows the request body for WPA2_EAP.
{
"wifiConfigurations": [
{
"credentialConfiguration": {
"eapAuthenticationMethod": "EAP_TLS",
"certificateAuthority": {
"providerName": "ALEXA_ENTERPRISE",
"id": "amzn1.alexa.enterprise.certificateAuthority.did.EXAMPLE_ID_VALUE"
},
"authenticationServerCertificates": [
"-----BEGIN CERTIFICATE-----\nCERTIFICATE_CONTENT\nMULTIPLE_LINES_WITH_LINE_BREAK_CHARACTERS\n-----END CERTIFICATE-----",
"-----BEGIN CERTIFICATE-----\nCERTIFICATE_CONTENT\nMULTIPLE_LINES_WITH_LINE_BREAK_CHARACTERS\n-----END CERTIFICATE-----"
]
},
"ssid": "\"wifi-ssid\"",
"keyManagement": "WPA2_EAP"
}
]
}
Request body parameters
Field | Description | Type | Required |
---|---|---|---|
|
Private shared key. Must be enclosed in double quotation marks. |
String |
Yes |
|
Identifies which EAP method will be used. Currently only EAP-TLS is supported. |
String |
Yes |
|
Identifies the certificate authority by its provider and the ID of the resource |
Object |
Yes |
|
Identifies the provider of the certificate issuer |
String |
Yes |
|
Identifies the ID of the certificate authority resource within the provider's system |
String |
Yes |
|
List of certificates provided by the authentication server used to validate the identity of the WPA2-Enterprise network. |
List |
Yes |
|
Wifi configuration network name. Must be enclosed in double quotation marks. |
String |
Yes |
|
Wifi configuration security type.
|
String |
Yes |
HTTP response codes
Status code | Type Description | |
---|---|---|
200 | OK | Successfully saved the Wi-Fi configurations. |
400 | BAD_REQUEST | The request is malformed or is missing one or more required parameters. |
401 | UNAUTHORIZED | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | The user isn't authorized to perform the operation. |
500 | INTERNAL_SERVER_ERROR | A service error occurred. |
POST addOrUpdateWifiConfigurations
Call POST /v2/endpoints/endpointId/features/connectivity/addOrUpdateWifiConfigurations
to associate saved Wi-Fi configurations with an endpoint. You can associate up to 32 Wi-Fi configurations with each endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, UK, DE, FR, IT, ES |
US, CA, UK, DE, FR, IT, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.POST /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer {LWA Token}
Content-Type: application/json
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
endpointId |
The endpoint ID returned by the Get all endpoints call. | String | Yes |
Request body format
{
"payload": {
"wifiConfigurations": [{
"ssid": "\"wifi-ssid\"",
"keyManagement": "WPAPSK"
}]
}
}
Request body parameters
Field | Description | Type | Required |
---|---|---|---|
ssid |
Wifi configuration network name. Must be enclosed in double quotation marks. Must be the same value used in the call to |
String |
Yes |
keyManagement |
Wifi configuration security type. Must be the same value used in the call to
|
String |
Yes |
Response body format
{
"submittedOperationId": "{operationId}"
}
Response body parameters
Field | Description | Type | Required |
---|---|---|---|
submittedOperationId |
An identifier to be used for retrieving the status of the operation | String | Yes |
HTTP response codes
Status code | Type Description | |
---|---|---|
202 | OK | Successfully initiated the Wi-Fi installation operation and returned the operationId for tracking the status in the response body. |
400 | BAD_REQUEST | The request is malformed or is missing one or more required parameters. |
400 | INVALID_CA_CERTIFICATE | A certificate cannot be issued for this request as the certificate authority certificate will expire or has expired before the expiration time of the issued certificate. |
400 | INVALID_CA_STATUS | The certificate authority linked to this SSID is not in an ACTIVE state and will not be able to issue a certificate for this request. |
400 | ENDPOINT_NOT_SUPPORTED | Adding or updating Wi-Fi configurations remotely is not supported for the specified endpoint. |
400 | TOO_MANY_CONFIGURATIONS | Request must contain exactly one Wi-Fi configuration. |
400 | INVALID_CONFIGURATION | Request contains invalid Wi-Fi configuration format. |
401 | UNAUTHORIZED | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Either the device endpoint wasn't found, or the specified Wi-Fi configuration wasn't found. |
404 | NO_SUCH_ENDPOINT | Endpoint not found. |
404 | NO_SUCH_CONFIGURATION | No matching Wi-Fi configuration found. |
500 | INTERNAL_SERVER_ERROR | A service error occurred. |
504 | ENDPOINT_UNREACHABLE | The endpoint is offline or unreachable. Please retry after endpoint is online. |
GET Wi-Fi installation status
Call GET /v2/endpoints/endpointId/features/connectivity/addOrUpdateWifiConfigurations/submittedOperations/{operationId}
to get the status of an addOrUpdateWifiConfigurations
operation.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, UK, DE, FR, IT, ES |
US, CA, UK, DE, FR, IT, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations/submittedOperations/{operationId} HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
endpointId |
The endpoint ID. Must be the same ID that you used in the call to POST addOrUpdateWiFiConfigurations. | String | Yes |
operationId |
The operation ID. Must be the submittedOperationId value returned by the POST addOrUpdateWifiConfigurations call |
String | Yes |
Response body example
{
"status": "TIMEOUT"
}
Response body parameters
Field | Description | Type | Required |
---|---|---|---|
status |
The status of specified addOrUpdateWifiConfigurations operation, as a Status object. |
Object | Yes |
Status object schema
Field | Description | Type | Required |
---|---|---|---|
status |
Value of status. The valid values are:
|
String |
Yes |
HTTP response codes
Status code | Type Description | |
---|---|---|
200 | OK | The operation returned the status value successfully. |
300 | RESOURCE_SPLIT | The endpoint ID has changed, but the underlying resource is still the same. The response body contains a URI reference for the new endpoint ID, for example, /v2/endpoints/{newId} . |
301 | ENDPOINT_REMOVED | The endpoint Id has changed, but the underlying resource is still the same. The response body contains a URI reference for the new endpoint ID, for example, /v2/endpoints/{newId} . |
303 | ENDPOINT_MERGED | The endpoint has been merged with another, causing the underlying resource to change. The response body contains a URI reference for the new endpoint ID, for example, /v2/endpoints/{newId} . |
400 | BAD_REQUEST | The request is malformed or is missing one or more required parameters. |
401 | UNAUTHORIZED | The LWA token is expired. |
403 | FORBIDDEN | The user isn't authorized to perform the operation for the specified endpoint. |
404 | NOT_FOUND | The specified endpointId or addOrUpdateWifiConfigurations request doesn't exist, or the request status is no longer available. |
500 | INTERNAL_SERVER_ERROR | A service error occurred. |
503 | Service Unavailable | Service is temporarily unavailable. |
Manage smart home features
GET features/color
Call GET /v2/endpoints/{endpointId}/features/color
to get color properties and available operations for the specified endpoint. For color property details, see Capability Property Schemas.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
GET /v2/endpoints/{endpointId}/features/color HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request body
None.
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Success response header
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
{
"properties": [
{
"name": "color",
"type": "RETRIEVABLE",
"value": {
"hue": 20,
"saturation": 0.5,
"brightness": 0.7
},
"timeOfSample": "1970-01-01T00:00:00Z"
}
],
"operations": [
{
"name": "setColor",
"path": "/v2/endpoints/{id}/features/color/setColor"
}
]
}
Partial success response body example
Following is an example showing the response returned when an error occurs during color
property retrieval.
{
"properties": [
{
"name": "color",
"type": "ERROR",
"error": {
"type": "",
"message": ""
}
}
],
"operations": [
{
"name": "setColor",
"path": "/v2/endpoints/{id}/features/color/setColor"
}
]
}
Response body parameters
properties
and operations
lists are required parameters, but the contents of each object list depends on whether or not the client has permissions to view the data.Field | Description | Type | Required |
---|---|---|---|
properties |
List of color properties. Currently only color is supported. Each property object is a polymorphic type. The contents of the list depend on whether or not the client has permissions to view the data. |
List of Property objects | Yes, but may be empty |
operations |
List of objects defining the color operations available for the specified endpoint. | List of Operation objects | Yes |
Property object schema
Field | Description | Type | Required |
---|---|---|---|
name |
The name of the property. Currently the only supported value is "color" . |
String | Yes |
type |
The type of property object. There are three supported values: RETRIEVABLE - Alexa is able to retrieve the value of the property. NOT_RETRIEVABLE - Retrieval is not supported for property. A retry will not succeed. ERROR - Alexa is unable to retrieve the value of the property due to an error. A retry may succeed. |
String | Yes |
value |
The current color. For details, see Capability Property Schemas. | String | No |
timeOfSample |
The time when the property value was retrieved. | Date | No |
error |
The presence of this field shows that an error occurred during property value retrieval. | Object | No |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error object schema
Field | Description | Type | Required |
---|---|---|---|
type |
Type of error encountered during property retrieval, for example, ENDPOINT_UNREACHABLE , ENDPOINT_BUSY . For valid error types, see Error type values. |
String | Yes |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | BAD_REQUEST | Bad Request | The request is invalid due to: {detailed reason}. |
401 | UNAUTHORIZED | Authentication Failure | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Not Found | The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | ENDPOINT_UNREACHABLE | Service Unavailable | The endpoint isn't reachable. |
POST features/color
Call POST /v2/endpoints/{endpointId}/features/color/setColor
to set color properties for the specified endpoint. For color property details, see Capability Property Schemas.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
POST /v2/endpoints/{endpointId}/features/color/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
endpointId |
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}" . |
String | Yes |
operation |
The operation to perform: setColor . |
String | Yes |
Request body example for setColor
{
"payload": {
"color": {
"hue": 20,
"saturation": 0.75,
"brightness": 0.34
}
}
}
Request body parameters for setColor
Field | Description | Type | Required |
---|---|---|---|
|
Payload wrapper object |
Object |
Yes |
|
Color object. For details, see Capability Property Schemas. |
Object |
Yes |
|
Hue value |
Double |
Yes |
|
Saturation value |
Double |
Yes |
|
Brightness value |
Double |
Yes |
Success response header
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Success response body
If the operation is completely successful, there is no response body.
Partial success response example
The HTTP/1.1 503 Service Unavailable
response indicates that the request was sent successfully, but Alexa received an error response from the endpoint reporter. Examples of endpoint errors: the endpoint is offline, the endpoint battery level is too low, etc.
HTTP/1.1 503 Service Unavailable
{
"type": "",
"message": ""
}
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error object schema
Field | Description | Type | Required |
---|---|---|---|
type |
Type of error encountered, for example, ENDPOINT_UNREACHABLE , ENDPOINT_BUSY . Present only if the request was valid but the request failed to execute successfully. For valid error types, see Error type values. |
String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | BAD_REQUEST | Bad Request | The request is invalid due to: {detailed reason}. |
401 | UNAUTHORIZED | Authentication Failure | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Not Found | The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | ENDPOINT_UNREACHABLE | Service Unavailable | The endpoint isn't reachable. |
GET features/brightness
Call GET /v2/endpoints/{endpointId}/features/brightness
to get the brightness setting and available operations for the specified endpoint. For brightness property details, see Capability Property Schemas.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
GET /v2/endpoints/{endpointId}/features/brightness HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request body
None.
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Success response header
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
{
"properties": [
{
"name": "brightness",
"type": "RETRIEVABLE",
"value": {
"value": 50
},
"timeOfSample": "1970-01-01T00:00:00Z"
}
],
"operations": [
{
"name": "setBrightness",
"path": "/v2/endpoints/{id}/features/brightness/setBrightness"
},
{
"name": "adjustBrightness",
"path": "/v2/endpoints/{id}/features/brightness/adjustBrightness"
}
]
}
Partial success response body example
Following is an example showing the response returned when an error occurs during brightness
property retrieval.
{
"properties": [
{
"name": "brightness",
"type": "ERROR",
"error": {
"type": "",
"message": ""
}
}
],
"operations": [
{
"name": "setBrightness",
"path": "/v2/endpoints/{id}/features/brightness/setBrightness"
},
{
"name": "adjustBrightness",
"path": "/v2/endpoints/{id}/features/brightness/adjustBrightness"
}
]
}
Response body parameters
properties
and operations
lists are required parameters, but the contents of each object list depends on whether or not the client has permissions to view the data.Field | Description | Type | Required |
---|---|---|---|
properties |
List of brightness properties. Currently only brightness is supported. Each property object is a polymorphic type. The contents of the list depend on whether or not the client has permissions to view the data. |
List of Property objects | Yes, but may be empty |
operations |
List of objects defining the brightness operations available for the specified endpoint. | List of Operation objects | Yes |
Property object schema
Field | Description | Type | Required |
---|---|---|---|
name |
The name of the property. Currently the only supported value is "brightness" . |
String | Yes |
type |
The type of property object. There are three supported values: RETRIEVABLE - Alexa is able to retrieve the value of the property. NOT_RETRIEVABLE - Retrieval is not supported for property. A retry will not succeed. ERROR - Alexa is unable to retrieve the value of the property due to an error. A retry may succeed. |
String | Yes |
value |
The current brightness level. Valid values are from 0 to 100, inclusive. For details, see Capability Property Schemas. | String | No |
timeOfSample |
The time when the property value was retrieved. | Date | No |
error |
The presence of this field shows that an error occurred during property value retrieval. | Object | No |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error object schema
Field | Description | Type | Required |
---|---|---|---|
type |
Type of error encountered during property retrieval, for example, ENDPOINT_UNREACHABLE , ENDPOINT_BUSY . For valid error types, see Error type values. |
String | Yes |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | BAD_REQUEST | Bad Request | The request is invalid due to: {detailed reason}. |
401 | UNAUTHORIZED | Authentication Failure | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Not Found | The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | ENDPOINT_UNREACHABLE | Service Unavailable | The endpoint isn't reachable. |
POST features/brightness
Call POST /v2/endpoints/{endpointId}/features/brightness/setBrightness
to set the brightness level for the specified endpoint.
Call POST /v2/endpoints/{endpointId}/features/brightness/adjustBrightness
to change the brightness level for the specified endpoint by a specified amount.
For brightness property details, see Capability Property Schemas.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
POST /v2/endpoints/{endpointId}/features/brightness/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
endpointId |
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}" . |
String | Yes |
operation |
The operation to perform: setBrightness . |
String | Yes |
Request body example for setBrightness
{
"payload": {
"brightness": 50
}
}
Request body parameters for setBrightness
Field | Description | Type | Required |
---|---|---|---|
|
Payload wrapper object |
Object |
Yes |
|
Brightness value. Valid values are from 0 to 100, inclusive. For details, see Capability Property Schemas. |
Integer |
Yes |
Request body example for adjustBrightness
{
"payload": {
"brightnessDelta": 10
}
}
Request body parameters for adjustBrightness
Field | Description | Type | Required |
---|---|---|---|
|
Payload wrapper object |
Object |
Yes |
|
Brightness delta value. Valid values are from -100 to 100, inclusive. For details, see Capability Property Schemas. |
Integer |
Yes |
Success response header
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Success response body
If the operation is completely successful, there is no response body.
Partial success response example
The HTTP/1.1 503 Service Unavailable
response indicates that the request was sent successfully, but Alexa received an error response from the endpoint reporter. Examples of endpoint errors: the endpoint is offline, the endpoint battery level is too low, etc.
HTTP/1.1 503 Service Unavailable
{
"type": "",
"message": ""
}
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error object schema
Field | Description | Type | Required |
---|---|---|---|
type |
Type of error encountered, for example, ENDPOINT_UNREACHABLE , ENDPOINT_BUSY . Present only if the request was valid but the request failed to execute successfully. For valid error types, see Error type values. |
String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | BAD_REQUEST | Bad Request | The request is invalid due to: {detailed reason}. |
401 | UNAUTHORIZED | Authentication Failure | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Not Found | The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | ENDPOINT_UNREACHABLE | Service Unavailable | The endpoint isn't reachable. |
GET features/colorTemperature
Call GET /v2/endpoints/{endpointId}/features/colorTemperature
to get color temperature properties and available operations for the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
GET /v2/endpoints/{endpointId}/features/colorTemperature HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request body
None.
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Success response header
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
{
"properties": [
{
"name": "colorTemperatureInKelvin",
"type": "RETRIEVABLE",
"value": {
"value": "2700"
},
"timeOfSample": "1970-01-01T00:00:00Z"
}
],
"operations": [
{
"name": "setColorTemperature",
"path": "/v2/endpoints/{id}/features/colorTemperature/setColorTemperature"
},
{
"name": "increaseColorTemperature",
"path": "/v2/endpoints/{id}/features/colorTemperature/increaseColorTemperature"
},
{
"name": "decreaseColorTemperature",
"path": "/v2/endpoints/{id}/features/colorTemperature/decreaseColorTemperature"
}
]
}
Partial success response body example
Following is an example showing the response returned when an error occurs during colorTemperature
property retrieval.
{
"properties": [
{
"name": "colorTemperatureInKelvin",
"type": "ERROR",
"error": {
"type": "",
"message": ""
}
}
],
"operations": [
{
"name": "setColorTemperature",
"path": "/v2/endpoints/{id}/features/colorTemperature/setColorTemperature"
},
{
"name": "increaseColorTemperature",
"path": "/v2/endpoints/{id}/features/colorTemperature/increaseColorTemperature"
},
{
"name": "decreaseColorTemperature",
"path": "/v2/endpoints/{id}/features/colorTemperature/decreaseColorTemperature"
}
]
}
Response body parameters
properties
and operations
lists are required parameters, but the contents of each object list depends on whether or not the client has permissions to view the data.Field | Description | Type | Required |
---|---|---|---|
properties |
List of color temperature properties. Currently only colorTemperatureInKelvin is supported. Each property object is a polymorphic type. The contents of the list depend on whether or not the client has permissions to view the data. |
List of Property objects | Yes, but may be empty |
operations |
List of objects defining the color temperature operations available for the specified endpoint. | List of Operation objects | Yes, but may be empty |
Property object schema
Field | Description | Type | Required |
---|---|---|---|
name |
The name of the property. Currently the only supported value is "colorTemperatureInKelvin" . |
String | Yes |
type |
The type of property object. There are three supported values: RETRIEVABLE - Alexa is able to retrieve the value of the property. NOT_RETRIEVABLE - Retrieval is not supported for property. A retry will not succeed. ERROR - Alexa is unable to retrieve the value of the property due to an error. A retry may succeed. |
String | Yes |
value |
The current color temperature value in Kelvin, from 1000 to 10000, inclusive. | Integer | No |
timeOfSample |
The time when the property value was retrieved. | Date | No |
error |
The presence of this field shows that an error occurred during property value retrieval. | Object | No |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error object schema
Field | Description | Type | Required |
---|---|---|---|
type |
Type of error encountered during property retrieval, for example, ENDPOINT_UNREACHABLE , ENDPOINT_BUSY . For valid error types, see Error type values. |
String | Yes |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | BAD_REQUEST | Bad Request | The request is invalid due to: {detailed reason}. |
401 | UNAUTHORIZED | Authentication Failure | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Not Found | The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | ENDPOINT_UNREACHABLE | Service Unavailable | The endpoint isn't reachable. |
POST features/colorTemperature
Call POST /v2/endpoints/{endpointId}/features/colorTemperature/setColorTemperature
to set the color temperature value for the specified endpoint.
Call POST /v2/endpoints/{endpointId}/features/colorTemperature/increaseColorTemperature
to increase the color temperature value for the specified endpoint. This call adjusts the color temperature but doesn't specify a value to change by; that is up to the implementing service or the manufacturer. This call has no request body.
Call POST /v2/endpoints/{endpointId}/features/colorTemperature/decreaseColorTemperature
to decrease the color temperature value for the specified endpoint. This call adjusts the color temperature but doesn't specify a value to change by; that is up to the implementing service or the manufacturer. This call has no request body.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
POST /v2/endpoints/{endpointId}/features/colorTemperature/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
endpointId |
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}" . |
String | Yes |
operation |
The operation to perform: setColorTemperature , increaseColorTemperature , or decreaseColorTemperature . |
String | Yes |
Request body example for setColorTemperature
{
"payload": {
"colorTemperatureInKelvin": 2700
}
}
Request body parameters for setColorTemperature
Field | Description | Type | Required |
---|---|---|---|
|
Payload wrapper object |
Object |
Yes |
|
Color temperature value. From 1000 to 10000, inclusive. |
Integer |
Yes |
Success response header
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Success response body
If the operation is completely successful, there is no response body.
Partial success response example
The HTTP/1.1 503 Service Unavailable
response indicates that the request was sent successfully, but Alexa received an error response from the endpoint reporter. Examples of endpoint errors: the endpoint is offline, the endpoint battery level is too low, etc.
HTTP/1.1 503 Service Unavailable
{
"type": "",
"message": ""
}
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error object schema
Field | Description | Type | Required |
---|---|---|---|
type |
Type of error encountered, for example, ENDPOINT_UNREACHABLE , ENDPOINT_BUSY . Present only if the request was valid but the request failed to execute successfully. For valid error types, see Error type values. |
String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | BAD_REQUEST | Bad Request | The request is invalid due to: {detailed reason}. |
401 | UNAUTHORIZED | Authentication Failure | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Not Found | The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | ENDPOINT_UNREACHABLE | Service Unavailable | The endpoint isn't reachable. |
GET features/power
Call GET /v2/endpoints/{endpointId}/features/power
to get power feature properties and their corresponding values for the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/features/power HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request body
None.
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
{
"properties": [
{
"name": "powerState",
"type": "RETRIEVABLE",
"value": {
"value": "ON"
},
"timeOfSample": "1970-01-01T00:00:00Z"
}
],
"operations": [
{
"name": "turnOn",
"path": "/v2/endpoints/{endpointID}/features/power/turnOn"
},
{
"name": "turnOff",
"path": "/v2/endpoints/{endpointID}/features/power/turnOff"
}
]
}
Partial success response example
Following is an example showing the response returned when an error occurs during powerState
property retrieval.
{
"properties": [
{
"name": "powerState",
"type": "ERROR",
"error": {
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
}
],
"operations": [
{
"name": "turnOn",
"path": "/v2/endpoints/{id}/features/power/turnOn"
},
{
"name": "turnOff",
"path": "/v2/endpoints/{id}/features/power/turnOff"
}
]
}
Response body parameters
properties
and operations
lists are required parameters, but the contents of each object list depends on whether or not the client has permissions to view the data.Field | Description | Type | Required |
---|---|---|---|
properties |
List of power-feature properties, such as power state. Each property object is a polymorphic type. For example, a powerState property object represents the state of the endpoint's power state at the time of sample. |
List of Property objects | Yes |
operations |
List of objects defining the power-feature operations available for the specified endpoint. | List of Operation objects | Yes |
Property object schema
Field | Description | Type | Required |
---|---|---|---|
name |
The name of the property. Currently the only supported value is "powerState" . |
String | Yes |
type |
The type of property object. There are three supported values: RETRIEVABLE - Alexa is able to retrieve the value of the property. NOT_RETRIEVABLE - Retrieval is not supported for property. A retry will not succeed. ERROR - Alexa is unable to retrieve the value of the property due to an error. A retry may succeed. |
String | Yes |
value |
The current power state: ON or OFF . |
String | No |
timeOfSample |
The time when the property value was retrieved. | Date | No |
error |
The presence of this field shows that an error occurred during property value retrieval. | Object | No |
Error object schema
Field | Description | Type | Required |
---|---|---|---|
type |
Type of error encountered during retrieval of the property: "DEVICE_UNREACHABLE" or "INTERNAL_ERROR" . |
String | Yes |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
Operation object schema
Field | Description | Type | Required |
---|---|---|---|
name |
The operation name. For the power feature, this is "turnOn" or "turnOff" . |
String | Yes |
path |
The full path that can be used to set the feature properties. | String | Yes |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | BAD_REQUEST | Bad Request | The request is invalid due to: {detailed reason}. |
401 | UNAUTHORIZED | Authentication Failure | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Not Found | The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | ENDPOINT_UNREACHABLE | Service Unavailable | The endpoint isn't reachable. |
POST features/power
Call POST /v2/endpoints/{endpointId}/features/power/turnOn
to turn on the endpoint's power.
Call POST /v2/endpoints/{endpointId}/features/power/turnOff
to turn off the endpoint's power.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.POST /v2/endpoints/{endpointId}/features/power/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
endpointId |
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}" . |
String | Yes |
operation |
The operation to perform: turnOn or turnOff . |
String | Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | BAD_REQUEST | Bad Request | The request is invalid due to: {detailed reason}. |
401 | UNAUTHORIZED | Authentication Failure | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Not Found | The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | ENDPOINT_UNREACHABLE | Service Unavailable | The endpoint isn't reachable. |
GET features/temperatureSensor
Call GET /v2/endpoints/{endpointId}/features/temperatureSensor
to get temperatureSensor feature properties and their corresponding values for the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/features/temperatureSensor HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request body
None.
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
{
"name": "temperatureSensor",
"properties": [
{
"name": "temperature",
"type": "RETRIEVABLE",
"value": {
"value": 68.0,
"scale": "FAHRENHEIT"
},
"timeOfSample": "2021-03-04T17:46:42.48Z"
},
]
}
Supported Property Values
Field | Description | Type | Required |
---|---|---|---|
temperature.value |
The temperature reported by the sensor. | temperature Object | No |
Temperature
Field | Description | Type |
---|---|---|
value |
The temperature. | Double |
scale |
The scale of the temperature. | A temperature scale string. |
Example temperature value
{
"value": {
"value": 68.0,
"scale": "FAHRENHEIT"
}
}
Temperature scales
Value | Description |
---|---|
CELSIUS |
The Celsius temperature scale. |
FAHRENHEIT |
The Fahrenheit temperature scale. |
KELVIN |
The Kelvin temperature scale. |
GET features/thermostat
Call GET /v2/endpoints/{endpointId}/features/thermostat
to get thermostat feature properties and their corresponding values for the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/features/thermostat HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request body
None.
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example (Single Setpoint Thermostat)
{
"name": "thermostat",
"properties": [
{
"name": "thermostatMode",
"type": "RETRIEVABLE",
"value": {
"value": "HEAT"
},
"timeOfSample": "2021-03-04T17:46:42.48Z"
},
{
"name": "targetSetpoint",
"type": "RETRIEVABLE",
"value": {
"value": 68.0,
"scale": "FAHRENHEIT"
},
"timeOfSample": "2021-03-04T17:46:42.48Z"
},
],
"operations": [
{
"name": "setThermostatMode",
"path": "/v2/endpoints/{endpointID}/features/thermostat/setThermostatMode"
},
{
"name": "setTargetSetpoint",
"path": "/v2/endpoints/{endpointID}/features/thermostat/setTargetSetpoint"
},
{
"name": "adjustTargetSetpoint",
"path": "/v2/endpoints/{endpointID}/features/thermostat/adjustTargetSetpoint"
}
],
"configuration": {
"supportedModes": [
"HEAT",
"COOL",
"AUTO"
]
}
}
Response body example (Dual Setpoint Thermostat)
{
"name": "thermostat",
"properties": [
{
"name": "thermostatMode",
"type": "RETRIEVABLE",
"value": {
"value": "HEAT"
},
"timeOfSample": "2021-03-04T17:46:42.48Z"
},
{
"name": "lowerSetpoint",
"type": "RETRIEVABLE",
"value": {
"value": 68.0,
"scale": "FAHRENHEIT"
},
"timeOfSample": "2021-03-04T17:46:42.48Z"
},
{
"name": "upperSetpoint",
"type": "RETRIEVABLE",
"value": {
"value": 73.0,
"scale": "FAHRENHEIT"
},
"timeOfSample": "2021-03-04T17:46:42.48Z"
}
],
"operations": [
{
"name": "setThermostatMode",
"path": "/v2/endpoints/{endpointID}/features/thermostat/setThermostatMode"
},
{
"name": "setTargetSetpoint",
"path": "/v2/endpoints/{endpointID}/features/thermostat/setTargetSetpoint"
}
],
"configuration": {
"supportedModes": [
"HEAT",
"COOL",
"AUTO"
]
}
}
Supported Property Values
Field | Description | Type | Required |
---|---|---|---|
targetSetpoint.value |
The target temperature of a single-setpoint thermostat. | temperature Object | No |
lowerSetpoint.value |
The lower setpoint of a dual-setpoint thermostat. | temperature Object | No |
upperSetpoint.value |
The upper setpoint of a dual-setpoint thermostat. | temperature Object | No |
thermostatMode.value |
The mode of a thermostat. | thermostatMode String | No |
Temperature
Field | Description | Type |
---|---|---|
value |
The temperature. | Double |
scale |
The scale of the temperature. | A temperature scale string. |
Example temperature value
{
"value": {
"value": 68.0,
"scale": "FAHRENHEIT"
}
}
Temperature scales
Value | Description |
---|---|
CELSIUS |
The Celsius temperature scale. |
FAHRENHEIT |
The Fahrenheit temperature scale. |
KELVIN |
The Kelvin temperature scale. |
ThermostatMode Values
Value | Description |
---|---|
AUTO |
Indicates automatic heating or cooling based on the current temperature and the setpoint. |
COOL |
Indicates cooling mode. |
HEAT |
Indicates heating mode. |
ECO |
Indicates economical mode. |
OFF |
Indicates that heating and cooling is off, but the device might still have power. |
Supported Configuration
Field | Description | Type | Required |
---|---|---|---|
supportedModes | The modes that the device supports. | Array thermostatMode Strings | yes |
Feature Operations
Supported Operations
Field | Description |
---|---|
adjustTargetSetpoint |
Adjust the target set point of a single set point thermostat by a specified value. |
setTargetSetpoint |
Set the thermostat to a specified set point(s). |
setThermostatMode |
Set the mode of the thermostat. |
adjustTargetSetpoint
Call POST /v2/endpoints/{endpointId}/features/thermostat/adjustTargetSetpoint
to adjust the target set point of a single set point thermostat by a specified value.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.POST /v2/endpoints/{endpointId}/features/thermostat/adjustTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body payload
Field | Description | Type | Required |
---|---|---|---|
targetSetpointDelta |
The amount by which the thermostat should adjust the set point. | temperature Object | Yes |
Example Request
POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/adjustTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer
{
"payload": {
"targetSetpointDelta": {
"value": -2.0,
"scale": "CELSIUS"
}
}
}
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | BAD_REQUEST | Bad Request | The request is invalid due to: {detailed reason}. |
401 | UNAUTHORIZED | Authentication Failure | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Not Found | The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | ENDPOINT_UNREACHABLE | Service Unavailable | The endpoint isn't reachable. |
setTargetSetpoint
Call POST /v2/endpoints/{endpointId}/features/thermostat/setTargetSetpoint
to set the thermostat to a specified set point(s).
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.POST /v2/endpoints/{endpointId}/features/thermostat/setTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body payload
Field | Description | Type | Required |
---|---|---|---|
targetSetpoint |
target set point for a single setpoint thermostat | temperature Object | Yes (for a single setpoint thermostat) |
lowerSetpoint |
lower set point for a dual setpoint thermostat | temperature Object | Yes (for a dual setpoint thermostat) |
upperSetpoint |
upper set point for a dual setpoint thermostat | temperature Object | Yes (for a dual setpoint thermostat) |
Example Request (Single Setpoint)
POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/setTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer
{
"payload": {
"targetSetpoint": {
"value": 21.0,
"scale": "CELSIUS"
}
}
}
Example Request (Dual Setpoint)
POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/setTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer
{
"payload": {
"lowerSetpoint": {
"value": 68.0,
"scale": "FAHRENHEIT"
},
"upperSetpoint": {
"value": 72.0,
"scale": "FAHRENHEIT"
}
}
}
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | BAD_REQUEST | Bad Request | The request is invalid due to: {detailed reason}. |
401 | UNAUTHORIZED | Authentication Failure | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Not Found | The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | ENDPOINT_UNREACHABLE | Service Unavailable | The endpoint isn't reachable. |
setThermostatMode
Call POST /v2/endpoints/{endpointId}/features/thermostat/setThermostatMode
to set the mode of the thermostat.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.POST /v2/endpoints/{endpointId}/features/thermostat/setThermostatMode HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body payload
Field | Description | Type | Required |
---|---|---|---|
thermostatMode |
The mode to set the thermostat to. | thermostatMode String | Yes (for a single setpoint thermostat) |
Example Request (Dual Setpoint)
POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/setTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer
{
"payload": {
"thermostatMode": "HEAT"
}
}
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | BAD_REQUEST | Bad Request | The request is invalid due to: {detailed reason}. |
401 | UNAUTHORIZED | Authentication Failure | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The user isn't authorized to perform the operation. |
404 | NOT_FOUND | Not Found | The endpoint in the path wasn't found. The specified feature or operation isn't available on the endpoint. |
429 | TOO_MANY_REQUESTS | Too Many Requests | The request was throttled. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | ENDPOINT_UNREACHABLE | Service Unavailable | The endpoint isn't reachable. |
Manage speaker
feature
GET features/speaker
Call GET /endpoints/{endpointID}/features/speaker
to retrieve speaker-feature properties and their corresponding values of the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/features/speaker HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request body
None.
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
{
"properties": [
{
"name": "volume",
"type": "RETRIEVABLE",
"value": {
"value": 42
},
"timeOfSample": "1970-01-01T00:00:00Z"
}
],
"operations": [
{
"name": "setVolume",
"path": "/v2/endpoints/{endpointID}/features/speaker/setVolume"
},
{
"name": "adjustVolume",
"path": "/v2/endpoints/{endpointID}/features/speaker/adjustVolume"
}
]
}
Partial success response example
Following is an example showing the response returned when an error occurs during volume
property retrieval.
{
"properties": [
{
"name": "volume",
"type": "RETRIEVABLE",
"error": {
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
}
],
"operations": [
{
"name": "setVolume",
"path": "/v2/endpoints/<id>/features/speaker/setVolume"
},
{
"name": "adjustVolume",
"path": "/v2/endpoints/<id>/features/speaker/adjustVolume"
}
]
}
Response body parameters
properties
and operations
lists are required parameters, but the contents of each object list depends on whether or not the client has permissions to view the data.Field | Description | Type | Required |
---|---|---|---|
properties |
List of speaker-feature properties, such as volume. Each property object is a polymorphic type. For example, a volume property object represents the state of the endpoint's speaker volume at the time of sample. | List of Property objects | Yes |
operations |
List of objects defining the speaker-feature operations available for the specified endpoint. | List of Operation objects | Yes |
Property object schema
Field | Description | Type | Required |
---|---|---|---|
name |
The name of the property. Currently the only supported value is "volume" . |
String | Yes |
type |
The type of property object. There are three supported values: RETRIEVABLE - Alexa is able to retrieve the value of the property. NOT_RETRIEVABLE - Retrieval is not supported for property. A retry will not succeed. ERROR - Alexa is unable to retrieve the value of the property due to an error. A retry may succeed. |
String | Yes |
value |
The current volume, for example, 42. Valid range is from 0 to 100. | Integer | No |
timeOfSample |
The time when the property value was retrieved. | Date | No |
error |
The presence of this field shows that an error occurred during property value retrieval. | Object | No |
Error object schema
Field | Description | Type | Required |
---|---|---|---|
type |
Type of error encountered during retrieval of the property: "DEVICE_UNREACHABLE" or "INTERNAL_ERROR" . |
String | Yes |
message |
The name of the property, for example, "volume" . |
String | Yes |
HTTP response codes
Status code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
400 | Bad Request | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The access token is valid, but the user doesn't have the needed LWA scope permissions. |
404 | Not found | The requested artifact wasn't found for the client. |
429 | Too many requests | The request was throttled because the server is too busy. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. Retry after one second, but don't retry more than one time. |
503 | Service Unavailable | Service is temporarily unavailable. |
POST features/speaker
Call POST /v2/endpoints/{endpointId}/features/speaker/setVolume
to set speaker volume to the specified value on the specified endpoint.
Call POST /v2/endpoints/{endpointId}/features/speaker/adjustVolume
to adjust speaker volume by the specified value on the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.POST /v2/endpoints/{endpointID}/features/speaker/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
endpointId |
The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}" . |
String | Yes |
operation |
One of DAAPI operation exposed on the speaker-feature for the specified endpoint: setVolume or adjustVolume . |
String | Yes |
Request body example for setVolume
{
"payload": {
"volume": 42
}
}
Request body parameters for setVolume
Field | Description | Type | Required |
---|---|---|---|
volume |
The absolute volume to set endpoint's speaker volume to. Valid range is 0 to 100. | String | Yes |
Request body example for adjustVolume
{
"payload": {
"volumeDelta": -42
}
}
Request body parameters for adjustVolume
Field | Description | Type | Required |
---|---|---|---|
volumeDelta |
The relative volume to adjust the endpoint's speaker volume by. Valid range is -100 to 100. If the volume of the endpoint is already set to '20', and adjustVolume operation is invoked to adjust the endpoint volume by '-30', the endpoint volume is set to 0. Similarly, if the volume of the endpoint is already set to '20' and adjustVolume operation is invoked to adjust the endpoint volume by '90', the endpoint volume is set to 100. |
String | Yes |
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
HTTP response codes
Status code | Name | Description |
---|---|---|
202 | Accepted | The request succeeded. |
400 | Bad Request | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The access token is valid, but the user doesn't have the needed LWA scope permissions. |
404 | Not found | The requested artifact wasn't found for the client. |
429 | Too many requests | The request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. Retry after one second, but don't retry more than one time. |
503 | Service Unavailable | The server is temporarily unavailable. |
Query endpoint setting value
You can query the current value of a setting for an endpoint by calling GET /v2/endpoints/{endpointId}/settings/{settingName}
.
You can also query the current values of multiple settings for an endpoint by calling GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults}
.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Supported settings
The following settings are supported.
Setting Name | Description | Response Fields | Response Field Description | Response Field Type |
---|---|---|---|---|
address |
Get the address setting. |
address |
Address setting for the endpoint. | Object |
Alexa.DoNotDisturb.doNotDisturb |
Get the DoNotDisturb setting. This setting prevents notifications and proactive experiences (calls, etc.) from disturbing the user. |
enabled |
true if the DoNotDisturb setting is enabled, or false otherwise. |
Boolean |
System.locales |
Get the user's preferred locales. In the context of an Alexa device, this setting controls which languages the Alexa-enabled device is expected to understand and respond with. | locales |
List of locale strings. Up to two locales can be specified. First element in the list is the preferred locale. Not all skill types are available in all locales. | List |
SpeechRecognizer.wakeWords |
Get the WakeWords setting. This setting controls what alternative wake words can be used to wake up Alexa. |
wakeWords |
List of wake words, for example, ["ALEXA"]. Alexa supported wake words are ALEXA, AMAZON, COMPUTER, and ECHO. Currently you can only specify one wake word at a time. Note: Not all devices and locales support all wake words. COMPUTER isn't supported in France (fr-FR). | List |
SpeechRecognizer.wakeWordConfirmation |
Get the wakeWordConfirmation setting. This setting enables the user to specify whether they want an audible tone to play in addition to the visual indicator when Alexa detects the wake word. The tone indicates that Alexa is now listening and capturing the request. |
wakeWordConfirmation |
The current wake word confirmation setting. Alexa-supported wake word confirmation settings are TONE and NONE . |
String |
SpeechRecognizer.speechConfirmation |
Get the speechConfirmation setting. This setting allows the user to specify whether they want a short tone to play at the end of their request to Alexa. The tone indicates that Alexa has finished listening to and capturing the request. |
speechConfirmation |
The current speech confirmation setting. Alexa supported speech confirmation settings are "TONE" and "NONE". | String |
SpeechRecognizer.FollowUp |
Get the follow-up mode setting. This setting enables Alexa to listen for a subsequent request from the user without requiring the user to say the wake word. | FollowUp |
true if follow-up mode is enabled, or false otherwise. |
Boolean |
Alexa.ManagedDevice.Settings.errorSuppression |
Get the errorSuppression setting. This setting controls whether the device plays error audio cues (brief, distinctive sounds) for certain errors. |
errorSuppression |
List of error suppressions. Currently the only supported value is CONNECTIVITY . If the list is empty ([]), no errors are suppressed. |
List |
Alexa.ManagedDevice.Settings.setupModePrivileges |
Get the setupModePrivileges setting. This setting controls the end user's ability to put a device into configuration mode via the setup mode process (for example, by long-pressing the Action button). |
setupModePrivileges |
A list of setup mode privileges. Alexa supported list of setup mode privileges is, ["ALL_SETTINGS"] . ["ALL_SETTINGS"] allows the end user to put a device into setup mode. An empty list ([] ) shows that setup mode is disabled. |
List |
Alexa.ManagedDevice.Settings.maximumVolumeLimit |
Get the maximumVolumeLimit setting. |
maximumVolumeLimit |
A number from 0 to 100, inclusive. | Integer |
System.timeZone |
Get the timeZone setting. |
timeZone |
A time zone string, following the Olson format defined in the Timezone Database. For example: "America/Los_Angeles" . |
String |
System.temperatureUnit |
Get the temperatureUnit setting. |
temperatureUnit |
A temperature string, "CELSIUS" or "FAHRENHEIT" . |
String |
System.distanceUnits |
Get the distanceUnits setting. |
distanceUnits |
A distance unit string, "METRIC" or "IMPERIAL" . |
String |
Accessibility.Captions.AlexaCaptions.enablement |
Get the AlexaCaptions setting. Note: Captions aren't supported in the UK (en-GB) or France (fr-FR). |
AlexaCaptions |
"ENABLED" or "DISABLED" . |
String |
Accessibility.Captions.ClosedCaptions.enablement |
Get the ClosedCaptions setting. Note: Captions aren't supported in the UK (en-GB) or France (fr-FR). |
ClosedCaptions |
"ENABLED" or "DISABLED" . |
String |
Accessibility.Display.Magnifier.enablement |
Get the Magnifier setting. Note: Magnifiers aren't supported in the UK (en-GB) or France (fr-FR). |
Magnifier |
"ENABLED" or "DISABLED" . |
String |
Accessibility.Display.ColorInversion.enablement |
Get the ColorInversion setting. Note: Color inversion isn't supported in the UK (en-GB) or France (fr-FR). |
ColorInversion |
"ENABLED" or "DISABLED" . |
String |
Query endpoint single setting
You can query the current value of a setting for an endpoint by calling GET /v2/endpoints/{endpointId}/settings/{settingName}
.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/{SettingName} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Response body
{value}
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
Query endpoint multiple settings
You can query the current values of multiple settings for an endpoint by calling GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults}
.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request query parameters
Field | Description | Type | Required |
---|---|---|---|
keys |
Comma separated setting names to query. | String | Yes |
nextToken |
The token client uses to query the next page. | String | No |
maxResults |
The maximum result client asks for this page. | String | No |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Response body
Field | Description | Type | Required |
---|---|---|---|
paginationContext |
An object with property of nextToken . This is for client to pass in for the subsequent request for next page. nextToken being absent means this is the final page. |
String | No |
settings |
An array consist of objects with 2 properties: key and value . There is no specific guaranteed order for returned settings. |
String | No |
errors |
An array consist of objects with each containing properties of key , status , code and message . errors being absent means all queries finish correctly with results filled in settings . |
String | No |
{
"paginationContext": {
"nextToken": "{nextToken}"
},
"settings": [
{
"key": "{settingName1}",
"value": {value1}
},
{
"key": "{settingName2}",
"value": {value2}
},
...
],
"errors": [
{
"status": {status3},
"key": "{settingName3}",
"code": "{code3}",
"message": "{message3}"
},
{
"status": {status4},
"key": "{settingName4}",
"code": "{code4}",
"message": "{message4}"
},
...
]
}
Error response
HTTP/1.1 {ErrorCode}
{
"code": "{ErrorCode}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
code |
The error code. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
GET address setting
Call GET /v2/endpoints/{endpointId}/settings/address
to get the address where an endpoint is located. Alexa uses this setting for features like Local Search and Weather. For details, see Enhance Your Skill With Address Information.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/address HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
{
"address": {
"addressLine1": "221 Baker Ave",
"addressLine2": "",
"addressLine3": "",
"city": "Sunnyvale",
"stateOrRegion": "California",
"districtOrCounty": "",
"postalCode": "94085",
"countryCode": "US"
}
}
Response body parameters
Field | Description | Type | Required |
---|---|---|---|
address |
The device address. | Address | Yes |
Address object
Parameter | Description | Type | Required |
---|---|---|---|
addressLine1 |
The first line of the address. | String | Yes |
addressLine2 |
The second line of the address. | String | Yes, may be empty string |
addressLine3 |
The third line of the address. | String | Yes, may be empty string |
city |
The city for the endpoint specified in the request. | String | Yes |
stateOrRegion |
Abbreviation for the state, province or region associated with the endpoint specified in the request. This value may be an empty string for non-US countries. | String | Yes |
districtOrCounty |
The district or county associated with the device. This value may be an empty string for non-US countries. | String | Yes |
postalCode |
The postal code for the endpoint specified in the request. | String | Yes |
countryCode |
The two-letter country/region code for the endpoint specified in the request. | String | Yes |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
503 | Service Unavailable | Service is temporarily unavailable. |
GET DoNotDisturb setting
Call GET /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb
to get the DoNotDisturb
setting. This setting prevents notifications and proactive experiences (calls, etc.) from disturbing the user.
DoNotDisturb
mode, proactive suggestion campaigns only appear when the user has interacted with Alexa recently. After a few minutes of no interaction with Alexa, the device returns to showing the clock.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
true
Response body value
A Boolean value: true
if the DoNotDisturb
setting is enabled, or false
otherwise.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET Locales setting
Call GET /v2/endpoints/{endpointId}/settings/System.locales
to get the user's preferred locales. In the context of an Alexa device, this setting controls which languages the Alexa-enabled device is expected to understand and respond with.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/System.locales HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body examples
["en-US", "es-US"]
["en-US", "fr-FR"]
Response body value
A list of up to two locale strings. First element in the list is the preferred locale. Not all skill types are available in all locales.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET WakeWords setting
Call GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords
to get the WakeWords
setting. This setting controls what alternative wake words the user can say to wake up Alexa.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
["ALEXA"]
Response body value
A list of the currently enabled wake words, for example, ["ALEXA"]. Alexa supported wake words are, ALEXA, AMAZON, COMPUTER, and ECHO. Currently you can only specify one wake word at a time. Note: Not all devices and locales support all wake words. COMPUTER isn't supported in France (fr-FR).
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET WakeWordConfirmation setting
Call GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation
to update the start-of-request sound setting. This setting enables the user to specify whether they want an audible tone to play in addition to the visual indicator when Alexa detects the wake word. The tone indicates that Alexa is now listening and capturing the request.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
endpointId |
The endpoint ID in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}" . |
String | Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
"NONE"
Response value
The current wake word confirmation setting. Alexa-supported wake word confirmation settings are TONE
and NONE
.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET SpeechConfirmation setting
Call GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation
to get the end-of-request sound. This setting allows the user to specify whether they want a short tone to play at the end of their request to Alexa to indicate that Alexa has finished listening to and capturing the request.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
"NONE"
Response value
The current speech confirmation setting. Alexa supported speech confirmation settings are "TONE" and "NONE".
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET ErrorSuppression setting
Call GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression
to get the list of error suppressions. This setting controls whether the device plays error audio cues (brief, distinctive sounds) for certain errors.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
["CONNECTIVITY"]
Response body value
The list of error suppressions. Currently the only supported value is ["CONNECTIVITY"]
. An empty list shows that no errors are suppressed.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested artifact wasn't found for the client. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET SetupModePrivileges setting
Call GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.setupModePrivileges
to get the list of setup mode privileges. This setting controls the end user's ability to put a device into configuration mode via the setup mode process (for example, by long-pressing the Action button).
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.setupModePrivileges HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
["ALL_SETTINGS"]
Response body value
The list of setup mode privileges. Alexa supported list of setup mode privileges is, ["ALL_SETTINGS"]
. ["ALL_SETTINGS"]
allows the end user to put a device into setup mode. An empty list ([]
) shows that setup mode is disabled.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET MaximumVolumeLimit setting
Call GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit
to get the maximum volume limit.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
42
Response body value
An integer value from 0 to 100, inclusive.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET TimeZone setting
Call GET /v2/endpoints/{endpointId}/settings/System.timeZone
to get the time zone.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/System.timeZone HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
"America/Los_Angeles"
Response body value
A time zone string, following the Olson format defined in the Timezone Database. For example: "America/Los_Angeles"
.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET TemperatureUnit setting
Call GET /v2/endpoints/{endpointId}/settings/System.temperatureUnit
to get the temperature scale (Celsius or Fahrenheit) setting.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/System.temperatureUnit HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
"CELSIUS"
Response body value
A temperature unit string: "CELSIUS"
or "FAHRENHEIT"
.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET DistanceUnits setting
Call GET /v2/endpoints/{endpointId}/settings/System.distanceUnits
to get the distance units (Metric or Imperial) setting.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/System.distanceUnits HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
"METRIC"
Response body value
A distance unit string: "METRIC"
or "IMPERIAL"
.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET AlexaCaptions setting
Call GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.AlexaCaptions.enablement
to get the Alexa caption setting.
This setting controls whether a multimedia device displays the following information:
- Alexa captions, which provide the text version of what Alexa speaks via SpeechSynthesizer. All domains that use Alexa Voice Service (AVS) should provide captions.
- The captions that accompany AudioPlayer directives.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, IT, DE, ES |
US, UK, CA, FR, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.AlexaCaptions.enablement HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
"ENABLED"
Response body value
A string representing the current value of this setting: "ENABLED"
or "DISABLED"
.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET ClosedCaptions setting
Call GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement
to get the closed caption setting.
This setting controls whether a multimedia device displays closed captions for video content.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, IT, DE, ES |
US, UK, CA, FR, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
"ENABLED"
Response body value
A string representing the current value of this setting: "ENABLED"
or "DISABLED"
.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET Magnifier setting
Call GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement
to get the device magnifier setting.
This setting gives the device user the ability to enlarge items on the screen to improve readability.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, IT, DE, ES |
US, UK, CA, FR, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
"ENABLED"
Response body value
A string representing the current value of this setting: "ENABLED"
or "DISABLED"
.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET ColorInversion setting
Call GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement
to get the screen color inversion setting.
This setting gives the device user the ability to invert the screen display colors to improve readability.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, IT, DE, ES |
US, UK, CA, FR, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
"ENABLED"
Response body value
A string representing the current value of this setting: "ENABLED"
or "DISABLED"
.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET multiple settings
Call GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults}
to get the values of multiple settings.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings?keys={settingNames}&nextToken={nextToken}&maxResults={maxResults} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request query parameters
Field | Description | Type | Required |
---|---|---|---|
keys |
Comma separated setting names to query. | String | Yes |
nextToken |
The token client uses to query the next page. | String | No |
maxResults |
The maximum result client asks for this page. | String | No |
Request body
None.
Request example
GET /v2/endpoints/{endpointId}/settings?keys=System.temperatureUnit,System.distanceUnits,Alexa.DoNotDisturb.doNotDisturb,System.timeZone HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body errors
When the HTTP response code is 200, there is chance the query on individual setting fails, in which case there are errors in response body with details included.
Status | Code | Description |
---|---|---|
204 | NO_CONTENT | The setting exists, but it doesn't have a value. |
403 | ACCESS_DENIED | The access to the specific setting is unauthorized. |
404 | INVALID_KEY | Setting key doesn't exist or is invalid. |
500 | INTERNAL_SERVER_ERROR | The query on specific setting couldn't be handled because of an internal service error. |
Response body example
{
"paginationContext": {},
"settings": [
{
"key": "System.distanceUnits",
"value": "IMPERIAL"
},
{
"key": "System.temperatureUnit",
"value": "CELSIUS"
}
],
"errors": [
{
"status": 204,
"key": "System.timeZone",
"code": "NO_CONTENT",
"message": "Setting value is empty"
},
{
"status": 403,
"key": "Alexa.DoNotDisturb.doNotDisturb",
"code": "ACCESS_DENIED",
"message": "The access to the specific setting is unauthorized"
}
]
}
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET FollowUp
setting
Call GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode
to get the follow-up mode setting. Valid values: true
or false
. This setting enables Alexa to listen for a subsequent request from the user without requiring the user to say the wake word.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
GET /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
true
Response body value
The current follow-up mode setting: true
or false
.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
GET speaking rate setting
Call GET /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate
to get the speaking rate setting.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
GET /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body example
0.75
Response body value
The response body contains the speaking rate.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
204 | No content | The setting exists, but it doesn't have a value. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
Update endpoint setting value
You can update the current value of most settings for an endpoint by calling PUT /v2/endpoints/{endpointId}/settings/{settingName}
. One exception is the address setting, which uses POST
.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Supported settings
The following settings are supported.
Setting Name | Description | Request Fields | Request Field Description | Request Field Type |
---|---|---|---|---|
address |
Post the address setting. |
address |
The device address. | Object |
Alexa.DoNotDisturb.doNotDisturb |
Put the DoNotDisturb setting. This setting prevents notifications and proactive experiences (calls, etc.) from disturbing the user. |
enabled |
true if the DoNotDisturb setting is enabled, or false otherwise. |
Boolean |
System.locales |
Put the user's preferred locales. In the context of an Alexa device, this setting controls which languages the Alexa-enabled device is expected to understand and respond with. | locales |
List of locale strings. You can specify up to two locales. First element in the list is the preferred locale. Not all skill types are available in all locales. | List |
SpeechRecognizer.wakeWords |
Put the WakeWords setting. This setting controls what alternative wake words the user can say to wake up Alexa. |
wakeWords |
List of wake words, for example, ["ALEXA"]. Alexa supported wake words are ALEXA, AMAZON, COMPUTER, and ECHO. Currently you can only specify one wake word at a time. Note: Not all devices and locales support all wake words. COMPUTER isn't supported in France (fr-FR). | List |
SpeechRecognizer.wakeWordConfirmation |
Put the wakeWordConfirmation setting. This setting enables the user to specify whether they want an audible tone to play in addition to the visual indicator when Alexa detects the wake word. The tone indicates that Alexa is now listening and capturing the request. |
wakeWordConfirmation |
The desired wake word confirmation setting. Alexa-supported wake word confirmation settings are "TONE" and "NONE". | String |
SpeechRecognizer.speechConfirmation |
Put the speechConfirmation setting. This setting allows the user to specify whether they want a short tone to play at the end of their request to Alexa. The tone indicates that Alexa has finished listening to and capturing the request. |
speechConfirmation |
The current speech confirmation setting. Alexa supported speech confirmation settings are "TONE" and "NONE". | String |
SpeechRecognizer.FollowUp |
Put the follow-up mode setting. This setting enables Alexa to listen for a subsequent request from the user without requiring the user to say the wake word. | FollowUp |
true if follow-up mode is enabled, or false otherwise. |
Boolean |
Alexa.ManagedDevice.Settings.errorSuppression |
Put the errorSuppression setting. This setting controls whether the device plays error audio cues (brief, distinctive sounds) for certain errors. |
errorSuppression |
List of error suppressions. Currently the only supported value is CONNECTIVITY . If the list is empty ([]), no errors are suppressed. |
List |
Alexa.ManagedDevice.Settings.maximumVolumeLimit |
Put the maximumVolumeLimit setting. |
maximumVolumeLimit |
A number from 0 to 100, inclusive. | Integer |
System.timeZone |
Put the timeZone setting. |
timeZone |
A time zone string, following the Olson format defined in the Timezone Database. For example: "America/Los_Angeles" . |
String |
System.temperatureUnit |
Put the temperatureUnit setting. |
temperatureUnit |
A temperature string, "CELSIUS" or "FAHRENHEIT" . |
String |
System.distanceUnits |
Put the distanceUnits setting. |
distanceUnits |
A distance unit string, "METRIC" or "IMPERIAL" . |
String |
Accessibility.Captions.AlexaCaptions.enablement |
Put the AlexaCaptions setting. Note: Captions aren't supported in the UK (en-GB) or France (fr-FR). |
AlexaCaptions |
"ENABLED" or "DISABLED" . |
String |
Accessibility.Captions.ClosedCaptions.enablement |
Put the ClosedCaptions setting. Note: Captions aren't supported in the UK (en-GB) or France (fr-FR). |
ClosedCaptions |
"ENABLED" or "DISABLED" . |
String |
Accessibility.Display.Magnifier.enablement |
Put the Magnifier setting. Note: Magnifiers aren't supported in the UK (en-GB) or France (fr-FR). |
Magnifier |
"ENABLED" or "DISABLED" . |
String |
Accessibility.Display.ColorInversion.enablement |
Put the ColorInversion setting. Note: Color inversion isn't supported in the UK (en-GB) or France (fr-FR). |
ColorInversion |
"ENABLED" or "DISABLED" . |
String |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.GET /v2/endpoints/{endpointId}/settings/{SettingName} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
{value}
Response header
Host
value is the same as the Host
value in the request.HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
POST address setting
Call POST /v2/endpoints/{endpointId}/settings/address
to set the address where an endpoint is located. Alexa uses this setting for features like Local Search and Weather. For details, see Enhance Your Skill With Address Information.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.POST /v2/endpoints/{endpointId}/settings/address HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
{
"address": {
"addressLine1": "221 Baker Ave",
"addressLine2": "",
"addressLine3": "",
"city": "Sunnyvale",
"stateOrRegion": "California",
"districtOrCounty": "",
"postalCode": "94085",
"countryCode": "US"
}
}
Request body parameters
Field | Description | Type | Required |
---|---|---|---|
address |
The device address. | Address | Yes |
Address object
Parameter | Description | Type | Required |
---|---|---|---|
addressLine1 |
The first line of the address. | String | Yes |
addressLine2 |
The second line of the address. | String | Yes, may be empty string |
addressLine3 |
The third line of the address. | String | Yes, may be empty string |
city |
The city for the endpoint specified in the request. | String | Yes |
stateOrRegion |
Abbreviation for the state, province or region associated with the endpoint specified in the request. This value may be an empty string for non-US countries. | String | Yes |
districtOrCounty |
The district or county associated with the device. This value may be an empty string for non-US countries. | String | Yes |
postalCode |
The postal code for the endpoint specified in the request. | String | Yes |
countryCode |
The two-letter country/region code for the endpoint specified in the request. | String | Yes |
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: {location}
Response header example
Host: api.amazonalexa.com
X-Amzn-RequestId: 6006f07b-539f-4924-869a-2f8bcf60bdf6
Content-Type: application/json
Location: /v2/endpoints/{endpoint-id}/settings/address
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Location |
Relative path to the created address. | String | Yes |
Response body parameters
The addressSuggestions
and addressErrors
parameters are mutually exclusive.
Parameter | Description | Type | Required |
---|---|---|---|
address |
The device address. | Address | Yes for 201, optional for 400 |
addressSuggestions |
Address suggestions, if the input address was invalid. | List of address suggestions | Optional for 400 |
addressErrors |
Address errors, if the input address was invalid. | List of address errors | Optional for 400 |
Success response body example
{
"address": {
"addressLine1": "221 Baker Ave",
"addressLine2": "",
"addressLine3": "",
"city": "Sunnyvale",
"stateOrRegion": "California",
"districtOrCounty": "",
"postalCode": "94085",
"countryCode": "US"
}
}
Error response body example: 400 address suggestions
If the request is malformed or is missing any required parameters, the operation returns a list of address suggestions, sorted in descending order of confidence.
{
"addressSuggestions": [
{
"address": {
"addressLine1":"221 Baker Ave",
"addressLine2": "",
"addressLine3": "",
"city":"Sunnyvale",
"stateOrRegion":"California",
"districtOrCounty": "",
"postalCode":"94085",
"countryCode":"US"
}
}
],
"code": 400,
"description": "The input address is invalid. Suggested valid addresses are included in the response."
}
Error response body example: 400 address errors
If the request is malformed or is missing any required parameters, the operation returns a list of address errors.
{
"addressErrors": [
{
"code": "FIELD_REQUIRED|FIELD_INVALID",
"subCode": "ADDRESS_STREET_INCOMPLETE|...",
"message": "{human-readable message}",
"element": "ADDRESS_1|ADDRESS_2|..."
}
],
"code": 400,
"description": "The input address is invalid. The list of errors is included in the response."
}
Address errors object
Parameter | Description | Type | Required |
---|---|---|---|
code |
Error code | Enum | No |
subCode |
Additional information about why an address element is invalid. | Enum | No |
message |
Human-readable message | String | No |
element |
Address element to which the error applies. | Enum | No |
Address error code values
code value |
Description |
---|---|
ELEMENT_REQUIRED |
A required element is missing. The element name is specified by the element field. |
ELEMENT_INVALID |
The value in a field is invalid. The element name is specified by the element field. |
Address error subCode values
subCode value |
Description |
---|---|
ADDRESS_PRIMARY_RANGE_MISSING_OR_INVALID |
The address number was not valid. |
ADDRESS_STREET_INCOMPLETE |
The street address was not complete. |
ADDRESS_LINES_JUNK_DATA |
The address line field contains junk data. |
ADDRESS_FIELD_LENGTH_HIGH |
The length of the address field is greater than allowed. |
ADDRESS_CITY_INVALID |
There is no city of that name in the specified state. |
ADDRESS_COUNTY_INVALID |
The specified county is incorrect. |
ADDRESS_STATE_INVALID |
The specified state is incorrect. |
ADDRESS_ZIP_INVALID |
The specified zip code is incorrect for the specified street, city and/or state. |
ADDRESS_STREET_NOT_FOUND |
The street was not found in the specified city. |
ADDRESS_MULTIBYTE_CHARACTERS |
The field has multi-byte characters. |
ADDRESS_DOOR_LEVEL_INFO_MISSING |
The address door-level info is missing. |
FIELD_EMPTY |
A required field was empty. |
Address element values
Address element | Description |
---|---|
ADDRESS_1 |
First line of the address. |
ADDRESS_2 |
Second line of the address, if any. |
ADDRESS_3 |
Third line of the address, if any. |
STREET_NAME |
Street name present in the address. |
BUILDING_NUMBER |
Building number. |
COMPLEMENT |
Number for smaller units in a building, such as an apartment number. |
NEIGHBORHOOD |
Neighborhoods are smaller regions of city. |
CITY |
City or municipality that contains the address. |
STATE |
U.S. state or possession that contains the address. |
COUNTRY |
Country that contains the address. |
ZIP |
5-digit or 9-digit zip code of the address. |
COUNTY |
County that contains the address. |
COUNTRY_CODE |
Country code of the address. |
HTTP response codes
Status Code | Name | Description |
---|---|---|
201 | Accepted | The request succeeded. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed, is missing one or more required parameters, or the address is invalid and there is an address suggestion. For details, see Error response body example: 400 address suggestions and Error response body example: 400 address errors. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
429 | Too many requests | Request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
503 | Service Unavailable | Service is temporarily unavailable. |
PUT DoNotDisturb setting
Call PUT /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb
to update the DoNotDisturb
setting. This call prevents notifications and proactive experiences (calls, etc.) from disturbing the user.
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 |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/Alexa.DoNotDisturb.doNotDisturb HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
true
Request body value
A Boolean value: true
to enable the DoNotDisturb
setting, or false
otherwise.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested artifact wasn't found for the client. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT Locales setting
Call PUT /v2/endpoints/{endpointId}/settings/System.locales
to update the locale setting. In the context of an Alexa device, this setting controls which languages the Alexa-enabled device is expected to understand and respond with.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/System.locales HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body examples
["en-US", "es-US"]
["en-US", "fr-FR"]
Request body value
List of locale strings. Specify at least one and no more than two locales. The first element in the list specifies the preferred locale. The following locales are supported: en-CA, en-GB, en-US, fr-FR, and fr-CA. This API also supports the following language pairs: en-US/fr-FR, fr-FR/en-US, en-CA/fr-CA, and fr-CA/en-CA. Not all skill types are available in all locales.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT WakeWords setting
Call PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords
to update the WakeWords
setting. This setting controls what alternative wake words can be used to wake up Alexa.
The supported wake words are: ALEXA, AMAZON, COMPUTER, and ECHO. Currently you can only specify one wake word at a time. Note: Not all devices and locales support all wake words. COMPUTER isn't supported in France (fr-FR).
WakeWords
setting for a device, you must set the Locales
setting. For details, see Put Locales
setting.This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWords HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
["ALEXA"]
Request body value
List of wake words, for example, ["ALEXA"].
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT WakeWordConfirmation setting
Call PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation
to update the start-of-request sound setting. This setting enables the user to specify whether they want an audible tone to play in addition to the visual indicator when Alexa detects the wake word. The tone indicates that Alexa is now listening and capturing the request.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.wakeWordConfirmation HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
"NONE"
Request body value
A string containing the desired wake word confirmation setting. Alexa supported wake word confirmation settings are "TONE" and "NONE".
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT SpeechConfirmation setting
Call PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation
to update the end-of-request sound setting. This setting allows the user to specify whether they want a short tone to play at the end of their request to Alexa to indicate that Alexa has finished listening to and capturing the request.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.speechConfirmation HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
"NONE"
Request body value
A string containing the desired speech confirmation setting. Alexa supported speech confirmation settings are "TONE" and "NONE".
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT ErrorSuppression setting
Call PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression
to update the list of error suppressions. This setting controls whether the device plays error audio cues (brief, distinctive sounds) for certain errors.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.errorSuppression HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
["CONNECTIVITY"]
Request body value
The list of error suppressions. Currently the only supported value is ["CONNECTIVITY"]
. An empty list shows that no errors are to be suppressed.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested artifact wasn't found for the client. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT MaximumVolumeLimit setting
Call PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit
to update the maximum volume limit.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/Alexa.ManagedDevice.Settings.maximumVolumeLimit HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
42
Request body value
An integer value from 0 to 100, inclusive.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT TimeZone setting
Call PUT /v2/endpoints/{endpointId}/settings/System.timeZone
to update the time zone.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/System.timeZone HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
"America/Los_Angeles"
Request body value
A time zone string, following the Olson format defined in the Timezone Database. For example: "America/Los_Angeles"
.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT TemperatureUnit setting
Call PUT /v2/endpoints/{endpointId}/settings/System.temperatureUnit
to update the temperature scale (Celsius or Fahrenheit) setting.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/System.temperatureUnit HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
"CELSIUS"
Request body value
A temperature string: "CELSIUS"
or "FAHRENHEIT"
.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT DistanceUnits setting
Call PUT /v2/endpoints/{endpointId}/settings/System.distanceUnits
to update the distance units (Metric or Imperial) setting.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/System.distanceUnits HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
"METRIC"
Request body value
A distance unit string: "METRIC"
or "IMPERIAL"
.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT AlexaCaptions setting
Call PUT /v2/endpoints/{endpointId}/settings/Accessibility.Captions.AlexaCaptions.enablement
to update the Alexa caption setting.
This setting controls whether a multimedia device displays the following information:
- Alexa captions, which provide the text version of what Alexa speaks via SpeechSynthesizer. All domains that use Alexa Voice Service (AVS) should provide captions.
- The captions that accompany AudioPlayer directives.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, IT, DE |
US, UK, CA, FR, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/Accessibility.Captions.AlexaCaptions.enablement HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
"ENABLED"
Request body value
A string representing the desired value of this setting: "ENABLED"
or "DISABLED"
.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT ClosedCaptions setting
Call PUT /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement
to update the Alexa caption setting.
This setting controls whether a multimedia device displays closed captions for video content.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, IT, DE |
US, UK, CA, FR, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/Accessibility.Captions.ClosedCaptions.enablement HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
"ENABLED"
Request body value
A string representing the desired value of this setting: "ENABLED"
or "DISABLED"
.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT Magnifier setting
Call PUT /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement
to update the device magnifier setting.
This setting gives the device user the ability to enlarge items on the screen to improve readability.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, IT, DE |
US, UK, CA, FR, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/Accessibility.Display.Magnifier.enablement HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
"ENABLED"
Request body value
A string representing the desired value of this setting: "ENABLED"
or "DISABLED"
.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT ColorInversion setting
Call PUT /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement
to get the screen color inversion setting.
This setting gives the device user the ability to invert the screen display colors to improve readability.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, IT, DE |
US, UK, CA, FR, IT, DE |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.PUT /v2/endpoints/{endpointId}/settings/Accessibility.Display.ColorInversion.enablement HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
"ENABLED"
Request body value
A string representing the desired value of this setting: "ENABLED"
or "DISABLED"
.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Response header parameters
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT FollowUp
setting
Call PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode
to update the follow-up mode setting. Valid values: true
or false
. This setting enables Alexa to listen for a subsequent request from the user without requiring the user to say the wake word.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
PUT /v2/endpoints/{endpointId}/settings/SpeechRecognizer.FollowUp.mode HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
false
Request body value
The new follow-up mode setting: true
or false
.
Response header
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
PUT speaking rate setting
Call PUT /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate
to update the speaking rate setting.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
PUT /v2/endpoints/{endpointId}/settings/SpeechSynthesizer.speakingRate HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body example
0.75
Request body value
The new speaking rate setting. Accepted values: 0.75
, 0.85
, 1
, 1.25
, 1.5
, 1.75
, and 2
. The default setting is 1
.
Response header
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Response body
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 | No content | Setting applied. |
400 | Bad Request (INVALID_REQUEST, INVALID_VALUE, DEVICE_UNREACHABLE, DEVICE_NOT_SUPPORTED) | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested endpoint wasn't found. |
405 | Method Not Allowed | The device doesn't support the setting. |
429 | Too many requests | The request is throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
Deregister endpoint
Call POST /v2/endpoints/{endpointId}/deregister
to deregister an endpoint from your Amazon Business account.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.POST /v2/endpoints/{endpointId}/deregister HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request body
None.
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Response body
None.
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request, for example, 1K82TJNQTXSJFP8NGJP0. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String | No |
HTTP response codes
Status code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
400 | Bad Request | The request is malformed or is missing one or more required parameters. |
401 | Unauthorized | The access token is missing, expired, or invalid. |
403 | Forbidden | The access token is valid, but the user doesn't have the needed LWA scope permissions. |
429 | Too many requests | The request was throttled. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-429 response is received. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. Retry after one second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until a non-500 response is received. |
503 | Service Unavailable | Service is temporarily unavailable. |
Change an endpoint's friendly name
Call POST /v2/endpoints/{endpointId}/friendlyName
to change the friendly name for an endpoint. Alexa uses the friendly name for all GUI and VUI experiences. Customers can use the friendly name to control an endpoint, for example, "Alexa, turn on {friendlyName}."
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.POST /v2/endpoints/{endpointId}/friendlyName HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body format
{
"type": "PLAIN",
"value": {
"text": "{friendlyNameString}"
}
}
Request body example
{
"type": "PLAIN",
"value": {
"text": "My Light"
}
}
Request body parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The name value type. Currently the only supported value is "PLAIN" . |
String | Yes |
value |
A Value object containing the friendly name for the endpoint. | Value | Yes |
Value object
Field | Description | Type | Required |
---|---|---|---|
text |
The friendly name string. The string must consist of 1 to 128 Unicode (UTF-8) characters and must not contain special characters or punctuation (except for apostrophes). The following rules apply. * Characters must be numbers, letters (Chinese characters and non-Roman letters are permitted), spaces, or apostrophes. * Names must contain at least one number or letter. |
String | Yes |
Response header
Host
value is the same as the Host
value in the request.HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Error response body format
{
"type" : "{errorType}" ,
"message" : "{errorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type for the error. Present only if the request was valid but the service failed to execute the request. This field can be used by business logic. | String | No |
message |
The error message for the error. The error message is exposed only for debugging/logging purposes. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status code | Type | Message | Description |
---|---|---|---|
200 | OK | The request succeeded. | |
400 | INVALID_FRIENDLY_NAME | The input friendly name has the following problems: {problemString} | The request is missing one or more required parameters, or one or more parameter values aren't valid. |
400 | DUPLICATE_NAME | The input friendly name is already assigned to another device. | Friendly names must be unique. |
401 | UNAUTHORIZED | Invalid or missing access token | The LWA token is missing, expired, or invalid. |
403 | FORBIDDEN | Forbidden | The client can list the resource but doesn't have permission to rename the resource. |
404 | NO_SUCH_ENDPOINT | Endpoint not found | The endpoint in the path doesn't exist, or the client does not have permission to list the resource. |
429 | TOO_MANY_REQUESTS | Too Many Requests | Request was throttled. Retry after 1 second, backing off exponentially until a 256-second wait, retrying every 256 seconds thereafter until you receive a non-429 response. |
500 | INTERNAL_SERVER_ERROR | Internal Service Error | A service error occurred. |
503 | SERVICE_UNAVAILABLE | Service Unavailable | The service is temporarily unavailable to handle the request. |
Forget endpoint
Call POST /v2/endpoints/{endpointId}/forget
to forget an endpoint.
forget
.This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.POST /v2/endpoints/{endpointId}/forget HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body
None.
Response header
Host
value is the same as the Host
value in the request.HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. | String | Yes |
Error response body format
{
"message": "{errorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
message |
The error message for the error. | String | No |
HTTP response codes
Status code | Name | Description |
---|---|---|
200 | OK | The request succeeded. |
400 | Bad Request | The request is missing one or more required parameters, or one or more parameter values aren't valid. |
401 | Unauthorized | The LWA token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested resource wasn't found, or the client doesn't have access to it. |
429 | Too many requests | Request was throttled. Don't perform automatic retries. Wait until the service has recovered, and then retry the operation. |
500 | Internal Server Error | A service error occurred. Retry after one second, backing off exponentially with jitter until a 256-second wait. Retry every 256 seconds thereafter until you receive a non-500 response. |
503 | Service Unavailable | The service is temporarily unavailable to handle the request. |
Delete all timers for an endpoint
Call DELETE /v1/alerts/timers?endpoint={endpointId}
to delete all timers on an endpoint. To delete timers on all endpoints in a unit, see [Delete all timers for a unit] (../alexa-smart-properties/unit-api.html#delete-all-timers-for-unit)
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
CA,DE, ES, FR, IT, US, UK |
CA,DE, ES, FR, IT, US, UK |
None |
Request format
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.DELETE /v1/alerts/timers?endpoint={endpointId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: {LWA Token}
Request body
None.
Request parameters
Field | Description | Type | Required |
---|---|---|---|
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Response header
Host
value is the same as the Host
value in the request.Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type | Required |
---|---|---|---|
|
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response
Upon successful deletion, the server returns an HTTP 204 No Content
status response. A successful payload doesn't contain a body.
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Error response
HTTP/1.1 {ErrorCode}
Content-Type: application/json
{
"errors": [{
"type": "{ErrorType}",
"endpointId": "{EndpointId}",
"message": "{ErrorMessage}"
}]
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
|
The error name, such as |
String |
No |
|
The endpoint ID, in the Amazon Common Identifier (ACI) format |
String |
No |
|
The error message for the error. The error message appears only for debugging/logging purposes. You must not share it with the user. No business logic should depend on the content of the error message. |
String |
No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
204 |
No content |
Timers were successfully deleted on the endpoint. Note that this status code is returned even if the endpoint has no timers to delete. |
400 |
BAD_REQUEST |
The request is malformed or is missing one or more required parameters. |
401 |
UNAUTHORIZED |
The authentication token is invalid or doesn't have access to the resource. |
403 |
FORBIDDEN |
The user doesn't have permission to perform the operation, or the unit doesn't exist. |
404 |
NOT FOUND |
The requested resource wasn't found, or the client doesn't have access to it. |
500 |
INTERNAL_SERVER_ERROR |
The request couldn't be handled because of an internal service error. |
504 |
DEVICE_NOT_REACHABLE |
The device is offline or unreachable. |
Related topics
Last updated: Nov 28, 2023