Endpoint API

About endpoints

An endpoint represents an Alexa-connected device (like an Echo device) with which an Alexa customer can interact. In Alexa Smart Properties for hospitality, you manage your Echo devices using the Alexa Smart Properties for hospitality endpoint API. With this API, you can enumerate the devices owned by your Amazon Business account; view and change settings; and associate endpoints with specific rooms.

Enumerate endpoints

Call GET /v2/endpoints?owner=~caller to get the list of endpoints that you registered to your Amazon Business account.

Request format examples

The following examples show how to use this call.

Enumerate endpoints that aren't associated with a unit

The following example lists the endpoints owned by the caller that aren't associated with a unit. By default, the results aren't expanded.

This call only returns endpoints that are not associated with any units. To enumerate endpoints associated with a specific unit, see Enumerate endpoints associated with a unit.

GET /v2/endpoints?owner=~caller HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Response body example

{
   "results": [
      {
         "id": "amzn1.alexa.endpoint.A234ajd9..."
      },
      {
         "id": "amzn1.alexa.endpoint.X35as24a..."
      }
   ],
   "paginationContext": {
        "nextToken": "ABCD123"
   }
}

Include details for each endpoint

This example shows how to include details for each endpoint, use the following expand=all parameter.

GET /v2/endpoints?owner=~caller&expand=all HTTP/1.1

Response body example

{
   "results":[
      {
         "id":"amzn1.alexa.endpoint.A234ajd9...",
         "friendlyName":{
            "type":"PLAIN",
            "value":{
               "text":"Test's Echo"
            }
         },
         "manufacturer":{
            "type":"PLAIN",
            "value":{
               "text":"Amazon"
            }
         },
         "model":{
            "type":"PLAIN",
            "value":{
               "text":"Echo Dot (3rd generation)"
            }
         },
         "serialNumber":{
            "type":"PLAIN",
            "value":{
               "text":"Z0F0d0M5R7UBSNWT"
            }
         },
         "softwareVersion":{
            "type":"PLAIN",
            "value":{
               "text":"1"
            }
         },
         "connections":[
            {
               "type":"TCP_IP",
               "macAddress":"FE7SD227F2AC"
            }
         ],
         "creationTime": "2021-11-11T06:48:16Z",
         "features":[
            {
               "name":"speaker",
               "path":"/v2/endpoints/{endpointID}/features/speaker"
            },
            {
               "name":"connectivity",
               "path":"/v2/endpoints/{endpointID}/features/connectivity"
            }
         ],
         "associatedUnits": [
            {
               "id":"amzn1.alexa.unit.did.unitOne"
            }
         ],
         "operations": [
            {
               "name": "deregister",
               "path": "/v2/endpoints/{endpointID}/deregister"
            }
         ],
         "displayCategories": {
            "primary": {
               "value": "ALEXA_VOICE_ENABLED",
               "sources": [
                  "ENDPOINT_REPORTER"
               ]
            },
            "all": [
               {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               }
            ]
         }
      }
      {
         "id":"amzn1.alexa.endpoint.X35as24a...",
         "friendlyName":{
            "type":"PLAIN",
            "value":"Another Test's Echo"
         },
         "manufacturer":{
            "type":"PLAIN",
            "value":{
               "text":"Amazon"
            }
         },
         "model":{
            "type":"PLAIN",
            "value":{
               "text":"Echo Dot (3rd generation)"
            }
         },
         "serialNumber":{
            "type":"PLAIN",
            "value":{
               "text":"ABC0d0M5R7UBSDFG"
            }
         },
         "softwareVersion":{
            "type":"PLAIN",
            "value":{
               "text":"1"
            }
         },
         "connections":[
            {
               "type":"TCP_IP",
               "macAddress":"DGSD227D2AB"
            }
         ],
         "creationTime": "2021-11-11T06:48:16Z",
         "features":[
            {
               "name":"speaker",
               "path":"/v2/endpoints/{endpointID}/features/speaker"
            },
            {
               "name":"connectivity",
               "path":"/v2/endpoints/{endpointID}/features/connectivity"
            }
         ],
         "associatedUnits": [
            {
               "id":"amzn1.alexa.unit.did.unitOne"
            }
         ],
         "operations": [
            {
               "name": "deregister",
               "path": "/v2/endpoints/{endpointID}/deregister"
            }
         ],
         "displayCategories": {
            "primary": {
               "value": "ALEXA_VOICE_ENABLED",
               "sources": [
                  "ENDPOINT_REPORTER"
               ]
            },
            "all": [
               {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               }
            ]
         }
      }
  ],
  "paginationContext":{
     "nextToken":"ABCD123"
  }
}

