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

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

202 Accepted

Devices unpaired successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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.
The following example shows the response body with the error type and message.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}

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

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 describes the error that occurred.

Property Description Type

type

Type of error that occurred.
Valid values: ENDPOINT_UNREACHABLE, INTERNAL_ERROR.

String

message

Human readable error message.
Use for debugging and logging purposes only. You must not share it with the customer. No business logic should depend on the content of the error message.

String


Was this page helpful?

Last updated: Sep 25, 2024