Unit Settings API

---

Use the Unit API to manage unit settings for Alexa Smart Properties core units such as rooms.

API endpoint

The endpoint of the Unit Settings API is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

Operations

The Unit Settings API includes the following operations.

Operation	HTTP Method and URI
Get the default music station setting	GET /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences
Set the default music station setting	PUT /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences
Delete all alarms for a unit	DELETE /v1/alerts/alarms?unitId={unitId}

Get the default music station setting

Call GET /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences to get the default music station preferences for a given unit.

This operation is available in the following countries.

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

Request format

Request path parameters

Field	Description	Type	Required
unitId	The unit ID, in the format "amzn1.alexa.unit.did.{id}".	String	Yes

Request body

None.

Response header

Field	Description	Type	Required
X-Amzn-RequestId	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example

Response body parameters

Field	Description	Type	Required
providerId	The radio station provider ID. For supported values, see Provider and station ID reference.	String	Yes
stationId	The station ID. For supported values, see Provider and station ID reference.	String	Yes

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type	Required
type	The error type.	String	No
message	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
429	Too many requests	The request is throttled.

Set the default music station setting

Call PUT /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences to set the default music station preferences for a given unit.

This operation is available in the following countries.

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

Request format

Request path parameters

Field	Description	Type	Required
unitId	The unit ID, in the format "amzn1.alexa.unit.did.{id}".	String	Yes

Request body example

Request body parameters

Field	Description	Type	Required
providerId	The radio station provider ID. For supported values, see Provider and station ID reference.	String	Yes
stationId	The station ID. For supported values, see Provider and station ID reference.	String	Yes

Response header

Field	Description	Type	Required
X-Amzn-RequestId	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type	Required
type	The error type.	String	No
message	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request	The request is malformed or is missing one or more required parameters.
403	Forbidden	The user doesn't have permission to perform the operation.
429	Too many requests	The request is throttled.

Delete all alarms for a unit

Call DELETE /v1/alerts/alarms?unitId={unitId} to delete all alarms on all endpoints in a unit. This API call is an extension of the AVS Alarms REST API.

This operation is available in the following countries.

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

Request format

Request body

None.

Request parameters

Field	Description	Type	Required
unitId	The unit ID, in the format "amzn1.alexa.unit.did.{id}".	String	Yes

Response header

Field	Description	Type	Required
X-Amzn-RequestId	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response

Upon successful deletion, the server returns an HTTP 204 No Content status response. A successful payload does not contain a body.

Error response

HTTP/1.1 {ErrorCode}
Content-Type: application/json

{
    "errors": [{
        "code": "{Code}",
        "endpointId": "{EndpointId}",
        "description": "{ErrorMessage}"
    }]
}

Error response parameters

Field	Description	Type	Required
code	The error name, for example, DEVICE_UNREACHABLE.	String	No
endpointId	The endpoint ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.endpoint.{id}".	String	No
description	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

Error handling for multiple device failure

If there is an error on a particular device in the unit, the API records the failure and continues deleting alarms on the remaining devices. The response returns the endpoint ID and reason for each device failure, as shown in the following example.

• If there are multiple failures with the same failure reason, the response returns the most accurate HTTP status code (for example, 504 DEVICE_NOT_REACHABLE if all failures are because of unreachable devices).
• If there are multiple failures with different failure reasons, the response returns the 500 INTERNAL_SERVER_ERROR status code, with more specific details for each failure listed in the array of errors.

HTTP/1.1 500 INTERNAL_SERVER_ERROR
Content-Type: application/json

{
    "errors": [{
            "code": "DEVICE_NOT_REACHABLE",
            "endpointId": "{ENDPOINT_ID_1}",
            "description": "Device not reachable / offline"
        },
        {
            "code": "INTERNAL_SERVER_ERROR",
            "endpointId": "{ENDPOINT_ID_2}",
            "description": "Unexpected Error"
        }
    ]
}

HTTP response codes

Status Code	Name	Description
204	No content	Alarms were successfully deleted on all endpoints in the unit. Note that this status code is returned even if the unit has no alarms to delete.
400	BAD_REQUEST	The request is malformed or is missing one or more required parameters.
401	UNAUTHORIZED	The authentication token is invalid or doesn't have access to the resource.
401	FORBIDDEN	The user doesn't have permission to perform the operation, or the unit doesn't exist.
500	INTERNAL_SERVER_ERROR	The request couldn't be handled because of an internal service error.
504	DEVICE_NOT_REACHABLE	The device is offline or unreachable.

---

Last updated: Apr 07, 2023