Endpoints REST API Reference
Use the Endpoints REST API to manage your Alexa Smart Properties (ASP) Alexa-connected devices, such as Amazon Echo devices or Alexa-connected lights. An endpoint represents an Alexa-connected device or component with which an ASP resident can interact. With this API, you can enumerate the devices owned by your Amazon Business account and associate endpoints with specific rooms.
You can use the Endpoints API along with the following APIs that manage endpoints:
- To view and update device settings, such device address, timezone, or connectivity status, see Endpoint Settings REST API Reference.
- To view and update endpoint properties, such as power state on a smart home light, see Endpoint Features REST API Reference.
- To view and update endpoint Wi-Fi configuration, see Endpoint Wi-Fi Management REST API Reference.
API endpoints
Based on the country of your organization, set the Host
parameter in the request header to one of the following API endpoints.
Country | Endpoint |
---|---|
CA, US |
|
DE, ES, FR, IT, UK |
|
JP |
|
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.
Operations
The Endpoints API includes the following operations.
Operation | HTTP Method and URI |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
Get endpoints by owner
Get the list of endpoints registered to your Amazon Business account. You can also get endpoints by using Query endpoints (advanced search).
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 list of endpoints by owner, you make a GET
request to the /v2/endpoints
resource.
Request path and header example
GET /v2/endpoints?owner={owner}&expand={expand}&maxResults={maxResults}&nextToken={nextToken}
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 |
---|---|---|---|---|
|
Query |
Filter endpoints to those associated with the owner. |
String |
Yes |
|
Query |
Get expanded information about each endpoint. |
String |
No |
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
Query |
Token from the previous response. |
String |
No |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body parameters
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with list of endpoints.
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 examples
The following example shows a response to a request that includes the owner=~caller
query parameter.
The following example shows a response to a request that includes the owner=~caller
and expand=feature:speaker&expand=feature:connectivity
query parameters.
The following example shows a response to a request that includes the owner=~caller
and expand=all
query parameters.
Response body properties
Property | Description | Type |
---|---|---|
|
List of connected endpoints associated with the customer account. |
Array of objects |
|
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
|
(Optional) Name used by the user to identify the endpoint. |
|
|
(Optional) Endpoint manufacturer. |
|
|
(Optional) Endpoint model. |
|
|
(Optional) Endpoint serial number. |
|
|
(Optional) Version of software on the endpoint. |
|
|
(Optional) List of methods to connect the endpoint to the internet and smart home hubs. |
Array of |
|
(Optional) Time the endpoint resource was created. |
String |
|
(Optional) List of features defined on the endpoint. |
Array of |
|
(Optional) List of units associated with the endpoint. |
Array of objects |
|
Unit ID, formatted as |
String |
|
(Optional) List of update operations available for this feature and endpoint. |
Array of |
|
(Optional) Heading in the Alexa app under which the endpoint displays. |
String |
|
(Optional) Indicates whether there are more results to return. |
Object |
|
Included when the response is truncated. Use this value in a subsequent request. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains a list of endpoints and associated information. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get endpoints by unit
Get the list of endpoints associated with a specified unit (room). You can also get endpoints by using Query endpoints (advanced search).
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 list of endpoints by unit, you make a GET
request to the /v2/endpoints
resource.
Request path and header example
GET /v2/endpoints?associatedUnits.id={unitId}&expand={expand}&maxResults={maxResults}&nextToken={nextToken}
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 |
---|---|---|---|---|
|
Query |
Filter endpoints to those associated with a particular unit. |
String |
Yes |
|
Query |
Get expanded information about each endpoint. |
String |
No |
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
Query |
Token from the previous response. |
String |
No |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with a list of endpoints associated with the specified unit.
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 to a request that includes the expand=all
query parameter.
Response body properties
Property | Description | Type |
---|---|---|
|
List of connected endpoints associated with the customer account. |
Array of objects |
|
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
|
(Optional) Name used by the user to identify the endpoint. |
|
|
(Optional) Endpoint manufacturer. |
|
|
(Optional) Endpoint model. |
|
|
(Optional) Endpoint serial number. |
|
|
(Optional) Version of software on the endpoint. |
|
|
(Optional) List of methods to connect the endpoint to the internet and smart home hubs. |
Array of |
|
(Optional) Time the endpoint resource was created. |
String |
|
(Optional) List of features defined on the endpoint. |
Array of |
|
(Optional) List of units associated with the endpoint. |
Array of objects |
|
Unit ID, formatted as |
String |
|
(Optional) List of update operations available for this feature and endpoint. |
Array of |
|
(Optional) Heading in the Alexa app under which the endpoint displays. |
String |
|
(Optional) Indicates whether there are more results to return. |
Object |
|
Included when the response is truncated. Use this value in a subsequent request. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains a list of endpoints in the specified unit. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get endpoint by ID
Get endpoint attributes for the specified endpoint. The caller must have access to the endpoint.
To get the endpoint ID, use Get endpoints by owner, Get endpoint by serial number, or Get endpoints by unit.
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 attributes of the specified endpoint ID, you make a GET
request to the /v2/endpoints/{endpointId}
resource. This request doesn't require filtering parameters, such as owner
.
Request path and header example
GET /v2/endpoints/{endpointId}?expand={expand}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID for the requested endpoint. |
String |
Yes |
|
Query |
Get expanded information about the endpoint. |
String |
No |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with information about the specified 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 following example shows the response that includes the expand=feature:speaker&expand=feature:connectivity
query parameters to get the speaker and connectivity features of the specified endpoint.
The following example shows a response to a request that includes the expand=all
query parameter to get all attributes of the specified endpoint.
Response body properties
Property | Description | Type |
---|---|---|
|
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
|
(Optional) Name used by the user to identify the endpoint. |
|
|
(Optional) Endpoint manufacturer. |
|
|
(Optional) Endpoint model. |
|
|
(Optional) Endpoint serial number. |
|
|
(Optional) Version of software on the endpoint. |
|
|
(Optional) List of methods to connect the endpoint to the internet and smart home hubs. |
Array of |
|
(Optional) Time the endpoint resource was created. |
String |
|
(Optional) List of features defined on the endpoint. |
Array of |
|
(Optional) List of units associated with the endpoint. |
Array of objects |
|
Unit ID, formatted as |
String |
|
(Optional) List of update operations available for this feature and endpoint. |
Array of |
|
(Optional) Heading in the Alexa app under which the endpoint displays. |
String |
|
(Optional) Indicates whether there are more results to return. |
Object |
|
Included when the response is truncated. Use this value in a subsequent request. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains endpoint information |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get endpoint by serial number
Get endpoints associated with the specified serial number of a device. The caller must have access to the endpoint. Usually, there is a one-to-one mapping between endpoint and serial number.
You can also look up a specific endpoint by endpoint ID. For more details, see Get endpoint by ID.
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 an endpoint by serial number, you make a GET
request to the /v2/endpoints
resource.
Request path and header example
GET /v2/endpoints?serialNumber.value.text={serialNumber}&expand={expand}
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 |
---|---|---|---|---|
|
Query |
Filter endpoints to those associated with a serial number. |
String |
Yes |
|
Query |
Get expanded information about the endpoint. |
String |
No |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
, along with an endpoint for the specified serial number.
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 to a request to get the endpoint associated with the specified serial number.
Response body properties
Property | Description | Type |
---|---|---|
|
List of connected endpoints associated with the customer account. |
Array of objects |
|
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
|
(Optional) Name used by the user to identify the endpoint. |
|
|
(Optional) Endpoint manufacturer. |
|
|
(Optional) Endpoint model. |
|
|
(Optional) Endpoint serial number. |
|
|
(Optional) Version of software on the endpoint. |
|
|
(Optional) List of methods to connect the endpoint to the internet and smart home hubs. |
Array of |
|
(Optional) Time the endpoint resource was created. |
String |
|
(Optional) List of features defined on the endpoint. |
Array of |
|
(Optional) List of units associated with the endpoint. |
Array of objects |
|
Unit ID, formatted as |
String |
|
(Optional) List of update operations available for this feature and endpoint. |
Array of |
|
(Optional) Heading in the Alexa app under which the endpoint displays. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the endpoint for the specified serial number. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Query endpoints (advanced search)
Get a list of endpoints that match the criteria that you specify. This operation supports queries by unit, manufacturer, and model.
You can construct the query with multiple AND or OR clauses. For example, you can search for endpoints that meet the following conditions: (unit ID is amzn1.alexa.unit.unitOne
OR amzn1.alexa.unit.unitTwo
) AND manufacturer name is someManufacturer
.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, UK, FR, CA, IT, DE |
US |
Request
To query endpoints, you make a POST
request to the /v2/endpointQuery
resource.
Request header example
POST /v2/endpointQuery
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
String |
Yes |
Request body example
The following example shows a request for endpoints in two units.
The following request queries endpoints in two units, filtered by device manufacturer.
The following request queries endpoints in two units, filtered by device manufacturer and model.
Request body parameters
Parameter | Description | Type | Required |
---|---|---|---|
|
Filtering conditions for the query. The fields can be |
Object |
Yes |
|
Query that logically joins two or more parameters by using the |
Array of objects |
No |
|
Query fields whose values must exactly match the corresponding value in the returned endpoints. |
Object |
No |
|
Query that logically joins two or more parameters by using the |
Array of objects |
No |
|
Query fields whose values must exactly match the corresponding value in the returned endpoints. |
Object |
No |
|
List of endpoint attributes to fetch. To get all endpoint attributes, specify |
Array of strings |
No |
|
Indicates whether to return a specific page of the results. |
Object |
No |
|
Token to retrieve a specific page of the paginated results. If this token isn't present, the response contains the first page of results. |
String |
No |
|
Maximum number of results to return in the response body. |
Number |
No |
Response
A successful response returns HTTP 200 OK
, along with a list of endpoints that match the filter criteria.
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 the response to the query to filter endpoints on feature:connectivity
in the expand
array.
The following example shows the response to get the endpoints for the associatedUnits.id
.
Response body parameters
Parameter | Description | Type |
---|---|---|
|
List of connected endpoints associated with the customer account. |
Array of objects |
|
Unique ID for this endpoint that Amazon assigns to each customer device. |
String |
|
(Optional) Name used by the user to identify the endpoint. |
|
|
(Optional) Endpoint manufacturer. |
|
|
(Optional) Endpoint model. |
|
|
(Optional) Endpoint serial number. |
|
|
(Optional) Version of software on the endpoint. |
|
|
(Optional) List of methods to connect the endpoint to the internet and smart home hubs. |
Array of |
|
(Optional) Time the endpoint resource was created. |
String |
|
(Optional) List of features defined on the endpoint. |
Array of |
|
(Optional) List of units associated with the endpoint. |
Array of objects |
|
Unit ID, formatted as |
String |
|
(Optional) List of update operations available for this feature and endpoint. |
Array of |
|
(Optional) Heading in the Alexa app under which the endpoint displays. |
String |
|
(Optional) Indicates whether there are more results to return. |
Object |
|
Included when the response is truncated. Use this value in a subsequent request. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains filtered endpoint information |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update associated units
Update the list of associated units (rooms) for an endpoint. You also use this API to disassociate endpoints from units.
Review the following items before you update an endpoint-unit association:
- At this time, you can associate an endpoint with one unit.
- To change unit associations, the endpoint must have an active connection. Keep the device powered on and online for one minute after successfully calling this API.
- After you associate an endpoint to a room, the friendly name of the device might change. For example, "Mary's device" might change to "Guest's device."
- To disassociate an endpoint from a room, set the unit ID to your default unit wildcard
"~caller.defaultUnitId"{{ }}
. - Apply settings only after you associate a device with a unit. Any previous settings on a device are cleared when you update the unit association.
- When you change unit associations for an endpoint, the
endpointId
might change. The response contains the newendpointId
. - Setup mode is disabled when the endpoint is associated with a unit. Setup mode is enabled when the endpoint is associated with the caller's default unit or when the endpoint isn't associated with any unit.
To determine that the endpoint rebooted, you can poll for the connectivity status of the endpoint by using Get endpoints by unit
. Amazon recommends a polling interval of two minutes or greater. For example, use the following operation to get the connectivity status GET /v2/endpoints?associatedUnits.id=amzn1.alexa.unit.did.unitFour&connections.macAddress=mac.address.1&features[name:connectivity].properties[name:reachability].value.value=OK
. When this API returns an endpointId
, the endpoint rebooted and reconnected to the network successfully.
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 update an association, you make a PUT
request to the /v2/endpoints
resource.
Request path and header example
PUT /v2/endpoints/{endpointId}/associatedUnits
Host: api.amazonalexa.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID for the requested endpoint. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The following example shows a request to update the unit association for the specified endpoint.
The following example shows a request to disassociate an endpoint from a unit.
Request body properties
Property | Description | Type | Required |
---|---|---|---|
N/A |
List of units to associate with the endpoint. At this time, you can associate an endpoint with one unit. |
Array of strings |
Yes |
|
Unit ID, formatted as |
String |
Yes |
Response
A successful response returns HTTP 200 OK
, along with the endpoint ID and associated units.
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 response shows the new unit associated with the endpoint.
{
"endpoint": {
"id": "amzn1.alexa.endpoint.1",
"associatedUnits": [{
"id": "amzn1.alexa.unit.did.unitFour"
}]
}
}
Response body properties
Property | Description | Type |
---|---|---|
|
Describes the endpoint association. |
Object |
|
ID for the endpoint. Note: When you change unit associations for an endpoint, the endpoint ID might change
|
String |
|
List of associated units for the endpoint. At this time, you can associate an endpoint with one unit. |
Array of strings |
|
Formatted as Amazon Common Identifier (ACI), |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the updated unit association. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update friendly name
Change the friendly name for the specified endpoint. Alexa uses the friendly name for all GUI and VUI experiences. Customers can use the friendly name to control an endpoint, for example, "Alexa, turn on Kitchen Lights." To get the endpoint ID, use Get endpoints by owner, Get endpoint by serial number, or Get endpoints by unit.
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 update the friendly name, you make a POST
request to the /v2/endpoints
resource.
Request path and header example
POST /v2/endpoints/{endpointId}/friendlyName
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Request format
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID for the requested endpoint. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"type": "PLAIN",
"value": {
"text": "Front Doorbell"
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Format of the value field. Currently, the only supported type is plain text. |
String |
Yes |
|
Describes the name. |
Object |
Yes |
|
Friendly name given in plain text.
Names must contain at least one number or letter. |
String |
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 |
---|---|
|
Friendly name updated successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Deregister endpoint
Deregister the specified endpoint from your Amazon Business account. To get the endpoint ID, use Get endpoints by owner, Get endpoint by serial number, or Get endpoints by unit.
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 deregister an endpoint, you make a POST
request to the /v2/endpoints
resource.
Request path and header example
POST /v2/endpoints/{endpointId}/deregister
Host: api.amazonalexa.com
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID for the requested endpoint. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Endpoint deregistered successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Forget endpoint
Request that Alexa forget 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 remove an endpoint, you make a POST
request to the /v2/endpoints
resource.
Request path and header example
POST /v2/endpoints/{endpointId}/forget
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID for the requested endpoint. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK
.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Request succeeded. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Delete timers on endpoint
Delete all timers on the specified endpoint. To get the endpoint ID, use Get endpoints by owner, Get endpoint by serial number, or Get endpoints by unit. To delete timers on all endpoints in a unit, see Delete all timers for a unit.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
CA,DE, ES, FR, IT, US, UK |
CA,DE, ES, FR, IT, US, UK |
None |
Request
To delete timers, you make a DELETE
request to the /v1/alerts/timers
resource.
Request path and header example
DELETE /v1/alerts/timers?endpoint={endpointId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID for the requested endpoint. |
String |
Yes |
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 204 No Content
.
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 |
---|---|
|
Timers deleted on the specified endpoint successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Object definitions
The Endpoints API defines the following objects.
Connection object
The Connection
object defines the method that an endpoint uses to connect to the internet and smart home hubs.
Property | Description | Type |
---|---|---|
|
Type of connection. |
String |
|
Unique identifier for the network interface controller (NIC). |
String |
DisplayCategories object
The DisplayCategories
object defines the heading in the Alexa app, with the correct iconography, under which the endpoint displays.
Property | Description | Type |
---|---|---|
|
Primary display category of the endpoint. |
Object |
|
Name of the category. |
String |
|
Source of the category. Either explicitly set by the customer or reported as part of the original endpoint report. |
Array of strings |
|
All categories of the endpoint. |
List of objects |
|
Name of the category. |
String |
|
Source of the category. Either explicitly set by the customer or reported as part of the original endpoint report. |
Array of strings |
Error object
The Error
object describes the error that occurred.
Property | Description | Type |
---|---|---|
|
Type of error that occurred. |
String |
|
Human readable error message. |
String |
Feature object
The Feature
object defines the features associated with the endpoint, such as speaker volume.
Property | Description | Type |
---|---|---|
|
Name of the feature. |
String |
|
URL to use to retrieve expanded results for this feature. For example, |
String |
|
(Optional) List of properties of the requested feature. Included when |
Array of objects |
|
Name of the property. |
String |
|
Indicates whether the caller can read the property value. |
String |
|
Value of the property when |
Various |
|
Time the endpoint detected the state change. |
String |
|
(Optional) Describes the error encountered. |
Error object |
NameValue object
The NameValue
object is a container for names of objects.
The following table defines the properties of the object.
Property | Description | Type |
---|---|---|
|
Format of the value field. At this time, the only supported type is plain text. |
String |
|
Name. |
Object |
|
Name given in plain text. |
String |
Operation object
The Operation
object describes the update operations available for the specified endpoint and feature.
Property | Description | Type |
---|---|---|
|
Name of the update operation. |
String |
|
Full HTTP path that you can use in an update operation to set the |
String |
Related topics
- Alexa Smart Properties REST API Reference
- Endpoint Features REST API Reference
- Endpoint Settings REST API Reference
- Endpoint Wi-Fi Management REST API Reference
Last updated: Sep 25, 2024