Include connectivity for each endpoint

To include connectivity details for each endpoint, use the following expand=feature:connectivity parameter.

GET /v2/endpoints?owner=~caller&expand=all&expand=feature:connectivity

Response body example

{
     "results": [
         {
             "id": "amzn1.alexa.endpoint.A234ajd9...",
             "friendlyName": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Test's Echo"
                 }
             },
             "manufacturer": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Amazon"
                 }
             },
             "model": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Echo Dot (3rd generation)"
                 }
             },
             "serialNumber": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Z0F0d0M5R7UBSNWT"
                 }
             },
             "softwareVersion": {
                 "type": "PLAIN",
                 "value": {
                     "text": "1"
                 }
             },
             "connections": [
                 {
                     "type": "TCP_IP",
                     "macAddress": "FE7SD227F2AC"
                 }
             ],
             "creationTime": "2021-11-11T06:48:16Z",
             "features": [
                {
                    "name": "speaker",
                    "path": "/v2/endpoints/{endpointID}/features/speaker"
                },
                {
                    "name": "connectivity",
                    "properties": [
                       {
                           "name": "reachability",
                           "type": "RETRIEVABLE",
                           "value": {
                               "value": "OK"
                           },
                           "timeOfSample": "2020-08-30T18:22:15.295Z"
                       }
                   ]
                }
            ],
            "associatedUnits": [
               {
                  "id":"amzn1.alexa.unit.did.unitOne"
               }
            ],
            "operations": [
              {
                  "name": "deregister",
                  "path": "/v2/endpoints/{endpointID}/deregister"
               }
            ],
            "displayCategories": {
               "primary": {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               },
               "all": [
                  {
                     "value": "ALEXA_VOICE_ENABLED",
                     "sources": [
                        "ENDPOINT_REPORTER"
                     ]
                  }
               ]
            }
         },
         {
             "id": "amzn1.alexa.endpoint.X35as24a...",
             "friendlyName": {
                 "type": "PLAIN",
                 "value": "Another Test's Echo"
             },
             "manufacturer": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Amazon"
                 }
             },
             "model": {
                 "type": "PLAIN",
                 "value": {
                     "text": "Echo Dot (3rd generation)"
                 }
             },
             "serialNumber": {
                 "type": "PLAIN",
                 "value": {
                     "text": "ABC0d0M5R7UBSDFG"
                 }
             },
             "softwareVersion": {
                 "type": "PLAIN",
                 "value": {
                     "text": "1"
                 }
             },
             "connections": [
                 {
                     "type": "TCP_IP",
                     "macAddress": "DGSD227D2AB"
                 }
             ],
             "creationTime": "2021-11-11T06:48:16Z",
             "features": [
                 {
                     "name": "speaker",
                     "path": "/v2/endpoints/{endpointID}/features/speaker"
                 },
                 {
                     "name": "connectivity",
                     "properties": [
                        {
                            "name": "reachability",
                            "type": "RETRIEVABLE",
                            "value": {
                                "value": "UNREACHABLE"
                            },
                            "timeOfSample": "2020-08-30T18:22:15.295Z"
                        }
                    ]
                 }
             ],
             "associatedUnits": [
                {
                   "id":"amzn1.alexa.unit.did.unitOne"
                }
             ],
             "operations": [
                 {
                     "name": "deregister",
                     "path": "/v2/endpoints/{endpointID}/deregister"
                 }
             ],
             "displayCategories": {
               "primary": {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               },
               "all": [
                  {
                     "value": "ALEXA_VOICE_ENABLED",
                     "sources": [
                        "ENDPOINT_REPORTER"
                     ]
                  }
               ]
            }
         }
     ],
     "paginationContext": {
         "nextToken": "ABCD123"
     }
}

Enumerate endpoints associated with a unit

To enumerate endpoints associated with a particular unitId that the caller has permission to access, provide the associatedUnits.id={unitId} parameter.

GET /v2/endpoints?associatedUnits.id={unitId}&expand=all

Response body example

