Endpoints REST API Reference

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

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

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

Authentication

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

Operations

The Endpoints API includes the following operations.

Operation	HTTP Method and URI
Get endpoints by owner	`GET /v2/endpoints?owner={owner}&expand={expand}&maxResults={maxResults}&nextToken={nextToken}`
Get endpoints by unit	`GET /v2/endpoints?associatedUnits.id={unitId}&expand={expand}&maxResults={maxResults}&nextToken={nextToken}`
Get endpoint by ID	`GET /v2/endpoints/{endpointId}?expand={expand}`
Get endpoint by serial number	`GET /v2/endpoints?serialNumber.value.text={serialNumber}&expand={expand}`
Query endpoints (advanced search)	`POST /v2/endpointQuery`
Update associated units	`PUT /v2/endpoints/{endpointId}/associatedUnits`
Update friendly name	`POST /v2/endpoints/{endpointId}/friendlyName`
Deregister endpoint	`POST /v2/endpoints/{endpointId}/deregister`
Forget endpoint	`POST /v2/endpoints/{endpointId}/forget`
Delete timers on endpoint	`DELETE /v1/alerts/timers?endpointId={endpointId}`

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

Note: Get endpoints by owner returns endpoints that are not associated with a unit. To get endpoints associated with a unit, use 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 list of endpoints by owner, you make a GET request to the /v2/endpoints resource.

Request path and header example

Copied to clipboard.

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
`owner`	Query	Filter endpoints to those associated with the owner. `~caller` represents the customer identified by the access token. Valid value: `~caller`	String	Yes
`expand`	Query	Get expanded information about each endpoint. To get all endpoint attributes, specify `all`. To get expanded information about a feature, specify the feature name. You can specify this filter more than one time, for example, `expand=feature:brightness&expand=feature:connectivity`. Valid values: `all`, `feature:brightness`, `feature:color`, `feature:colorTemperature`, `feature:connectivity`, `feature:power`,`feature:speaker`, `feature:temperatureSensor`, `feature:thermostat`.	String	No
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–50. Default: 10.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

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

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
`results`	List of connected endpoints associated with the customer account. The order of the list might change based on the query parameters provided in the request.	Array of objects
`results[].id`	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String
`results[].friendlyName`	(Optional) Name used by the user to identify the endpoint.	`NameValue` object
`results[].manufacturer`	(Optional) Endpoint manufacturer.	`NameValue` object
`results[].model`	(Optional) Endpoint model.	`NameValue` object
`results[].serialNumber`	(Optional) Endpoint serial number.	`NameValue` object
`results[].softwareVersion`	(Optional) Version of software on the endpoint.	`NameValue` object
`results[].connections`	(Optional) List of methods to connect the endpoint to the internet and smart home hubs.	Array of `Connection` objects
`results[].creationTime`	(Optional) Time the endpoint resource was created. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`results[].features`	(Optional) List of features defined on the endpoint.	Array of `Feature` objects
`results[].associatedUnits`	(Optional) List of units associated with the endpoint.	Array of objects
`results[].associatedUnits[].id`	Unit ID, formatted as `amzn1.alexa.unit.did.{id}`.	String
`results[].operations`	(Optional) List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of `Operation` objects
`results[].displayCategories`	(Optional) Heading in the Alexa app under which the endpoint displays.	String
`paginationContext`	(Optional) Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request.	String

HTTP status codes

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

Get 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

