Endpoint Features REST API Reference

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

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

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	`https://api.amazonalexa.com`
DE, ES, FR, IT, UK	`https://api.eu.amazonalexa.com`
JP	`https://api.fe.amazonalexa.com`

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.

Operations

The Endpoint Features API includes the following operations.

Operation	HTTP method and URI
Get Bluetooth properties	`GET /v2/endpoints/{endpointId}/features/bluetooth`
Get brightness	`GET /v2/endpoints/{endpointId}/features/brightness`
Get color	`GET /v2/endpoints/{endpointId}/features/color`
Get color temperature	`GET /v2/endpoints/{endpointId}/features/colorTemperature`
Get connectivity status	`GET /v2/endpoints/{endpointId}/features/connectivity`
Get power state	`GET /v2/endpoints/{endpointId}/features/power`
Get speaker properties	`GET /v2/endpoints/{endpointId}/features/speaker`
Get temperature sensor	`GET /v2/endpoints/{endpointId}/features/temperatureSensor`
Get thermostat properties	`GET /v2/endpoints/{endpointId}/features/thermostat`
Unpair Bluetooth devices	`POST /v2/endpoints/{endpointId}/features/bluetooth/unpair`
Update brightness	`POST /v2/endpoints/{endpointId}/features/brightness/{operation}`
Update color	`POST /v2/endpoints/{endpointId}/features/color/setColor`
Update color temperature	`POST /v2/endpoints/{endpointId}/features/colorTemperature/{operation}`
Update power state	`POST /v2/endpoints/{endpointId}/features/power/{operation}`
Update speaker properties	`POST /v2/endpoints/{endpointId}/features/speaker/{operation}`

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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body 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 object.

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
`properties`	List of properties for the endpoint. If you don't have permission to view the data, the list is empty.	Array of objects
`properties[].name`	Name of the property. Valid value: `none`.	String
`properties[].type`	Type of the property. If set to `ERROR`, you can retry the request. Valid values: `RETRIEVABLE`, `NOT_RETRIEVABLE`, `ERROR`.	String
`properties[].error`	(Optional) Describes the error encountered. Included when `type = ERROR`.	Error object
`operations`	List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of Operation objects
`configuration`	Configuration data accessible to the caller. Valid values: `none`.	List of configuration objects

HTTP status codes

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

Get 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the current brightness level. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

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
`properties`	List of properties for the endpoint. If you don't have permission to view the data, the list is empty.	Array of objects
`properties[].name`	Name of the property. Valid value: `brightness`.	String
`properties[].type`	Type of the property. If set to `ERROR`, you can retry the request. Valid values: `RETRIEVABLE`, `NOT_RETRIEVABLE`, `ERROR`.	String
`properties[].value`	Brightness properties.	Object
`properties[].value.value`	Current brightness level of the endpoint. Valid values: 0–100.	Integer
`properties[].timeOfSample`	Time the endpoint detected the state change. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`properties[].error`	(Optional) Describes the error encountered. Included when `type = ERROR`.	Error object
`operations`	List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of Operation objects

HTTP status codes

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

Get 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the 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 object.

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
`properties`	List of properties for the endpoint. If you don't have permission to view the data, the list is empty.	Array of objects
`properties[].name`	Name of the property. Valid value: `color`.	String
`properties[].type`	Type of the property. If set to `ERROR`, you can retry the request. Valid values: `RETRIEVABLE`, `NOT_RETRIEVABLE`, `ERROR`.	String
`properties[].value`	Current color of the endpoint.	Color object
`properties[].value.hue`	Current hue value of the color. Valid values: 0–360.	Integer
`properties[].value.saturation`	Current saturation level of the color. Valid values: 0.0–1.0, inclusive.	Double
`properties[].value.brightness`	Current brightness. Valid values: 0.0–1.0, inclusive.	Double
`properties[].timeOfSample`	Time the endpoint detected the state change. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`properties[].error`	(Optional) Describes the error encountered. Included when `type = ERROR`.	Error object
`operations`	List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of Operation objects

HTTP status codes

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

Get 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the current color temperature. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

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
`properties`	List of properties for the endpoint. If you don't have permission to view the data, the list is empty.	Array of objects
`properties[].name`	Name of the property. Valid value: `colorTemperatureInKelvin`.	String
`properties[].type`	Type of the property. If set to `ERROR`, you can retry the request. Valid values: `RETRIEVABLE`, `NOT_RETRIEVABLE`, `ERROR`.	String
`properties[].value`	Color properties.	Object
`properties[].value`	Current color temperature in degrees Kelvin of an endpoint. For details about shades of white, see Color temperature values. Valid values: 1000–10000.	Integer
`properties[].timeOfSample`	Time the endpoint detected the state change. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`properties[].error`	(Optional) Describes the error encountered. Included when `type = ERROR`.	Error object
`operations`	List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of Operation objects

HTTP status codes

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

Get 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the connection status of the endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
    "properties": [{
        "name": "reachability",
        "type": "RETRIEVABLE",
        "value": {
            "value": "OK"
        },
        "timeOfSample": "2024-07-03T10:20:50.52Z"
    }]
}

