Skill Validation API
The Alexa Skill Validation API is an asynchronous API that can be used by skill developers to validate their skills before submitting them for certification or at any time during development as regression testing. A successful response may contain both successful and failed validation results. The Alexa Skill Validation API will also determine if a skill update qualifies for instant update to a live skill.
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.
POST
Submit a skill to the Skill Validation API for validation.
HTTP/1.1
POST /v1/skills/{skillId}/stages/{stage}/validations
| Field | Description | Parameter Type | Required? |
|---|---|---|---|
| skillId | Unique identifier of skill. | String | Yes |
| stage | Stage of the skill. One of: "development" or "live" | String | Yes |
The stage value chosen determines which stage of the skill is validated.
Request
Request headers
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: string
Authorization: string
Request Body
{
"locales": [Array of strings]
}
| Field | Optional? | Description |
|---|---|---|
| locales | No | Locale(s) to perform validations for. All locales are supported. |
Response
Response header
Content-Type: application/json
Location: /skills/{skillId}/stages/{stage}/validations/{validationId}
X-Amzn-RequestId: string
Response body
{
"id": string,
"status": "IN_PROGRESS"
}
Response exceptions (not 202)
{
"id": string,
"message": string
}
Examples
Sample request for skill with a development skill
POST /v1/skills/1234/stage/development/validations
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
Authorization: MYTOKEN
{
"locales": ["en-US"]
}
Sample responses to skill in development stage
HTTP 200 OK (in progress)
Content-Type: application/json
Location: /skills/22222222-2222-2222-2222-222222222222/stage/development/validations/33333333-3333-3333-3333-333333333333
X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
{
"id": "33333333-3333-3333-3333-333333333333",
"status": "IN_PROGRESS",
"result": null
}
HTTP 500 Internal Server Error
Content-Type: application/json
X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
{
"message": "An error occurred."
}
GET
The results of a skill validation are obtained with GET.
HTTP/1.1
GET /v1/skills/{skillId}/stages/{stage}/validations/{validationId}
| Field | Description | Parameter Type | Required? |
|---|---|---|---|
| skillId | Unique identifier of skill. | Path | Yes |
| stage | Stage of the skill. One of: "development" or "live" | String | Yes |
The stage value chosen determines which stage of the skill is validated.
For an example of a sample request and successful response, see Supported validations.
Request
Request headers
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: string
Authorization: string
Request body
Empty body
Response
Response header
Content-Type: application/json
X-Amzn-RequestId: string
Response body
{
"id": string,
"status": string enum["IN_PROGRESS", "SUCCESSFUL", "FAILED"],
"result": {
"validations": [
{
"title": string,
"description": string,
"category": string,
"locale": string,
"status": string enum["SUCCESSFUL", "FAILED"],
"importance": string enum["REQUIRED", "RECOMMENDED"]
}
],
"error": {
"message": string
}
}
}
| Field | Description |
|---|---|
| id | UUID generated for this request |
| status | Current status of this validation. "FAILED" will be returned if any validations are "FAILED", or if there was an error |
| validations -> title | Title of validation |
| validations -> description | Human-readable description with a brief explanation of validation |
| validations -> category | Dot-delimited string of category |
| validations -> locale | Locale of specific validation |
| validations -> status | Status of specific validation |
| validations -> importance | Importance of specific validation |
| error -> code | Externally referenceable code for error |
| error -> message | Human-readable message of validation |
Response exception (non-200)
{
"id": string,
"message": string
}
| Field | Description |
|---|---|
| message | A human-readable description of error |
See Response codes.
HTTP 200 OK (in progress)
This sample response indicates the final response is in progress, but not yet available.
Content-Type: application/json
X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
{
"id": "333-3333-3333-3333-333",
"status": "IN_PROGRESS",
"results": null
}
HTTP 404 Not Found
The requested validation for the skill was not found.
Content-Type: application/json
X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
{
"message": "No validation found for given id."
}
HTTP 200 OK (Failed)
The validation was not successfully completed.
Content-Type: application/json
X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
{
"id": "33333333-3333-3333-3333-333333333333",
"status": "FAILED",
"result": {
"error": {
"message": "Skill Validation Not Allowed"
}
}
}
Response codes
| Requests | Responses |
|---|---|
| 202 | Skill validation has successfully begun |
| 403 | API user does not have permission or is currently in a state that does not allow calls to this API |
| 404 | The specified skill, stage or validation does not exist. The error response will contain a description that indicates the specific resource type that was not found. |
| 409 | This request conflicts with another one currently being processed. |
| 429 | API user has exceed the permitted request rate. |
| 500 | Internal server error |
Supported validations
This section describes the validations that are run by the Skill Validation API.
The following table describes how the Skill Validation API determines the overall status of the validation request.
| validations->importance | validations->status | Overall Status |
|---|---|---|
| Recommended/Required | Successful | Successful |
| Recommended | Failed | Successful |
| Required | Failed | Failed |
If any test with an importance of "RECOMMENDED" has a status of "FAILED", the overall status can still be "SUCCESSFUL" if no tests with an importance of "REQUIRED" have a status of "FAILED".
Example phrase validation
Sample request for skill validation
GET /skills/22-22222/stage/development/validations/333-3333-3333-3333-333
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
Authorization: MYTOKEN
Empty body
Sample response to skill validation
HTTP 200 OK (Succeeded) with full response
Content-Type: application/json
X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
{
"id": "11111111-1111-1111-1111-111111111111",
"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. (i.e. Alexa).",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
},
{
"locale": "en-US",
"title": "Example Phrase must contain invocation name",
"description": "Your example phrase must contain the invocation name: [reindeer skill].",
"status": "FAILED",
"importance": "RECOMMENDED"
},
{
"locale": "en-US",
"title": "Example Phrase must contain invocation name",
"description": "Your example phrase must contain the invocation name: [reindeer skill].",
"status": "FAILED",
"importance": "RECOMMENDED"
},
{
"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": "Your example phrase must not contain special characters. However, '[@, !, #, $, %, &, (, ), *, /, :, {, [, ;, |, \, <, }, ], ^, >, _]' was found.",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
},
{
"locale": "en-US",
"title": "Example Phrase must contain invocation name",
"description": "Your example phrase must contain the invocation name: [reindeer skill].",
"status": "FAILED",
"importance": "RECOMMENDED"
},
{
"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": "Your example phrase must not contain special characters. However, '[@, !, #, $, %, &, (, ), *, /, :, {, [, ;, |, \\, <, }, ], ^, >, _]' was found.",
"status": "SUCCESSFUL",
"importance": "REQUIRED"
},
{
"locale": "en-US",
"title": "Example Phrase must contain invocation name",
"description": "Your example phrase must contain the invocation name: [reindeer skill].",
"status": "FAILED",
"importance": "RECOMMENDED"
}
]
}
}
Sample responses to update live skill in development stage
This section identifies the live skill validations that are run by the Skill Validation API. This API will determine if a skill is eligible or ineligible for live skill updates.
Sample successful response for a live skill
The sample below shows the response if your skill is eligible for live skill updates.
{
"title": "Eligibility to update your live skill instantly",
"description": "Your skill contains changes that make it eligible to update your live skill instantly. For more information see https://www.amazon.com/alexa/updateyourliveskillinstantly",
"status": "SUCCESSFUL",
"importance": "RECOMMENDED"
}
Sample failed response for a live skill
The sample below shows the response if your skill is ineligible for live skill updates.
{
"title": "Eligibility to update your live skill instantly",
"description": "Your skill contains changes that make it ineligible to update your live skill instantly. For more information see https://www.amazon.com/alexa/updateyourliveskillinstantly",
"status": "FAILED",
"importance": "RECOMMENDED"
}