{
   "results":[
      {
         "id":"amzn1.alexa.endpoint.A234ajd9...",
         "friendlyName":{
            "type":"PLAIN",
            "value": {
               "text":"Test's Echo"
            }
         },
         "manufacturer":{
            "type":"PLAIN",
            "value": {
                "text": "Amazon"
            }
         },
         "model":{
            "type":"PLAIN",
            "value": {
                "text":"Echo Dot (3rd generation)"
            }
         },
         "serialNumber":{
            "type":"PLAIN",
            "value": {
                "text":"Z0F0d0M5R7UBSNWT"
            }
         },
         "softwareVersion":{
            "type":"PLAIN",
            "value": {
                "text":"1"
            }
         },
         "connections":[
            {
               "type":"TCP_IP",
               "macAddress":"FE7SD227F2AC"
            }
         ],
         "creationTime": "2021-11-11T06:48:16Z",
         "features":[
            {
               "name":"speaker",
               "path":"/v2/endpoints/{endpointID}/features/speaker"
            },
            {
               "name":"connectivity",
               "path":"/v2/endpoints/{endpointID}/features/connectivity"
            }
         ],
         "associatedUnits":[
            {
               "id":"amzn1.alexa.unit.did.unitOne"
            }
         ],
         "operations": [
            {
               "name": "deregister",
               "path": "/v2/endpoints/{endpointID}/deregister"
            }
         ],
         "displayCategories": {
            "primary": {
               "value": "ALEXA_VOICE_ENABLED",
               "sources": [
                  "ENDPOINT_REPORTER"
               ]
            },
            "all": [
               {
                  "value": "ALEXA_VOICE_ENABLED",
                  "sources": [
                     "ENDPOINT_REPORTER"
                  ]
               }
            ]
         }
      }
}

Request query parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body parameters

NameValue object

Example

"model": {
    "type": "PLAIN",
    "value": {
        "text":"Amazon Echo"
    }

Value object

Connection object

Example

{
  "type": "TCP_IP",
  "macAddress": "141AC1534151"
}

Feature object

Example

{
    "name": "speaker",
    "path" : "/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/speaker"
}

Unit object

Example

{
  "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
}

Display categories object

Example

"displayCategories": {
   "primary": {
      "value": "ALEXA_VOICE_ENABLED",
      "sources": [
         "ENDPOINT_REPORTER"
      ]
   },
   "all": [
      {
         "value": "ALEXA_VOICE_ENABLED",
         "sources": [
            "ENDPOINT_REPORTER"
         ]
      }
   ]
}

Display category object

Example

{
  "value": "LIGHT",
  "sources": ["CUSTOMER", "ENDPOINT_REPORTER"]
}

Pagination context object

Example

{
  "nextToken": "ABCD123"
}

Error response

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

Error response parameters

HTTP response codes

Retrieve endpoint

Call GET /v2/endpoints/{endpointId}?expand=all to retrieve an endpoint and list values for all endpoint attributes the caller has permission to access.

The caller must have access to the endpoint.

This request doesn't require filtering parameters such as owner.

Request format examples

The following examples show how to use this call.

List endpoint ID only

The following example lists only the endpoint ID for the endpoint.

GET /v2/endpoints/{endpointId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

{
    "id": "amzn1.alexa.endpoint.A234ajd9..."
}

List all attributes

The following example lists all the endpoint's attributes.

GET /v2/endpoints/{endpointId}?expand=all HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Response body example

{
   "id":"amzn1.alexa.endpoint.ABC123...",
   "friendlyName":{
      "type":"PLAIN",
      "value":{
         "text":"white echo"
      }
   },
   "manufacturer":{
      "type":"PLAIN",
      "value":{
         "text":"Amazon"
      }
   },
   "model":{
      "type":"PLAIN",
      "value":{
         "text":"Echo Dot (3rd generation)"
      }
   },
   "serialNumber":{
      "type":"PLAIN",
      "value":{
         "text":"G0922M09951706JS"
      }
   },
   "softwareVersion":{
      "type":"PLAIN",
      "value":{
         "text":"4262172036"
      }
   },
   "connections":[
      {
         "type":"TCP_IP",
         "macAddress":"141AC1534151"
      }
   ],
   "associatedUnits":[
      {
         "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
      }
   ],
   "creationTime": "2021-11-11T06:48:16Z",
   "features":[
      {
         "name":"speaker",
         "path":"/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/speaker"
      },
      {
         "name":"connectivity",
         "path":"/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/connectivity"
      }
   ],
   "operations":[
      {
         "name":"deregister",
         "path":"/v2/endpoints/amzn1.alexa.endpoint.ABC123.../deregister"
      }
   ],
   "displayCategories": {
      "primary": {
         "value": "ALEXA_VOICE_ENABLED",
         "sources": [
            "ENDPOINT_REPORTER"
         ]
      },
      "all": [
         {
            "value": "ALEXA_VOICE_ENABLED",
            "sources": [
               "ENDPOINT_REPORTER"
            ]
         }
      ]
   }
}

List all attributes and speaker feature

The following example lists all the endpoint's attributes and the speaker feature.

GET /v2/endpoints/{endpointId}?expand=all&expand=feature:speaker HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Response body example

{
   "id":"amzn1.alexa.endpoint.ABC123...",
   "friendlyName":{
      "type":"PLAIN",
      "value":{
         "text":"white echo"
      }
   },
   "manufacturer":{
      "type":"PLAIN",
      "value":{
         "text":"Amazon"
      }
   },
   "model":{
      "type":"PLAIN",
      "value":{
         "text":"Echo Dot (3rd generation)"
      }
   },
   "serialNumber":{
      "type":"PLAIN",
      "value":{
         "text":"G0922M09951706JS"
      }
   },
   "softwareVersion":{
      "type":"PLAIN",
      "value":{
         "text":"4262172036"
      }
   },
   "connections":[
      {
         "type":"TCP_IP",
         "macAddress":"141AC1534151"
      }
   ],
   "associatedUnits":[
      {
         "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
      }
   ],
   "creationTime": "2021-11-11T06:48:16Z",
   "features":[
        {
           "name": "speaker",
            "properties": [
                {
                    "name": "volume",
                    "type": "RETRIEVABLE",
                    "value": {
                        "value": 40
                    },
                    "timeOfSample": "2021-02-26T01:48:31.225Z"
                }
            ],
            "operations": [
                {
                    "name": "adjustVolume",
                    "path": "/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/speaker/adjustVolume"
                },
                {
                    "name": "setVolume",
                    "path": "/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/speaker/setVolume"
                }
            ]
      },
      {
         "name":"connectivity",
         "path":"/v2/endpoints/amzn1.alexa.endpoint.ABC123.../features/connectivity"
      }
   ],
   "operations":[
      {
         "name":"deregister",
         "path":"/v2/endpoints/amzn1.alexa.endpoint.ABC123.../deregister"
      }
   ],
   "displayCategories": {
      "primary": {
         "value": "ALEXA_VOICE_ENABLED",
         "sources": [
            "ENDPOINT_REPORTER"
         ]
      },
      "all": [
         {
            "value": "ALEXA_VOICE_ENABLED",
            "sources": [
               "ENDPOINT_REPORTER"
            ]
         }
      ]
   }
}

Request path parameters

Request query parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body parameters

Error response

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

Error response parameters

HTTP response codes

Manage endpoint-to-unit association

PUT associatedUnits

Call PUT /v2/endpoints/{endpointId}/associatedUnits to update the list of associated units for an endpoint. Currently an endpoint can only be associated with one unit at a time.

Request format

PUT /v2/endpoints/{endpointId}/associatedUnits HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body

[
  {
    "id": "amzn1.alexa.unit.did.{id}"
  }
]

Request body using default unit ID wildcard

[
  {
    "id": "~caller.defaultUnitId"
  }
]

Request body parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body

{
    "endpoint": {
        "id": "amzn1.alexa.endpoint.ABC123...",
        "associatedUnits": [{
            "id": "amzn1.alexa.unit.did.ZXY987..."
        }]
    }
}

Response body parameters

Error response

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

Error response parameters

HTTP response codes

Query the endpoint status

After you've called the PUT associatedUnits API and received a 200 code, the process to associate the endpoint with the unit is complete on the cloud side. However, the physical endpoint must complete an automatic reboot to complete the endpoint-to-unit association on the endpoint side. There are no steps required to automatically reboot the endpoint.

To check if the endpoint has successfully rebooted, you can poll for the connectivity status of the endpoint. We recommend a polling interval of 2 minutes or greater.

When this API returns an endpointId, the endpoint has successfully rebooted and reconnected to the network.

Request example

GET /v2/endpoints?associatedUnits.id=amzn1.alexa.unit.did.foo&connections.macAddress=00:11:22:AA:BB:33:44:55&features[name:connectivity].properties[name:reachability].value.value=OK HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Manage connectivity feature

GET features/connectivity

Call GET /v2/endpoints/{endpointId}/features/connectivity to get states and attributes related to connectivity of the endpoint.

Request format

GET /v2/endpoints/{endpointId}/features/connectivity  HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
    "properties": [
        {
            "name": "reachability",
            "type": "RETRIEVABLE",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2020-07-20T00:00:00Z"
        }
    ]
}

Response body parameters

Error response

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

Error response parameters

HTTP response codes

Manage Wi-Fi settings

Manage Wi-Fi configuration for Alexa endpoints and track status. To use these requests, you'll need an LWA token with "credential_locker::wifi_management" and "alexa::enterprise:management" scopes.

POST saveWifiConfigurations

Call POST /credentiallocker/v2/saveWifiConfigurations to save Wi-Fi configurations for later use with an endpoint.

Request format

POST /credentiallocker/v2/saveWifiConfigurations HTTP/1.1
Host: credential-locker-service.amazon.com
x-amz-access-token: {LWA Token}
Content-Type: application/json
Authorization: Bearer {LWA Token}

Request body format

{
    "wifiConfigurations": [{
        "credentialConfiguration": {
            "privateSharedKey": "\"wifi-password\""
        },
        "ssid": "\"wifi-ssid\"",
        "keyManagement": "WPAPSK"
    }]
}

Request body parameters

HTTP response codes

POST addOrUpdateWifiConfigurations

Call POST /v2/endpoints/endpointId/features/connectivity/addOrUpdateWifiConfigurations to associate saved Wi-Fi configurations with an endpoint. You can associate up to 32 Wi-Fi configurations with each endpoint.

Request format

POST /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer {LWA Token}
Content-Type: application/json

Request path parameters

Request body format

{
    "payload": {
        "wifiConfigurations": [{
            "ssid": "\"wifi-ssid\"",
            "keyManagement": "WPAPSK"
        }]
    }
}

Request body parameters

Response body format

{
     "submittedOperationId": "{operationId}"
}

Response body parameters

HTTP response codes

GET Wi-Fi installation status

Call GET /v2/endpoints/endpointId/features/connectivity/addOrUpdateWifiConfigurations/submittedOperations/{operationId} to get the status of an addOrUpdateWifiConfigurations operation.

Request format

GET /v2/endpoints/{endpointId}/features/connectivity/addOrUpdateWifiConfigurations/submittedOperations/{operationId} HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer {LWA Token}

Request path parameters

Response body example

{
     "status": "TIMEOUT"
}

Response body parameters

Status object schema

HTTP response codes

Manage smart home features

GET features/color

Call GET /v2/endpoints/{endpointId}/features/color to get color properties and available operations for the specified endpoint. For color property details, see Capability Property Schemas.

Request format

GET /v2/endpoints/{endpointId}/features/color HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
   "properties": [
      {
         "name": "color",
         "type": "RETRIEVABLE",
         "value": {
            "hue": 20,
            "saturation": 0.5,
            "brightness": 0.7
         },
         "timeOfSample": "1970-01-01T00:00:00Z"
      }
   ],
   "operations": [
      {
         "name": "setColor",
         "path": "/v2/endpoints/{id}/features/color/setColor"
      }
   ]
}

Partial success response body example

Following is an example showing the response returned when an error occurs during color property retrieval.

{
    "properties": [
        {
            "name": "color",
            "type": "ERROR",
            "error": {
                "type": "",
                "message": ""
            }
        }
    ],
    "operations": [
        {
            "name": "setColor",
            "path": "/v2/endpoints/{id}/features/color/setColor"
        }
    ]
}

Response body parameters

Property object schema

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

POST features/color

Call POST /v2/endpoints/{endpointId}/features/color/setColor to set color properties for the specified endpoint. For color property details, see Capability Property Schemas.

Request format

POST /v2/endpoints/{endpointId}/features/color/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body example for setColor

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

Request body parameters for setColor

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Success response body

If the operation is completely successful, there is no response body.

Partial success response example

The HTTP/1.1 503 Service Unavailable response indicates that the request was sent successfully, but Alexa received an error response from the endpoint reporter. Examples of endpoint errors: the endpoint is offline, the endpoint battery level is too low, etc.

HTTP/1.1 503 Service Unavailable

{
    "type": "",
    "message": ""
}

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

GET features/brightness

Call GET /v2/endpoints/{endpointId}/features/brightness to get the brightness setting and available operations for the specified endpoint. For brightness property details, see Capability Property Schemas.

Request format

GET /v2/endpoints/{endpointId}/features/brightness HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
   "properties": [
      {
         "name": "brightness",
         "type": "RETRIEVABLE",
         "value": {
            "value": 50
         },
         "timeOfSample": "1970-01-01T00:00:00Z"
      }
   ],
   "operations": [
       {
          "name": "setBrightness",
          "path": "/v2/endpoints/{id}/features/brightness/setBrightness"
       },
       {
          "name": "adjustBrightness",
          "path": "/v2/endpoints/{id}/features/brightness/adjustBrightness"
       }
   ]
}