Copied to clipboard.

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
`unitId`	Query	Filter endpoints to those associated with a particular unit. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`. For endpoints assigned to your Amazon Business account, set the value to `~caller.defaultUnitId`.	String	Yes
`expand`	Query	Get expanded information about each endpoint. To get all endpoint attributes, specify `all`. To get expanded information about a feature, specify the feature name. You can specify this filter more than one time, for example, `expand=feature:brightness&expand=feature:connectivity`. Valid values: `all`, `feature:brightness`, `feature:color`, `feature:colorTemperature`, `feature:connectivity`, `feature:power`,`feature:speaker`, `feature:temperatureSensor`, `feature:thermostat`.	String	No
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–50. Default: 10.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

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

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
`results`	List of connected endpoints associated with the customer account. The order of the list might change based on the query parameters provided in the request.	Array of objects
`results[].id`	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String
`results[].friendlyName`	(Optional) Name used by the user to identify the endpoint.	`NameValue` object
`results[].manufacturer`	(Optional) Endpoint manufacturer.	`NameValue` object
`results[].model`	(Optional) Endpoint model.	`NameValue` object
`results[].serialNumber`	(Optional) Endpoint serial number.	`NameValue` object
`results[].softwareVersion`	(Optional) Version of software on the endpoint.	`NameValue` object
`results[].connections`	(Optional) List of methods to connect the endpoint to the internet and smart home hubs.	Array of `Connection` objects
`results[].creationTime`	(Optional) Time the endpoint resource was created. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`results[].features`	(Optional) List of features defined on the endpoint.	Array of `Feature` objects
`results[].associatedUnits`	(Optional) List of units associated with the endpoint.	Array of objects
`results[].associatedUnits[].id`	Unit ID, formatted as `amzn1.alexa.unit.did.{id}`.	String
`results[].operations`	(Optional) List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of `Operation` objects
`results[].displayCategories`	(Optional) Heading in the Alexa app under which the endpoint displays.	String
`paginationContext`	(Optional) Indicates whether there are more results to return. For details, see Handling Pagination in Query Results	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request.	String

HTTP status codes

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

Get 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

Copied to clipboard.

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
`endpoint`	Path	ID for the requested endpoint. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`expand`	Query	Get expanded information about the endpoint. To get all attributes of the endpoint, specify `all`. To get expanded information about a feature, specify the feature name. You can specify this filter more than one time, for example, `expand=feature:brightness&expand=feature:connectivity`. Valid values: `all`, `feature:brightness`, `feature:color`, `feature:colorTemperature`, `feature:connectivity`, `feature:power`,`feature:speaker`, `feature:temperatureSensor`, `feature:thermostat`.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

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

Response body example

The following example shows 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
`id`	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String
`friendlyName`	(Optional) Name used by the user to identify the endpoint.	`NameValue` object
`manufacturer`	(Optional) Endpoint manufacturer.	`NameValue` object
`model`	(Optional) Endpoint model.	`NameValue` object
`serialNumber`	(Optional) Endpoint serial number.	`NameValue` object
`softwareVersion`	(Optional) Version of software on the endpoint.	`NameValue` object
`connections`	(Optional) List of methods to connect the endpoint to the internet and smart home hubs.	Array of `Connection` objects
`creationTime`	(Optional) Time the endpoint resource was created. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`features`	(Optional) List of features defined on the endpoint.	Array of `Feature` objects
`associatedUnits`	(Optional) List of units associated with the endpoint.	Array of objects
`associatedUnits[].id`	Unit ID, formatted as `amzn1.alexa.unit.did.{id}`.	String
`operations`	(Optional) List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of `Operation` objects
`displayCategories`	(Optional) Heading in the Alexa app under which the endpoint displays.	String
`paginationContext`	(Optional) Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request.	String

HTTP status codes

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

Get 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

Copied to clipboard.

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
`serialNumber`	Query	Filter endpoints to those associated with a serial number.	String	Yes
`expand`	Query	Get expanded information about the endpoint. To get all endpoint attributes, specify `all`. To get expanded information about a feature, specify the feature name. You can specify this filter more than one time, for example, `expand=feature:brightness&expand=feature:connectivity`. Valid values: `all`, `feature:brightness`, `feature:color`, `feature:colorTemperature`, `feature:connectivity`, `feature:power`,`feature:speaker`, `feature:temperatureSensor`, `feature:thermostat`.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

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

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
`results`	List of connected endpoints associated with the customer account. The order of the list might change based on the query parameters provided in the request.	Array of objects
`results[].id`	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String
`results[].friendlyName`	(Optional) Name used by the user to identify the endpoint.	`NameValue` object
`results[].manufacturer`	(Optional) Endpoint manufacturer.	`NameValue` object
`results[].model`	(Optional) Endpoint model.	`NameValue` object
`results[].serialNumber`	(Optional) Endpoint serial number.	`NameValue` object
`results[].softwareVersion`	(Optional) Version of software on the endpoint.	`NameValue` object
`results[].connections`	(Optional) List of methods to connect the endpoint to the internet and smart home hubs.	Array of `Connection` objects
`results[].creationTime`	(Optional) Time the endpoint resource was created. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`results[].features`	(Optional) List of features defined on the endpoint.	Array of `Feature` objects
`results[].associatedUnits`	(Optional) List of units associated with the endpoint.	Array of objects
`results[].associatedUnits[].id`	Unit ID, formatted as `amzn1.alexa.unit.did.{id}`.	String
`results[].operations`	(Optional) List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of `Operation` objects
`results[].displayCategories`	(Optional) Heading in the Alexa app under which the endpoint displays.	String

HTTP status codes

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

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

Copied to clipboard.

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
`access token`	Header	LWA token.	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
`query`	Filtering conditions for the query. The fields can be `and` or `or` lists, which can encompass additional lists of `and` or `or` filtering conditions. Include at least one filter.	Object	Yes
`query.and[]`	Query that logically joins two or more parameters by using the `and` logical operator.	Array of objects	No
`query.and[].match`	Query fields whose values must exactly match the corresponding value in the returned endpoints. Valid values: • `associatedUnits.id`: Unit ID by which to filter. Example: `amzn1.alexa.unit.did.unitOne` or `~caller.defaultUnitId`. • `manufacturer.value.text`: Alexa-enabled device manufacturer by which to filter. Example: `Amazon`. • `model.value.text`: Model of Alexa-enabled device by which to filter. Example: `Echo Dot (3rd generation)`.	Object	No
`query.or[]`	Query that logically joins two or more parameters by using the `or` logical operator.	Array of objects	No
`query.or[].match`	Query fields whose values must exactly match the corresponding value in the returned endpoints. Valid values: • `associatedUnits.id`: Unit ID by which to filter. • `manufacturer.value.text`: Alexa-enabled device manufacturer by which to filter. • `model.value.text`: Model of Alexa-enabled device by which to filter.	Object	No
`expand`	List of endpoint attributes to fetch. To get all endpoint attributes, specify `all`. Valid values: `all`, `feature:brightness`, `feature:color`, `feature:colorTemperature`, `feature:connectivity`, `feature:power`,`feature:speaker`, `feature:temperatureSensor`, `feature:thermostat`.	Array of strings	No
`paginationContext`	Indicates whether to return a specific page of the results.	Object	No
`paginationContext.nextToken`	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
`paginationContext.maxResults`	Maximum number of results to return in the response body. Valid values: 1–10.	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 object.

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
`results`	List of connected endpoints associated with the customer account. The order of the list might change based on the query parameters provided in the request.	Array of objects
`results[].id`	Unique ID for this endpoint that Amazon assigns to each customer device. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String
`results[].friendlyName`	(Optional) Name used by the user to identify the endpoint.	`NameValue` object
`results[].manufacturer`	(Optional) Endpoint manufacturer.	`NameValue` object
`results[].model`	(Optional) Endpoint model.	`NameValue` object
`results[].serialNumber`	(Optional) Endpoint serial number.	`NameValue` object
`results[].softwareVersion`	(Optional) Version of software on the endpoint.	`NameValue` object
`results[].connections`	(Optional) List of methods to connect the endpoint to the internet and smart home hubs.	Array of `Connection` objects
`results[].creationTime`	(Optional) Time the endpoint resource was created. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`results[].features`	(Optional) List of features defined on the endpoint.	Array of `Feature` objects
`results[].associatedUnits`	(Optional) List of units associated with the endpoint.	Array of objects
`results[].associatedUnits[].id`	Unit ID, formatted as `amzn1.alexa.unit.did.{id}`.	String
`results[].operations`	(Optional) List of update operations available for this feature and endpoint. If you don't have permission to view the data, the list is empty.	Array of `Operation` objects
`results[].displayCategories`	(Optional) Heading in the Alexa app under which the endpoint displays.	String
`paginationContext`	(Optional) Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request.	String

HTTP status codes

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

Update associated units

Update the list of associated units (rooms) for an endpoint. You also use this API to disassociate endpoints from units.

Important: When you associate Alexa devices or smart devices with a room or disassociate devices from a room, the devices must have an active connection to your Wi-Fi network and the internet for the update to complete successfully. The connection allows the device to complete an automatic reboot. Alexa Smart Properties retries these requests for one hour.

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 new endpointId.
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

Copied to clipboard.

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

Request body example

The 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
`id`	Unit ID, formatted as `amzn1.alexa.unit.did.{id}`. To remove an endpoint from a unit and return it to your Amazon Business account, set the value to `~caller.defaultUnitId`.	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 object.

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
`endpoint`	Describes the endpoint association.	Object
`endpoint.id`	ID for the endpoint. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`. Note: When you change unit associations for an endpoint, the endpoint ID might change	String
`endpoint.associatedUnits`	List of associated units for the endpoint. At this time, you can associate an endpoint with one unit.	Array of strings
`endpoint.associatedUnits[].id`	Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`, or `~caller.defaultUnitId`.	String

HTTP status codes

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

Update 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

Copied to clipboard.

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

Request body example

Copied to clipboard.

{
    "type": "PLAIN",
    "value": {
        "text": "Front Doorbell"
    }
}

Request body properties

Property	Description	Type	Required
`type`	Format of the value field. Currently, the only supported type is plain text. Valid values: `PLAIN`.	String	Yes
`value`	Describes the name.	Object	Yes
`value.text`	Friendly name given in plain text. Names must contain at least one number or letter. Valid values: 1–128 Unicode (UTF-8) characters. Characters must be numbers, letters, spaces, or apostrophes. You can use Chinese characters and non-Roman letters. No other special characters or punctuation allowed.	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 object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

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

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

Copied to clipboard.

POST /v2/endpoints/{endpointId}/deregister
Host: api.amazonalexa.com
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpoint`	Path	ID for the requested endpoint. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

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

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

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

