Skill Beta Testing API

The Skill Beta Testing API is an asynchronous API that can be used by skill developers to set up skill beta testing for a limited audience before releasing a skill for production. You can also use this API to test changes to an existing skill, while still keeping the currently live version of the skill available for the general public. You can invite friends or family, your social network contacts, or other people for whom you have an email address to test your skill and provide feedback. You can send up to 500 invitations per test. At any time, you can add testers, remove testers, or end a test. You can get feedback on your skill throughout the testing cycle, and reduce costs by making fixes before you release the skill to production. Using skill beta testing can help increase your chances of skill success.

The API's endpoint is https://api.amazonalexa.com. Each API request must have an Authorization header whose value should be the access token retrieved from Login with Amazon.

Some of the APIs relate to setting up and managing the beta test, and other APIs relate to managing the beta testers.

Create beta test

Creates a beta test.

Request

POST /v1/skills/{skillId}/betaTest

Request body

The feedbackEmail is the email address to which the beta tester can send feedback.

{
  "feedbackEmail": "string"
}

Response

201 Success. Return a URL to track the resource in 'Location' header.

Errors

Code Description
400 Bad request
401 The auth token is invalid/expired or doesn't have access to the resource.
404 The resource being requested is not found.
409 The request could not be completed due to a conflict with the current state of the target resource.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.

Get beta test

Obtains the beta test details for a specified skill ID.

Request

GET /v1/skills/{skillId}/betaTest

Response

200 Success.

The beta test manifest that contains the information about the beta test is returned, as follows:

{
  "expiryDate": "2018-09-26T07:14:13.378Z",
  "status": "IN_DRAFT",
  "feedbackEmail": "string",
  "invitationUrl": "string",
  "invitesRemaining": 0
}

Errors

Code Description
400 Bad request
401 The auth token is invalid/expired or doesn't have access to the resource.
404 The resource being requested is not found.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.

Update beta test

Updates the details of a beta test. Currently only the feedback email can be updated.

Request

PUT /v1/skills/{skillId}/betaTest

Request body

Include a new value for the feedbackEmail value, which is the email address to which the beta tester can send feedback.

{
  "feedbackEmail": "string"
}

Response

204 Success. No content.

Errors

Code Description
400 Bad request
401 The auth token is invalid/expired or doesn't have access to the resource.
404 The resource being requested is not found.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.

Start beta test

Start the beta test for the specified skill ID. This will start the clock for the test's duration, as a beta test can only last 90 days, although you can then create a new beta test.

Request

POST /v1/skills/{skillId}/betaTest/start

Response

202 Accept. Return a URL to track the resource in 'Location' header.

Errors

Code Description
400 Bad request
401 The auth token is invalid/expired or doesn't have access to the resource.
404 The resource being requested is not found.
409 The request could not be completed due to a conflict with the current state of the target resource.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.

End beta test

Ends the beta test for the specified skill ID. By default, a beta test will conclude after 90 days. You can end a beta test early with this API.

Request

POST /v1/skills/{skillId}/betaTest/end

Response

202 Accept. Return a URL to track the resource in 'Location' header.

Errors

Code Description
400 Bad request
401 The auth token is invalid/expired or doesn't have access to the resource.
404 The resource being requested is not found.
409 The request could not be completed due to a conflict with the current state of the target resource.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.

Get list of testers for a beta test

Obtain the list of testers who are in a particular beta test. See also: Pagination and filtering of results.

Request

GET /v1/skills/{skillId}/betaTest/testers

Response

200 Success.

A list of testers is returned, as follows. In this case, only one tester is shown, but there may be other testers in the array that is returned. Up to 500 testers may be included in a beta test.

{
  "testers": [
    {
      "emailId": "string",
      "associationDate": "2018-09-26T07:32:37.589Z",
      "isReminderAllowed": true,
      "invitationStatus": "ACCEPTED"
    }
  ],
  "isTruncated": true,
  "nextToken": "string"
}

Errors

Code Description
400 Bad request
401 The auth token is invalid/expired or doesn't have access to the resource.
404 The resource being requested is not found.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.

Add testers to a beta test

If you have an existing beta test, you can add testers to it, if you have not exceeded the limit of 500 testers.

Request

POST /v1/skills/{skillId}/betaTest/testers/add

Request body

Include an array of emailId values, each of which is a tester's email address.

{
  "testers": [
    {
      "emailId": "string"
    }
  ]
}

Response

204 Success. No content.

Errors

Code Description
400 Bad request
401 The auth token is invalid/expired or doesn't have access to the resource.
404 The resource being requested is not found.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.

Remove testers from a beta test

Remove testers from an existing beta test.

Request

POST /v1/skills/{skillId}/betaTest/testers/remove

Request body

Include an array of emailId values, each of which is a tester's email address.

{
  "testers": [
    {
      "emailId": "string"
    }
  ]
}

Response

204 Success. No content.

Errors

Code Description
400 Bad request
401 The auth token is invalid/expired or doesn't have access to the resource.
404 The resource being requested is not found.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.

Send reminder to testers

Send reminder to the testers in a beta test for the given Alexa skill. The system will send an invitation email to each tester and add entitlement on the acceptance.

Request

POST /v1/skills/{skillId}/betaTest/testers/sendReminder

Request body

{
  "testers": [
    {
      "emailId": "string"
    }
  ]
}

Response

204 Success. No content.

Errors

Code Description
400 Bad request
401 The auth token is invalid/expired or doesn't have access to the resource.
404 The resource being requested is not found.
409 The request could not be completed due to a conflict with the current state of the target resource.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.

Request feedback from testers

Request feedback from the testers in a beta test for the specified Alexa skill. The system will send notification emails to testers, and these emails will request feedback.

Request

POST /v1/skills/{skillId}/betaTest/testers/requestFeedback

Request body

{
  "testers": [
    {
      "emailId": "string"
    }
  ]
}

Response

204 Success. No content.

Errors

Code Description
400 Bad request
401 The auth token is invalid/expired or doesn't have access to the resource.
404 The resource being requested is not found.
409 The request could not be completed due to a conflict with the current state of the target resource.
429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.

Pagination and filtering of results

For API calls that return a list, you can optionally control the number of results that appear at once with maxResults, and you can use nextToken to obtain the next set of results with the next API call. This sample request has been given line breaks here for readability, but should be concatenated without line breaks. Some of the API calls that return lists also allow additional parameters for filtering.

GET  /v1/skills/AAA-xxxx-yyyy/betaTest/testers?
     nextToken=VWB111111111
     &maxResults=5
Parameter Description
nextToken String. The nextToken value can be used in a subsequent API call to obtain the next values after the maxResults are shown. This token has a 24-hour expiry.
maxResultsInteger. The maximum number of results to display in a single API call. The default is 100, and the range is 1-500. The `nextToken` value can be used to obtain the remaining results in a subsequent API call.