Partial success response body example

Following is an example showing the response returned when an error occurs during brightness property retrieval.

{
    "properties": [
        {
            "name": "brightness",
            "type": "ERROR",
            "error": {
                "type": "",
                "message": ""
            }
        }
    ],
    "operations": [
        {
            "name": "setBrightness",
            "path": "/v2/endpoints/{id}/features/brightness/setBrightness"
        },
        {
            "name": "adjustBrightness",
            "path": "/v2/endpoints/{id}/features/brightness/adjustBrightness"
        }
    ]
}

Response body parameters

Property object schema

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

POST features/brightness

Call POST /v2/endpoints/{endpointId}/features/brightness/setBrightness to set the brightness level for the specified endpoint. Call POST /v2/endpoints/{endpointId}/features/brightness/adjustBrightness to change the brightness level for the specified endpoint by a specified amount.

For brightness property details, see Capability Property Schemas.

Request format

POST /v2/endpoints/{endpointId}/features/brightness/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body example for setBrightness

{
    "payload": {
        "brightness": 50
    }
}

Request body parameters for setBrightness

Request body example for adjustBrightness

{
    "payload": {
        "brightnessDelta": 10
    }
}

Request body parameters for adjustBrightness

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Success response body

If the operation is completely successful, there is no response body.

Partial success response example

