Smart Home REST API Reference

The smart home REST API reference describes the operations for Alexa-connected smart home skills and device apps. The REST API definitions include the endpoints, authentication methods, and request and response parameters.

Guidelines for the REST API

Follow these guidelines to use the smart home REST API.

Use an access token in the request

Each API request must include an authorization header with a bearer access token retrieved from the Login with Amazon (LWA) OAuth 2.0 server.

To get the access token, use one of the following methods:

For API requests from a skill session, include the context.System.apiAccessToken retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest.
For out-of-session API requests from a website, app, or tool, you use your skill credentials to request an access token from LWA. For more details, see Get access token with skill credentials REST API or Steps to get an access token. In the request body, optionally set the scope to the operations that you want to access. For more details, see the documentation for the REST API that you plan to use.

Handle pagination in query results

For API query requests that return a large number of results, Alexa divides the results into pages. When the response contains more results than the current page can hold, the response body includes a paginationContext object with a nextToken value. You can iterate through the paged responses by sending the same query request with paginationContext.nextToken in the request header. Some REST API definitions allow additional filter parameters. If paginationContext is absent from the response, you've received the last page of results.

Example paged response

The following example response shows that there are more results. The nextToken property points to the next page of results.

{
    "paginationContext": {
        "nextToken": "someToken.2"
    },
    "results": [{
        ...
        },
        ...
    ]
}

Property	Description	Type
`paginationContext`	Indicates there are more matching results. If present, the response contains a subset of the results. When there are no more matching results, `paginationContext` isn't included in the response.	Object
`paginationContext.nextToken`	Identifies the next set of results to return. The token expires in 24 hours. Use this value for the `nextToken` parameter the request header in a subsequent request.	String

Note: Refer to the specific REST API interface for the definition of the paginationContext property in the response body.

Example request for next page

To get the next page of results, repeat your original request and include the nextToken value from the previous response as a query parameter.

The following example shows the HTTP header that includes the nextToken value. On receipt of this request, Alexa sends the next set of results. If there are additional results, the response includes a new token. When Alexa returns the last page of results, the response doesn't include paginationContext.

GET /{resource}?nextToken=someToken.2
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Limit the number of results

Use the maxResults parameter in the request to control how many results Alexa returns per page. In the response, Alexa returns up to the specified number of results.

The following example shows the HTTP header that requests up to 10 results. On receipt of this request, Alexa sends the next set of results. If there are more than 10 results, Alexa includes another token in the response to enable you to get the next set of results.

GET {resource}?maxResults=10&nextToken=someToken.2
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

The following table shows the definition of the request path parameters.

Parameter	Located in	Description	Type	Required
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response.	String	No
`maxResults`	Query	Maximum number of results to return in the response.	Number	No

Amazon request ID

Some API responses include an X-Amzn-RequestId parameter in the response header. If you encounter an issue, provide this ID when contacting Amazon support to help troubleshoot your specific request. For example, the response might contain the following header:

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

Property	Description	Type
`request-id`	Unique identifier for the request.	String

In this section

Credential Locker – Use the Credential Locker REST API in your smart home skill to view customer Thread network credentials or create a new customer Thread network for Matter device setup.
Smart Home Skill Evaluation – Use the Smart Home Evaluation REST API to start test evaluations and get evaluation results. Smart home evaluations verify that your implementation of the Alexa smart home interfaces.

Was this page helpful?

Provide feedback

Last updated: May 12, 2026