Response body properties

Property	Description	Type
`properties`	List of properties for the endpoint. If you don't have permission to view the data, the list is empty.	Array of objects
`properties[].name`	Name of the property. Valid value: `reachability`.	String
`properties[].type`	Type of the property. If set to `ERROR`, you can retry the request. Valid values: `RETRIEVABLE`, `NOT_RETRIEVABLE`, `ERROR`.	String
`properties[].value`	Connectivity properties.	Object
`properties[].value.value`	Current connectivity status of the endpoint. Valid values: `OK` – The device is connected to the network `UNREACHABLE` – The device isn't connected to the network. For example, the device is unplugged, or the network isn't available. `NOT_FOUND` – The device has been offline for more than 30 days, or there is no device state reported. This status typically indicates an unplugged device.	String
`properties[].timeOfSample`	Time the endpoint detected the state change. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`properties[].error`	(Optional) Describes the error encountered. Included when `type = ERROR`.	Error object

HTTP status codes

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

Get 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the power state of the endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

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
`properties`	List of properties for the endpoint. If you don't have permission to view the data, the list is empty.	Array of objects
`properties[].name`	Name of the property. Valid value: `powerState`.	String
`properties[].type`	Type of the property. If set to `ERROR`, you can retry the request. Valid values: `RETRIEVABLE`, `NOT_RETRIEVABLE`, `ERROR`.	String
`properties[].value`	Power properties.	Object
`properties[].value.value`	Current power state of the endpoint. Valid values: `ON`, `OFF`.	String
`properties[].timeOfSample`	Time the endpoint detected the state change. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`properties[].error`	(Optional) Describes the error encountered. Included when `type = ERROR`.	Error object
`operations`	List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of Operation objects

HTTP status codes

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

Get 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the speaker properties of the endpoint. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

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
`properties`	List of properties for the endpoint. If you don't have permission to view the data, the list is empty.	Array of objects
`properties[].name`	Name of the property. Valid value: `volume`.	String
`properties[].type`	Type of the property. If set to `ERROR`, you can retry the request. Valid values: `RETRIEVABLE`, `NOT_RETRIEVABLE`, `ERROR`.	String
`properties[].value`	Speaker properties.	Object
`properties[].value.value`	Current volume. Valid values: 0–100.	Integer
`properties[].timeOfSample`	Time the endpoint detected the state change. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`properties[].error`	(Optional) Describes the error encountered. Included when `type = ERROR`.	Error object
`operations`	List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of Operation objects

HTTP status codes

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

Get 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the current temperature. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

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
`properties`	List of properties for the endpoint. If you don't have permission to view the data, the list is empty.	Array of objects
`properties[].name`	Name of the property. Valid values: `temperature`.	String
`properties[].type`	Type of the property. If set to `ERROR`, you can retry the request. Valid values: `RETRIEVABLE`, `NOT_RETRIEVABLE`, `ERROR`.	String
`properties[].value`	Temperature property.	Temperature object
`properties[].value.value`	Current temperature detected by the endpoint.	Double
`properties[].value.scale`	Temperature scale. Valid values: `CELSIUS`, `FAHRENHEIT`, `KELVIN`.	String
`properties[].timeOfSample`	Time the endpoint detected the state change. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`properties[].error`	(Optional) Describes the error encountered. Included when `type = ERROR`.	Error object

HTTP status codes

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

Get 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the 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 object.

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
`properties`	List of properties for the endpoint. If you don't have permission to view the data, the list is empty.	Array of objects
`properties[].name`	Name of the property. Valid values: `thermostatMode`, `targetSetpoint`, `lowerSetpoint`, `upperSetpoint`.	String
`properties[].type`	Type of the property. If set to `ERROR`, you can retry the request. Valid values: `RETRIEVABLE`, `NOT_RETRIEVABLE`, `ERROR`.	String
`properties[].value`	Thermostat properties of the specified endpoint.	Object
`properties[].value.value`	Current value of the property specified by name. Valid values for `thermostatMode`: `HEAT`, `COOL`, `AUTO`, `ECO`, `OFF`. Valid values for `targetSetpoint`, `lowerSetpoint`, `upperSetpoint`: Current temperature.	String for `thermostatMode`, Double for setpoints
`properties[].value.scale`	Temperature scale. Included for `targetSetpoint`, `lowerSetpoint`, `upperSetpoint` only. Valid values: `CELSIUS`, `FAHRENHEIT`, `KELVIN`.	String
`properties[].timeOfSample`	Time the endpoint detected the state change. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`properties[].error`	(Optional) Describes the error encountered. Included when `type = ERROR`.	Error object
`configuration`	Supported thermostat modes.	Object
`supportedModes`	List of modes that the thermostat endpoint supports. Valid values: `HEAT`, `COOL`, `AUTO`, `ECO`, `OFF`.	Array of string
`operations`	List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of Operation objects