The HTTP/1.1 503 Service Unavailable response indicates that the request was sent successfully, but Alexa received an error response from the endpoint reporter. Examples of endpoint errors: the endpoint is offline, the endpoint battery level is too low, etc.

HTTP/1.1 503 Service Unavailable

{
    "type": "",
    "message": ""
}

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

GET features/colorTemperature

Call GET /v2/endpoints/{endpointId}/features/colorTemperature to get color temperature properties and available operations for the specified endpoint.

Request format

GET /v2/endpoints/{endpointId}/features/colorTemperature HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
   "properties": [
      {
         "name": "colorTemperatureInKelvin",
         "type": "RETRIEVABLE",
         "value": {
            "value": "2700"
         },
         "timeOfSample": "1970-01-01T00:00:00Z"
      }
   ],
   "operations": [
      {
          "name": "setColorTemperature",
          "path": "/v2/endpoints/{id}/features/colorTemperature/setColorTemperature"
      },
      {
         "name": "increaseColorTemperature",
         "path": "/v2/endpoints/{id}/features/colorTemperature/increaseColorTemperature"
      },
      {
         "name": "decreaseColorTemperature",
         "path": "/v2/endpoints/{id}/features/colorTemperature/decreaseColorTemperature"
      }
   ]
}

Partial success response body example

