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.
- Create beta test
- Get beta test
- Update beta test
- Start beta test
- End beta test
- Get list of testers for a beta test
- Add testers to a beta test
- Remove testers from a beta test
- Send reminder to testers
- Request feedback from testers
- Pagination and filtering of results
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.
|
maxResults | Integer. 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. |