Beta Test Management REST API Reference

Use the Beta Test Management REST API to set up a beta test for a limited audience before you release your Alexa skill for production. Or, use this API to test changes to an existing skill and keep the live version of the skill available for the general public.

You can get feedback on your skill throughout the testing cycle, and reduce costs by making fixes before you release the skill to production. Beta testing can help increase your chances of skill success.

For more details about how to invite people to your test your skill, see Beta Tester Management REST API Reference.

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 Beta Test Management API includes the following operations.

Operation HTTP method and URI

Create beta test

POST /v1/skills/{skillId}/betaTest

End beta test

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

Get beta test

GET /v1/skills/{skillId}/betaTest

Start beta test

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

Update beta test

PUT /v1/skills/{skillId}/betaTest

Create beta test

Create a new beta test for the specified skill.

Request

To create a beta test, you make a POST request to the betaTest resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/betaTest
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.

{
  "feedbackEmail": "example@email.address"
}

Request body properties

Property Description Type Required

feedbackEmail

Email address to which the beta tester can send feedback.

String

Yes

Response

A successful response returns HTTP 201 Created, along with a Location in the header that contains a URL to track the beta test. 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 response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

201 Created

Request to create a beta test succeeded.
The response header contains a Location parameter that includes a URL to track the beta test.

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.

End beta test

End the beta test for the specified skill. By default, a beta test ends after 90 days. Use this API to end the test before 90 days.

Request

To end a test, you make a POST request to the betaTest resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/betaTest/end
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

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 202 Accept. 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 response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

202 Accept

Request to end the beta test succeeded.

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.

Get beta test

Get the details about the beta test for a specified skill ID.

Request

To get the beta test details, you make a GET request to the betaTest resource.

Request path and header example

Copied to clipboard.

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

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 details about the beta test. 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

{
    "expiryDate": "2018-09-26T07:14:13.378Z",
    "status": "IN_DRAFT",
    "feedbackEmail": "example@email.address",
    "invitationUrl": "https://example.com",
    "invitesRemaining": 500
}

Response body properties

Property Description Type

expiryDate

Date that the beta test expires.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

status

Status of the test.
Valid values: IN_DRAFT, STARTING, RUNNING, STOPPING, ENDED.

String

feedbackEmail

Email address to which the beta tester can send feedback

String

invitationUrl

URL to the beta test invitation.

String

invitesRemaining

Number of invitations that you can send for the beta test.

String

HTTP status codes

Status Description

200 OK

Response body contains details about the beta test.

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.

Start beta test

Start the beta test for the specified skill. After you start the test, it can run for up to 90 days. After that, you can create a new beta test.

Request

To start a test, you make a POST request to the betaTest resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/betaTest/start
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

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 202 Accept. 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 response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

202 Accept

Request to start the beta test succeeded.
The response header contains a Location parameter that includes a URL to track the beta test.

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.

Update beta test

Updates the details of a beta test for the specified skill.

Request

To update a test, you make a PUT request to the betaTest resource.

Request path and header example

Copied to clipboard.

PUT /v1/skills/{skillId}/betaTest
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.

{
  "feedbackEmail": "example@email.address"
}

Request body properties

Property Description Type Required

feedbackEmail

Email address to which the beta tester can send feedback.

String

Yes

Response

A successful response returns HTTP 204 No Content. 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 response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Request to update a beta test succeeded.

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.

Last updated: May 11, 2023