Following is an example showing the response returned when an error occurs during colorTemperature property retrieval.

{
    "properties": [
        {
            "name": "colorTemperatureInKelvin",
            "type": "ERROR",
            "error": {
                "type": "",
                "message": ""
            }
        }
    ],
    "operations": [
        {
            "name": "setColorTemperature",
            "path": "/v2/endpoints/{id}/features/colorTemperature/setColorTemperature"
        },
        {
           "name": "increaseColorTemperature",
           "path": "/v2/endpoints/{id}/features/colorTemperature/increaseColorTemperature"
        },
        {
          "name": "decreaseColorTemperature",
          "path": "/v2/endpoints/{id}/features/colorTemperature/decreaseColorTemperature"
        }
    ]
}

Response body parameters

Property object schema

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

POST features/colorTemperature

Call POST /v2/endpoints/{endpointId}/features/colorTemperature/setColorTemperature to set the color temperature value for the specified endpoint.

Call POST /v2/endpoints/{endpointId}/features/colorTemperature/increaseColorTemperature to increase the color temperature value for the specified endpoint. This call adjusts the color temperature but doesn't specify a value to change by; that is up to the implementing service or the manufacturer. This call has no request body.

Call POST /v2/endpoints/{endpointId}/features/colorTemperature/decreaseColorTemperature to decrease the color temperature value for the specified endpoint. This call adjusts the color temperature but doesn't specify a value to change by; that is up to the implementing service or the manufacturer. This call has no request body.

Request format

POST /v2/endpoints/{endpointId}/features/colorTemperature/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body example for setColorTemperature

{
    "payload": {
        "colorTemperatureInKelvin": 2700
    }
}

Request body parameters for setColorTemperature

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Success response body

If the operation is completely successful, there is no response body.

Partial success response example

The HTTP/1.1 503 Service Unavailable response indicates that the request was sent successfully, but Alexa received an error response from the endpoint reporter. Examples of endpoint errors: the endpoint is offline, the endpoint battery level is too low, etc.

HTTP/1.1 503 Service Unavailable

{
    "type": "",
    "message": ""
}

Error response

HTTP/1.1 {ErrorCode}

