Alexa Skills REST API Reference

The Alexa Skills REST API reference describes the operations for Alexa features that you can add to your Alexa skill and for Alexa skill management tasks that you can do programmatically. The REST API definitions include the endpoints, authentication methods, and request and response parameters.

Authentication

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.

Pagination in Query results

For query requests that return a large number of results, Alexa divides the results into pages and includes a paginationContext object in the response. You can iterate through the paged response by sending the same query request with paginationContext.nextToken in the request header. Some REST API definitions allow additional filter parameters.

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

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 more results, Alexa includes another token in the response to enable you to get the next set of results. 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

You can control the number of results on a page by including the maxResults parameter in the request. In the response, Alexa returns up to the specified number of results.

The following example shows the HTTP header that includes the maxResults and nextToken values. On receipt of this request, Alexa sends the next set of results up to the 10. 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

In some REST APIs, Alexa includes the X-Amzn-RequestId parameter in the response header. If a problem occurs, Amazon can use the request-id to help troubleshoot problems. 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

Was this page helpful?

Last updated: Nov 26, 2024