HTTP status codes

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

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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 202 Accepted. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`202 Accepted`	Devices unpaired successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`operation`	Path	Operation to adjust or set the brightness level. Valid values: `adjustBrightness`, `setBrightness`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The following example shows the request body for the adjustBrightness operation.

Copied to clipboard.

{
    "payload": {
        "brightnessDelta": -25
    }
}

The following example shows the request body for the setBrightness operation.

Copied to clipboard.

{
    "payload": {
        "brightness": 75
    }
}

Request body properties

Property	Description	Type	Required
`payload`	Information required to control the `brightness` property. Include one of `brightness` or `brightnessDelta`.	Object	Yes
`payload.brightness`	Percentage amount to set the brightness of the endpoint. Include with `setBrightness` operation. Valid values: 0–100.	Integer	No
`payload.brightnessDelta`	Percentage amount by which to change the brightness of the endpoint. Include with `adjustBrightness` operation. Use a negative value to decrease the brightness and positive value to increase the brightness. Valid values: –100 (minus 100) to 100.	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 object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`200 OK`	Property updated successfully on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "payload": {
        "color": {
            "hue": 20,
            "saturation": 0.75,
            "brightness": 0.34
        }
    }
}

Request body properties

Property	Description	Type	Required
`payload`	Information required to control the `color` property.	Object	Yes
`payload.color`	Defines the color to set the endpoint.	Integer	Yes
`payload.color.hue`	Current hue value of the color. Valid values: 0–360.	Integer	Yes
`payload.color.saturation`	Current saturation level of the color. Valid values: 0.0–1.0, inclusive.	Double	Yes
`payload.color.brightness`	Current brightness. Valid values: 0.0–1.0, inclusive.	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 object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`200 OK`	Property updated successfully on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`operation`	Path	Color temperature operation to adjust or set the color temperature. Valid values: `decreaseColorTemperature`, `increaseColorTemperature`, `setColorTemperature`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	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.

Copied to clipboard.

{
    "payload": {
        "colorTemperatureInKelvin": 2000
    }
}

Request body properties

Property	Description	Type	Required
`payload`	Information required to control the `colorTemperatureInKelvin` property for the `setColorTemperature` operation.	Object	No
`payload.colorTemperatureInKelvin`	Color temperature in degrees Kelvin of an endpoint. For details about shades of white, see Color temperature values. Valid values: 1000–10000.	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 object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`200 OK`	Property updated successfully on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`operation`	Path	Operation used to turn on and off the power. Valid values: `turnOn`, `turnOff`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`200 OK`	Property updated successfully on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update 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

Copied to clipboard.

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
`endpointId`	Path	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an ACI, `amzn1.alexa.endpoint.{id}`.	String	Yes
`operation`	Path	Operation used to set or adjust the speaker volume. Valid values: `setVolume`, `adjustVolume`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The following example shows the request body for the adjustVolume operation.

Copied to clipboard.

{
    "payload": {
        "volumeDelta": -25
    }
}

The following example shows the request body for the setVolume operation.

Copied to clipboard.

{
    "payload": {
        "volume": 75
    }
}

Request body properties

Property	Description	Type	Required
`payload`	Information required to control the `speaker` property. Include one of `volume` or `volumeDelta`.	Object	Yes
`payload.volume`	Amount to set the volume of the endpoint. Include with `setVolume` operation. Valid values: 0–100.	Integer	No
`payload.volumeDelta`	Amount by which to change the volume of the endpoint. Include with `adjustVolume` operation. Use a negative value to decrease the volume and positive value to increase the volume. Valid values: –100 (minus 100) to 100.	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 object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`200 OK`	Property updated successfully on the specified endpoint.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Object definitions

The Endpoint Features API defines the following objects 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`	Name of the update operation.	String
`path`	Full HTTP path that you can use in an update operation to set the `name` property.	String

Temperature object

The Temperature object represents the current temperature detected by the endpoint.

Property	Description	Type
`value`	Temperature in degrees.	Double
`scale`	Temperature scale. Included for `targetSetpoint`, `lowerSetpoint`, `upperSetpoint` only. Valid values: `CELSIUS`, `FAHRENHEIT`, `KELVIN`.	String

ThermostatMode values

The following table shows the mode value strings for thermostats. A thermostat might not support all modes.

Value	Description
`AUTO`	Automatic heating or cooling based on the current temperature and the setpoint.
`COOL`	Cooling mode.
`ECO`	Economy mode.
`EM_HEAT`	Emergency heating mode. This mode uses a backup heat source as an additional heat source. For example, a customer might use emergency heat when it's really cold or when the heat pump is broken.
`HEAT`	Heating mode.
`OFF`	Heating and cooling are off, but the device might still have power.

Error object

The Error object defines the error type and message included in the response when an error occurs.

The following example shows the response body with the error type and message.

{
    "type": "ENDPOINT_UNREACHABLE",
    "message": "The endpoint is offline or unreachable."
}

Property	Description	Type
`type`	Type of error that occurred. For specific error types, see the HTTP status code table for each operation.	String
`message`	Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String

Was this page helpful?

Provide feedback

Last updated: Nov 01, 2024