{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error object schema

HTTP response codes

GET features/power

Call GET /v2/endpoints/{endpointId}/features/power to get power feature properties and their corresponding values for the specified endpoint.

Request format

GET /v2/endpoints/{endpointId}/features/power HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
   "properties": [
      {
         "name": "powerState",
         "type": "RETRIEVABLE",
         "value": {
             "value": "ON"
         },
         "timeOfSample": "1970-01-01T00:00:00Z"
      }
   ],
   "operations": [
      {
         "name": "turnOn",
         "path": "/v2/endpoints/{endpointID}/features/power/turnOn"
      },
      {
         "name": "turnOff",
         "path": "/v2/endpoints/{endpointID}/features/power/turnOff"
      }
   ]
}

Partial success response example

Following is an example showing the response returned when an error occurs during powerState property retrieval.

{
    "properties": [
        {
            "name": "powerState",
            "type": "ERROR",
            "error": {
                "type": "{ErrorType}",
                "message": "{ErrorMessage}"
            }
        }
    ],
    "operations": [
        {
            "name": "turnOn",
            "path": "/v2/endpoints/{id}/features/power/turnOn"
        },
        {
            "name": "turnOff",
            "path": "/v2/endpoints/{id}/features/power/turnOff"
        }
    ]
}

Response body parameters

Property object schema

Error object schema

Operation object schema

HTTP response codes

POST features/power

Call POST /v2/endpoints/{endpointId}/features/power/turnOn to turn on the endpoint's power.

Call POST /v2/endpoints/{endpointId}/features/power/turnOff to turn off the endpoint's power.

Request format

POST /v2/endpoints/{endpointId}/features/power/{operation} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body

None.

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response

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

Error response parameters

HTTP response codes

GET features/temperatureSensor

Call GET /v2/endpoints/{endpointId}/features/temperatureSensor to get temperatureSensor feature properties and their corresponding values for the specified endpoint.

Request format

GET /v2/endpoints/{endpointId}/features/temperatureSensor HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
   "name": "temperatureSensor",
   "properties": [
      {
         "name": "temperature",
         "type": "RETRIEVABLE",
         "value": {
            "value": 68.0,
            "scale": "FAHRENHEIT"
         },
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      },
   ]
}

Supported Property Values

Temperature

Example temperature value

{
    "value": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
    }
}

Temperature scales

GET features/thermostat

Call GET /v2/endpoints/{endpointId}/features/thermostat to get thermostat feature properties and their corresponding values for the specified endpoint.

Request format

GET /v2/endpoints/{endpointId}/features/thermostat HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example (Single Setpoint Thermostat)

{
   "name": "thermostat",
   "properties": [
      {
         "name": "thermostatMode",
         "type": "RETRIEVABLE",
         "value": {
            "value": "HEAT"
         },
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      },
      {
         "name": "targetSetpoint",
         "type": "RETRIEVABLE",
         "value": {
            "value": 68.0,
            "scale": "FAHRENHEIT"
         },
         "deviceNativeScale": "FAHRENHEIT",
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      },
   ],
   "operations": [
      {
         "name": "setThermostatMode",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/setThermostatMode"
      },
      {
         "name": "setTargetSetpoint",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/setTargetSetpoint"
      },
      {
         "name": "adjustTargetSetpoint",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/adjustTargetSetpoint"
      },
      {
         "name": "resumeSchedule",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/resumeSchedule"
      }
   ],
   "configuration": {
      "supportedModes": [
         "HEAT",
         "COOL",
         "AUTO"
      ],
      "supportsScheduling": false
   }
}

Response body example (Dual Setpoint Thermostat)

{
   "name": "thermostat",
   "properties": [
      {
         "name": "thermostatMode",
         "type": "RETRIEVABLE",
         "value": {
            "value": "HEAT"
         },
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      },
      {
         "name": "lowerSetpoint",
         "type": "RETRIEVABLE",
         "value": {
            "value": 68.0,
            "scale": "FAHRENHEIT"
         },
         "deviceNativeScale": "FAHRENHEIT",
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      },
      {
         "name": "upperSetpoint",
         "type": "RETRIEVABLE",
         "value": {
            "value": 73.0,
            "scale": "FAHRENHEIT"
         },
         "deviceNativeScale": "FAHRENHEIT",
         "timeOfSample": "2021-03-04T17:46:42.48Z"
      }
   ],
   "operations": [
      {
         "name": "setThermostatMode",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/setThermostatMode"
      },
      {
         "name": "setTargetSetpoint",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/setTargetSetpoint"
      },
      {
         "name": "resumeSchedule",
         "path": "/v2/endpoints/{endpointID}/features/thermostat/resumeSchedule"
      }
   ],
   "configuration": {
      "supportedModes": [
         "HEAT",
         "COOL",
         "AUTO"
      ],
      "supportsScheduling": false
   }
}

