Skill Rollback REST API Reference

Use the Skill Rollback REST API to revert your skill to a previous live version without having to submit the skill for recertification. For example, if your new skill version introduced a bug or any other unintended behaviors, you can roll back the skill to a previous version.

To roll back a skill, your skill must meet the rollback eligibility requirements. For more details, see Skill Rollback.

You can roll back a skill in the Alexa developer console also. For details, see Roll back your skill by using the console. Or, you can roll back a skill by using the Alexa Skills Kit (ASK) Command Line Interface rollback-skill command.

API endpoint

The endpoint of the Skill Rollback API is https://api.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 Get an Access Token for SMAPI.

Operations

The Skill Rollback API includes the following operations.

Operation HTTP method and URI

Get rollback status

GET /v1/skills/{skillId}/rollbacks/{rollbackRequestId}

Submit for rollback

POST /v1/skills/{skillId}/rollbacks

Get rollback status

Get the rollback status of the specified skill and rollback ID.

Request

To get the rollback status, you make a GET request to the rollbacks resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/rollbacks/{rollbackRequestId}
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

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

rollbackRequestId

Path

Identifies the rollback request.
Use ~latest to get the latest rollback status.

String

Yes

access token

Header

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 the rollback status. 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

{
    "id": "rollback.id",
    "status": "IN_PROGRESS",
    "submissionTime": "Sat Jun 27 01:24:01 UTC 2020",
    "targetVersion": "1",
    "errors": [{
        "code": "",
        "validationDetails": {},
        "message": ""
    }]
}

Response body properties

Property Description Type

id

Identifies the rollback request.

String

targetVersion

Version of the skill to rollback to.

String

submissionTime

Data and time of the rollback request.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

status

Current status of the rollback request. If the rollback failed, you can resubmit the rollback request.
Valid values: FAILED, INELIGIBLE, IN_PROGRESS, SUCCEEDED.

String

errors[]

List of errors.

Array of objects

errors[].code

HTTP status code that reflects the error.

String

errors[].validationDetails

Machine-readable structure that contains information about the error. Included if HTTP 4XX validation errors occur.

Object

errors[].message

Human readable error message.

String

HTTP status codes

Status Description

200 OK

Response body contains the rollback status and target version.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn'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

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill 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.

Submit for rollback

Submit the specified skill for rollback to the specified target version. You can submit a skill for rollback or publishing at one time, but not both at the same time.

Request

To roll back a skill, you make a POST request to the rollbacks resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/rollbacks
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
  "targetVersion" : "2"  
}

Request body properties

Property Description Type Required

targetVersion

Skill version to which you want to roll back to.

String

Yes

Response

A successful response returns HTTP 202 Accepted, along with a Location in the header that contains a path to the rollback and an ID in the body to track the rollback request. 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.

{
    "rollbackRequestId": "rollback.id.1"
}

Response body properties

Property Description Type

rollbackRequestId

Identifies the rollback request.

String

HTTP status codes

Status Description

202 Accepted

Response body contains the rollback request ID.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn'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

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill 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.