Forget endpoint

Request that Alexa forget the specified endpoint.

Note: This call only applies to the Alexa representation of the endpoint. It doesn't propagate back to the entity that reported the endpoint to Alexa, such as a smart home skill. To make sure that the endpoint isn't automatically reconnected to Alexa, remove it from the reporter. For example, for endpoints reported by a manufacturer's smart home skill, remove the endpoint from the manufacturer's app before calling this operation.

Note: Don't use this operation to disassociate an endpoint from a unit. To disassociate an endpoint from a unit, use Update associated units.

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

Copied to clipboard.

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

Request body example

The request has no body.

Request body properties

The request has no body.

Response

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

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

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

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

Copied to clipboard.

DELETE /v1/alerts/timers?endpointId={endpointId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`endpointId`	Path	ID for the requested endpoint. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.endpoint.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

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

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

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

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`	Type of connection. Valid values: `TCP_IP`,`ZIGBEE`, `UNKNOWN`.	String
`macAddress`	Unique identifier for the network interface controller (NIC). Valid value: 1 – 32 characters.	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`	Primary display category of the endpoint.	Object
`primary.value`	Name of the category.	String
`primary.sources`	Source of the category. Either explicitly set by the customer or reported as part of the original endpoint report. Valid values: `CUSTOMER`, `ENDPOINT_REPORTER`.	Array of strings
`all`	All categories of the endpoint.	List of objects
`all[].value`	Name of the category.	String
`all[].sources`	Source of the category. Either explicitly set by the customer or reported as part of the original endpoint report. Valid values: `CUSTOMER`, `ENDPOINT_REPORTER`.	Array of strings

Error object

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

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

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

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

Feature object

The Feature object defines the features associated with the endpoint, such as speaker volume.

Property	Description	Type
`name`	Name of the feature. For example, `speaker`,`volume`.	String
`path`	URL to use to retrieve expanded results for this feature. For example, `/v2/endpoints/{endpointID}/features/speaker`. For more details, see Endpoint Features REST API Reference.	String
`properties`	(Optional) List of properties of the requested feature. Included when `expand=feature:<feature name>` in query parameters.	Array of objects
`properties[].name`	Name of the property.	String
`properties[].type`	Indicates whether the caller can read the property value. Valid values: `RETRIEVABLE`, `NOT_RETRIEVABLE`, `ERROR`.	String
`properties[].value`	Value of the property when `type` is `RETRIEVABLE`. The value definition depends on the feature. For more details, see Endpoint Features REST API Reference.	Various
`properties[].timeOfSample`	Time the endpoint detected the state change. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String
`properties[].error`	(Optional) Describes the error encountered. Included when `type = ERROR`.	Error object

NameValue object

The NameValue object is a container for names of objects.

The following table defines the properties of the object.

Property	Description	Type
`type`	Format of the value field. At this time, the only supported type is plain text. Valid values: `PLAIN`.	String
`value`	Name.	Object
`value.text`	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`	Name of the update operation.	String
`path`	Full HTTP path that you can use in an update operation to set the `name` property.	String

Was this page helpful?

Provide feedback

Last updated: Nov 19, 2024