Supported Property Values

Temperature

Example temperature value

{
    "value": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
    }
}

Temperature scales

ThermostatMode Values

Supported Configuration

Feature Operations

Supported Operations

adjustTargetSetpoint

Call POST /v2/endpoints/{endpointId}/features/thermostat/adjustTargetSetpoint to adjust the target set point of a single set point thermostat by a specified value.

Request format

POST /v2/endpoints/{endpointId}/features/thermostat/adjustTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body payload

Example Request

POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/adjustTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer 
{
   "payload": {
      "targetSetpointDelta": {
         "value": -2.0,
         "scale": "CELSIUS"
      }
   }
}

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response

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

Error response parameters

HTTP response codes

resumeSchedule

Call POST /v2/endpoints/{endpointId}/features/thermostat/resumeSchedule to revert the thermostat mode and setpoint(s) to a pre-programmed schedule.

Request format

POST /v2/endpoints/{endpointId}/features/thermostat/resumeSchedule HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body payload

none

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response

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

Error response parameters

HTTP response codes

setTargetSetpoint

Call POST /v2/endpoints/{endpointId}/features/thermostat/setTargetSetpoint to set the thermostat to a specified set point(s).

Request format

POST /v2/endpoints/{endpointId}/features/thermostat/setTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body payload

Example Request (Single Setpoint with scheduling)

POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/setTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer 
{
   "payload": {
      "targetSetpoint": {
         "value": 21.0,
         "scale": "CELSIUS"
      },
      "schedule": {
         "start": "2017-06-22T21:35Z",
         "duration": "PT25M"
      }
   }
}

Example Request (Dual Setpoint)

POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/setTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer 
{
   "payload": {
      "lowerSetpoint": {
         "value": 68.0,
         "scale": "FAHRENHEIT"
      },
      "upperSetpoint": {
         "value": 72.0,
         "scale": "FAHRENHEIT"
      }
   }
}

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response

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

Error response parameters

HTTP response codes

TimeInterval

Represents a time duration. A TimeInterval indicates when an operation should start, end and/or how long it should last. One or two of the fields of a time interval can be specified, but if all three are specified, an error will occur.

Example with start and end

{
    "start":"2017-10-04T14:00Z",
    "end":"2017-10-04T14:15Z"
}

Example with start and duration

{
    "start":"2017-10-04T14:00Z",
    "duration":"PT30M"
}

Example with duration only

{
     "duration":"PT30M"
}

setThermostatMode

Call POST /v2/endpoints/{endpointId}/features/thermostat/setThermostatMode to set the mode of the thermostat.

Request format

POST /v2/endpoints/{endpointId}/features/thermostat/setThermostatMode HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body payload

Example Request (Dual Setpoint)

POST
/v2/endpoints/amzn1.alexa.endpoint.abc123/features/thermostat/setTargetSetpoint HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer 
{
   "payload": {
      "thermostatMode": "HEAT"
   }
}

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response

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

Error response parameters

HTTP response codes

Manage speaker feature

GET features/speaker

Call GET /endpoints/{endpointID}/features/speaker to retrieve speaker-feature properties and their corresponding values of the specified endpoint.

Request format

GET /v2/endpoints/{endpointId}/features/speaker HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
   "properties": [
      {
         "name": "volume",
         "type": "RETRIEVABLE",
         "value": {
             "value": 42
         },
         "timeOfSample": "1970-01-01T00:00:00Z"
      }
   ],
   "operations": [
      {
         "name": "setVolume",
         "path": "/v2/endpoints/{endpointID}/features/speaker/setVolume"
      },
      {
         "name": "adjustVolume",
         "path": "/v2/endpoints/{endpointID}/features/speaker/adjustVolume"
      }
   ]
}

Partial success response example

Following is an example showing the response returned when an error occurs during volume property retrieval.

{
    "properties": [
        {
            "name": "volume",
            "type": "RETRIEVABLE",
            "error": {
                "type": "{ErrorType}",
                "message": "{ErrorMessage}"
            }
        }
    ],
    "operations": [
        {
            "name": "setVolume",
            "path": "/v2/endpoints/<id>/features/speaker/setVolume"
        },
        {
            "name": "adjustVolume",
            "path": "/v2/endpoints/<id>/features/speaker/adjustVolume"
        }
    ]
}