Endpoint Features REST API Reference
Use the Endpoint Features REST API to view and update Alexa-connected endpoint properties, such as power state on a smart home light. You use the Endpoint Features API along with the Endpoints REST API to view and change settings on devices owned by your Amazon Business account. To manage Wi-Fi configurations, see Endpoint Wi-Fi Management REST API Reference.
API endpoints
Based on the country of your organization, set the Host
parameter in the request header to one of the following API endpoints.
Country | Endpoint |
---|---|
CA, US |
|
DE, ES, FR, IT, UK |
|
JP |
|
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.
Operations
The Endpoint Features API includes the following operations.
Operation | HTTP method and URI |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
Get Bluetooth properties
Get the Bluetooth properties of the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
None |
US, UK, FR, CA, IT, DE, JP |
US, UK, FR, CA, IT, DE, JP |
None |
Request
To get Bluetooth properties, you make a GET
request to the features/bluetooth
resource.
Request path and header example
GET /v2/endpoints/{endpointId}/features/bluetooth
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body parameters
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the Bluetooth properties.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The following example shows a response.
{
"operations": [
{
"name": "unpair",
"path": "/v2/endpoints/{endpointId}/features/bluetooth/unpair"
}
]
}
Response body parameters
Parameter | Description | Type |
---|---|---|
|
List of properties for the endpoint. |
Array of objects |
|
Name of the property. |
String |
|
Type of the property. |
String |
|
(Optional) Describes the error encountered. |
Error object |
|
List of update operations available for this feature and endpoint. |
Array of Operation objects |
|
Configuration data accessible to the caller. |
List of configuration objects |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the current values of the requested property. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get brightness
Get the brightness level of the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To get the brightness level, you make a GET
request to the features/brightness
resource.
Request path and header example
GET /v2/endpoints/{endpointId}/features/brightness
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the current brightness level.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"properties": [{
"name": "brightness",
"type": "RETRIEVABLE",
"value": {
"value": 50
},
"timeOfSample": "2024-08-23T12:00:30.02Z"
}],
"operations": [
{
"name": "setBrightness",
"path": "/v2/endpoints/{id}/features/brightness/setBrightness"
},
{
"name": "adjustBrightness",
"path": "/v2/endpoints/{id}/features/brightness/adjustBrightness"
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of properties for the endpoint. |
Array of objects |
|
Name of the property. |
String |
|
Type of the property. |
String |
|
Brightness properties. |
Object |
|
Current brightness level of the endpoint. |
Integer |
|
Time the endpoint detected the state change. |
String |
|
(Optional) Describes the error encountered. |
Error object |
|
List of update operations available for this feature and endpoint. |
Array of Operation objects |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the current value of the requested property. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get color
Get the hue, saturation, and brightness of the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To get the color, you make a GET
request to the features/color
resource.
Request path and header example
GET /v2/endpoints/{endpointId}/features/color
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the current hue, saturation, and brightness of the endpoint.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"properties": [{
"name": "color",
"type": "RETRIEVABLE",
"value": {
"hue": 20,
"saturation": 0.5,
"brightness": 0.7
},
"timeOfSample": "2024-07-02T06:20:50.52Z"
}],
"operations": [
{
"name": "setColor",
"path": "/v2/endpoints/{endpointId}/features/color/setColor"
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of properties for the endpoint. |
Array of objects |
|
Name of the property. |
String |
|
Type of the property. |
String |
|
Current color of the endpoint. |
Color object |
|
Current hue value of the color. |
Integer |
|
Current saturation level of the color. |
Double |
|
Current brightness. |
Double |
|
Time the endpoint detected the state change. |
String |
|
(Optional) Describes the error encountered. |
Error object |
|
List of update operations available for this feature and endpoint. |
Array of Operation objects |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the current value of the requested property. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get color temperature
Get the color temperature of endpoints that support tunable white light, such as light bulbs.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To get the color temperature, you make a GET
request to the features/colorTemperature
resource.
Request path and header example
GET /v2/endpoints/{endpointId}/features/colorTemperature
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the current color temperature.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"properties": [{
"name": "colorTemperatureInKelvin",
"type": "RETRIEVABLE",
"value": {
"value": 2700
},
"timeOfSample": "2024-07-02T06:20:50.52Z"
}],
"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 properties
Property | Description | Type |
---|---|---|
|
List of properties for the endpoint. |
Array of objects |
|
Name of the property. |
String |
|
Type of the property. |
String |
|
Color properties. |
Object |
|
Current color temperature in degrees Kelvin of an endpoint. For details about shades of white, see Color temperature values. |
Integer |
|
Time the endpoint detected the state change. |
String |
|
(Optional) Describes the error encountered. |
Error object |
|
List of update operations available for this feature and endpoint. |
Array of Operation objects |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the current value of the requested property. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get connectivity status
Get the connection status of the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To get the connection status, you make a GET
request to the features/connectivity
resource.
Request path and header example
GET /v2/endpoints/{endpointId}/features/connectivity
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the connection status of the endpoint.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"properties": [{
"name": "reachability",
"type": "RETRIEVABLE",
"value": {
"value": "OK"
},
"timeOfSample": "2024-07-03T10:20:50.52Z"
}]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of properties for the endpoint. |
Array of objects |
|
Name of the property. |
String |
|
Type of the property. |
String |
|
Connectivity properties. |
Object |
|
Current connectivity status of the endpoint. Valid values:
|
String |
|
Time the endpoint detected the state change. |
String |
|
(Optional) Describes the error encountered. |
Error object |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the current value of the requested property. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get power state
Determine if the power of the specified endpoint is on or off.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To get the power state, you make a GET
request to the features/power
resource.
Request path and header example
GET /v2/endpoints/{endpointId}/features/power
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the power state of the endpoint.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"properties": [{
"name": "powerState",
"type": "RETRIEVABLE",
"value": {
"value": "ON"
},
"timeOfSample": "2024-07-02T06:44:02.32Z"
}],
"operations": [
{
"name": "turnOn",
"path": "/v2/endpoints/{endpointID}/features/power/turnOn"
},
{
"name": "turnOff",
"path": "/v2/endpoints/{endpointID}/features/power/turnOff"
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of properties for the endpoint. |
Array of objects |
|
Name of the property. |
String |
|
Type of the property. |
String |
|
Power properties. |
Object |
|
Current power state of the endpoint.
Valid values: |
String |
|
Time the endpoint detected the state change. |
String |
|
(Optional) Describes the error encountered. |
Error object |
|
List of update operations available for this feature and endpoint. |
Array of Operation objects |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the current value of the requested property. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get speaker properties
Get the speaker properties of the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To get the speaker properties, you make a GET
request to the features/speaker
resource.
Request path and header example
GET /v2/endpoints/{endpointId}/features/speaker
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the speaker properties of the endpoint.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"properties": [{
"name": "volume",
"type": "RETRIEVABLE",
"value": {
"value": "42"
},
"timeOfSample": "2024-08-13T10:20:50.52Z"
}],
"operations": [
{
"name": "setVolume",
"path": "/v2/endpoints/<id>/features/speaker/setVolume"
},
{
"name": "adjustVolume",
"path": "/v2/endpoints/<id>/features/speaker/adjustVolume"
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of properties for the endpoint. |
Array of objects |
|
Name of the property. |
String |
|
Type of the property. |
String |
|
Speaker properties. |
Object |
|
Current volume. Valid values: 0–100. |
Integer |
|
Time the endpoint detected the state change. |
String |
|
(Optional) Describes the error encountered. |
Error object |
|
List of update operations available for this feature and endpoint. |
Array of Operation objects |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the current value of the requested property. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get temperature sensor
Get the current temperature detected by the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To get the temperature, you make a GET
request to the features/temperatureSensor
resource.
Request path and header example
GET /v2/endpoints/{endpointId}/features/temperatureSensor
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the current temperature.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"properties": [{
"name": "temperature",
"type": "RETRIEVABLE",
"value": {
"value": 68.0,
"scale": "FAHRENHEIT"
},
"timeOfSample": "2024-07-02T06:44:02.32Z"
}]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of properties for the endpoint. |
Array of objects |
|
Name of the property. |
String |
|
Type of the property. |
String |
|
Temperature property. |
Temperature object |
|
Current temperature detected by the endpoint. |
Double |
|
Temperature scale. |
String |
|
Time the endpoint detected the state change. |
String |
|
(Optional) Describes the error encountered. |
Error object |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the current value of the requested properties. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get thermostat properties
Get the thermostat mode and setpoints for the specified endpoint. A single-setpoint thermostat has a single temperature setting. A dual-setpoint thermostat has two temperature settings, a lower and upper setpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To get the thermostat properties, you make a GET
request to the features/thermostat
resource.
Request path and header example
GET /v2/endpoints/{endpointId}/features/thermostat
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with the thermostat mode and setpoints of the thermostat endpoint.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The follow example shows the thermostat properties of a single-setpoint thermostat.
The follow example shows the thermostat properties of a dual-setpoint thermostat.
Response body properties
Property | Description | Type |
---|---|---|
|
List of properties for the endpoint. |
Array of objects |
|
Name of the property. |
String |
|
Type of the property. |
String |
|
Thermostat properties of the specified endpoint. |
Object |
|
Current value of the property specified by name.
Valid values for |
String for |
|
Temperature scale. Included for |
String |
|
Time the endpoint detected the state change. |
String |
|
(Optional) Describes the error encountered. |
Error object |
|
Supported thermostat modes. |
Object |
|
List of modes that the thermostat endpoint supports.
Valid values: |
Array of string |
|
List of update operations available for this feature and endpoint. |
Array of Operation objects |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the current value of the requested properties. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Unpair Bluetooth devices
Unpair all Bluetooth devices from the specified Alexa-enabled endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, CA, DE, ES, FR, IT, UK, JP |
US, CA, DE, ES, FR, IT, UK, JP |
US |
Request
To unpair Bluetooth devices, you make a POST
request to the features/bluetooth/
resource.
Request path and header example
POST /v2/endpoints/{endpointId}/features/bluetooth/unpair
Host: api.amazonalexa.com
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 202 Accepted
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Devices unpaired successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update brightness
Set the brightness level for the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, JP |
US, UK, FR, CA, IT, DE, JP |
US |
Request
To set the brightness, you make a POST
request to the features/brightness
resource.
Request path and header example
POST /v2/endpoints/{endpointId}/features/brightness/{operation}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Path |
Operation to adjust or set the brightness level.
Valid values: |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The following example shows the request body for the adjustBrightness
operation.
{
"payload": {
"brightnessDelta": -25
}
}
The following example shows the request body for the setBrightness
operation.
{
"payload": {
"brightness": 75
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Information required to control the |
Object |
Yes |
|
Percentage amount to set the brightness of the endpoint. |
Integer |
No |
|
Percentage amount by which to change the brightness of the endpoint. Include with |
Integer |
No |
Response
A successful response returns HTTP 200 OK
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Property updated successfully on the specified endpoint. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update color
Set the color for the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, JP |
US, UK, FR, CA, IT, DE, JP |
US |
Request
To set the color, you make a POST
request to the features/color
resource.
Request path and header example
POST /v2/endpoints/{endpointId}/features/color/setColor`
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"payload": {
"color": {
"hue": 20,
"saturation": 0.75,
"brightness": 0.34
}
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Information required to control the |
Object |
Yes |
|
Defines the color to set the endpoint. |
Integer |
Yes |
|
Current hue value of the color. |
Integer |
Yes |
|
Current saturation level of the color. |
Double |
Yes |
|
Current brightness. |
Double |
Yes |
Response
A successful response returns HTTP 200 OK
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Property updated successfully on the specified endpoint. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update color temperature
Set the color temperature for the specified endpoint. You can set the color temperature to a specific value. Or, you can increase to a cooler or whiter setting relative to the current setting or decrease to a warmer or softer setting relative to the current setting. The endpoint manufacturer chooses how much to increase and decrease the setting.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, JP |
US, UK, FR, CA, IT, DE, JP |
US |
Request
To set the color temperature, you make a POST
request to the features/colorTemperature
resource.
Request path and header example
POST /v2/endpoints/{endpointId}/features/colorTemperature/{operation}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Path |
Color temperature operation to adjust or set the color temperature. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The decreaseColorTemperature
and increaseColorTemperature
operations have no request body.
The following example shows the request body for the setColorTemperature
operation.
{
"payload": {
"colorTemperatureInKelvin": 2000
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Information required to control the |
Object |
No |
|
Color temperature in degrees Kelvin of an endpoint. For details about shades of white, see Color temperature values. |
Integer |
No |
Response
A successful response returns HTTP 200 OK
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Property updated successfully on the specified endpoint. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update power state
Turn the power on or off for the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, JP |
US, UK, FR, CA, IT, DE, JP |
US |
Request
To set the power state, you make a POST
request to the features/power
resource.
Request path and header example
POST /v2/endpoints/{endpointId}/features/power/{operation}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Path |
Operation used to turn on and off the power.
Valid values: |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Property updated successfully on the specified endpoint. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update speaker properties
Set or adjust the speaker volume for the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To set the speaker properties, you make a POST
request to the features/speaker
resource.
Request path and header example
POST /v2/endpoints/{endpointId}/features/speaker/{operation}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
Yes |
|
Path |
Operation used to set or adjust the speaker volume.
Valid values: |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The following example shows the request body for the adjustVolume
operation.
{
"payload": {
"volumeDelta": -25
}
}
The following example shows the request body for the setVolume
operation.
{
"payload": {
"volume": 75
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Information required to control the |
Object |
Yes |
|
Amount to set the volume of the endpoint. |
Integer |
No |
|
Amount by which to change the volume of the endpoint. Include with |
Integer |
No |
Response
A successful response returns HTTP 200 OK
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Property updated successfully on the specified endpoint. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Object definitions
The Endpoint Features API defines the following object definitions and property values.
Color temperature values
The following table lists example color temperature values for shades of white.
Shade | Color temperature in absolute Kelvin |
---|---|
warm, warm white |
2200 |
incandescent, soft white |
2700 |
white |
4000 |
daylight, daylight white |
5500 |
cool, cool white |
7000 |
Operation object
The Operation
object describes the update operations available for the specified endpoint and feature.
Property | Description | Type |
---|---|---|
|
Name of the update operation. |
String |
|
Full HTTP path that you can use in an update operation to set the |
String |
Temperature object
The Temperature
object represents the current temperature detected by the endpoint.
Property | Description | Type |
---|---|---|
|
Temperature in degrees. |
Double |
|
Temperature scale. |
String |
ThermostatMode values
The following table shows the mode value strings for thermostats. A thermostat might not support all modes.
Value | Description |
---|---|
|
Automatic heating or cooling based on the current temperature and the setpoint. |
|
Cooling mode. |
|
Economy mode. |
|
Emergency heating mode. |
|
Heating mode. |
|
Heating and cooling are off, but the device might still have power. |
Error object
The Error
object describes the error that occurred.
Property | Description | Type |
---|---|---|
|
Type of error that occurred. |
String |
|
Human readable error message. |
String |
Related topics
- Alexa Smart Properties REST API Reference
- Endpoints REST API Reference
- Endpoint Settings REST API Reference
- Endpoint Wi-Fi Management REST API Reference
Last updated: Sep 25, 2024