Skill Validation REST API Reference
Use the Skill Validation REST API to validate your skill at any time during development and before you submit the skill for certification. You can also use the API to determine if a skill update qualifies for an instant update to a live skill.
You can validate your skill in the Alexa developer console also. For details, see Validate and test your skill.
API endpoint
The endpoint of the Skill Validation 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 Validation API includes the following operations.
| Operation | HTTP method and URI |
|---|---|
|
| |
|
|
Get validation status
Get the validation status and the results of completed validations.
Request
To get the validation status, you make a GET request to the validations resource.
Request path and header example
GET /v1/skills/{skillId}/stages/{stage}/validations/{validationId}
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 |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
|
Header |
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 a list of completed validations.
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": "validation.id.1",
"status": "SUCCESSFUL",
"result": {
"validations": [{
"locale": "en-US",
"title": "Not enough example phrases provided",
"description": "Required: Provide at least 1 example phrase",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
},
{
"locale": "en-US",
"title": "Too many Example Phrases provided",
"description": "Please limit your entry to a maximum of 3 example phrases.",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
},
{
"locale": "en-US",
"title": "Example Phrase has duplicate phrases",
"description": "Your example phrases must not be duplicates. Please provide unique entries.",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
},
{
"locale": "en-US",
"title": "Example Phrase too short",
"description": "Your example phrase does not meet the minimum character limit of 2 characters.",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
},
{
"locale": "en-US",
"title": "Example Phrase exceeds maximum length",
"description": "Your example phrase has exceeded the maximum character limit of 200 characters.",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
},
{
"locale": "en-US",
"title": "Example Phrase contains special characters",
"description": "Example phrases can only contain apostrophes, quotation marks, question marks, periods, exclamation points, and commas.",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
},
{
"locale": "en-US",
"title": "Example Phrase cannot be blank",
"description": "The example phrase may not be left empty. At least one example phrase must exist.",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
},
{
"locale": "en-US",
"title": "Example Phrase must start with Wake Word",
"description": "The example phrase must start with a valid wake word. (Alexa).",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
},
{
"locale": "en-US",
"title": "Example Phrase must contain invocation name",
"description": "Your example phrase must contain the invocation name: [Quick Trivia].",
"status": "FAILED",
"importance": "RECOMMENDED"
},
{
"locale": "en-US",
"title": "Example Phrase contains special characters",
"description": "Your example phrase must not contain special characters. However, '[@, !, #, $, %, &, (, ), *, /, :, {, [, ;, |, \, <, }, ], ^, >, _]' was found.",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
}
]
}
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
Property |
Description |
Type |
|
|
Identifies the validation request. |
String |
|
|
Current state of the validation request. Note: If any test with an importance of
RECOMMENDED has a result.validations[].status of FAILED, status is SUCCESSFUL. However, if any test with an importance of REQUIRED has a result.validations[].status of FAILED, the status is FAILED. |
String |
|
|
Result of the validation. |
Object |
|
|
List of validations executed against the skill. |
Array of objects |
|
|
Locale of the validation. |
String |
|
|
Short, human readable title of the validation performed. |
String |
|
|
Human readable description of the validation performed. Might include instructions on how to address validation failures. |
String |
|
|
(Optional) Dot-delimited category name. |
String |
|
|
Status of the validation. |
String |
|
|
Defines the importance of fixing the failure. |
String |
|
|
(Optional) Included when an error occurs executing the validation. |
Object |
|
|
HTTP status code that reflects the error. |
String |
|
|
Human readable error message. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains status and results of the validation. |
|
|
Indicates that one or more properties in the request body are invalid. |
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
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. |
|
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Submit for validation
Submit the specified skill for validation testing.
Request
To validate a skill, you make a POST request to the validations resource.
Request path and header example
POST /v1/skills/{skillId}/stages/{stage}/validations
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
|
Header |
String |
Yes |
Request body example
{
"locales": ["en-US"]
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
List of locales in which to validate the skill. |
Array of strings |
Yes |
Response
A successful response returns HTTP 202 Accepted, along with a Location in the header that contains a path to the validation and an ID in the body to track the validation 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.
{
"id": "validation.id.1",
"status": "IN_PROGRESS",
"result": null
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Identifies the validation request. |
String |
|
|
Current state of the validation request. Note: If any test with an importance of
RECOMMENDED has a result.validations[].status of FAILED, status is SUCCESSFUL. However, if any test with an importance of REQUIRED has a result.validations[].status of FAILED, the status is FAILED. |
String |
|
|
Result of the validation. |
Object |
|
|
List of validations executed against the skill. |
Array of objects |
|
|
Locale of the validation. |
String |
|
|
Short, human readable title of the validation performed. |
String |
|
|
Human readable description of the validation performed. Might include instructions on how to address validation failures. |
String |
|
|
(Optional) Dot-delimited category name. |
String |
|
|
Status of the validation. |
String |
|
|
Defines the importance of fixing the failure. |
String |
|
|
(Optional) Included when an error occurs executing the validation. |
Object |
|
|
HTTP status code that reflects the error. |
String |
|
|
Human readable error message. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the validation ID and status, along with the validation results, if any. |
|
|
Indicates that one or more properties in the request body are invalid. |
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
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. |
|
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Object definitions
The following objects are used by the Skill Validation API.
Locale values
The following table shows valid values for the locale property.
| Locale code | Language |
|---|---|
|
|
Arabic (SA) |
|
|
German (DE) |
|
|
English (AU) |
|
|
English (CA) |
|
|
English (UK) |
|
|
English (IN) |
|
|
English (US) |
|
|
Spanish (ES) |
|
|
Spanish (MX) |
|
|
Spanish (US) |
|
|
French (CA) |
|
|
French (FR) |
|
|
Hindi (IN) |
|
|
Italian (IT) |
|
|
Japanese (JP) |
|
|
Portuguese (BR) |