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:

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?endpoint={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).

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

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

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

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

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

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

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

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

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

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

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

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

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

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

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

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

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

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

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

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

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

endpoint

Describes the endpoint association.

Object

endpoint.id

ID for the endpoint.
Formatted as an Amazon Common Identifier (ACI), amzn1.alexa.endpoint.{id}.

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

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

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update 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 code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

200 OK

Friendly name updated successfully.

400 Bad Request

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

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

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

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 code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

200 OK

Endpoint deregistered successfully.

400 Bad Request

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

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

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

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

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 code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

200 OK

Request succeeded.

400 Bad Request

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

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

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

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

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

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

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

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Object definitions

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

Property Description Type

type

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

String

message

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

String

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?

Last updated: Sep 25, 2024