Skill Validation REST API Reference

Note: Sign in to the developer console to build or publish your skill.

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 /v1/skills/{skillId}/stages/{stage}/validations/{validationId}`
Submit for validation	`POST /v1/skills/{skillId}/stages/{stage}/validations`

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

Copied to clipboard.

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
`skillId`	Path	Identifies the skill. Valid values: 1–255 characters.	String	Yes
`stage`	Path	Indicates stage of the skill. Valid values: `development`, `live`.	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 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
`id`	Identifies the validation request.	String
`status`	Current state of the validation request. Valid values: `IN_PROGRESS`, `SUCCESSFUL`, `FAILED`. 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`	Result of the validation.	Object
`result.validations[]`	List of validations executed against the skill.	Array of objects
`result.validations[].locale`	Locale of the validation.	String
`result.validations[].title`	Short, human readable title of the validation performed. To determine if your skill is eligible for live skill update, look for `title` set to `Eligibility to update your live skill instantly`.	String
`result.validation[].description`	Human readable description of the validation performed. Might include instructions on how to address validation failures.	String
`result.validation[].category`	(Optional) Dot-delimited category name.	String
`result.validations[].status`	Status of the validation. Valid values: `SUCCESSFUL`, `FAILED`.	String
`result.validation[].importance`	Defines the importance of fixing the failure. Valid values: `REQUIRED`, `RECOMMENDED`.	String
`result.validation[].error`	(Optional) Included when an error occurs executing the validation.	Object
`result.validation[].error.code`	HTTP status code that reflects the error.	String
`result.validation[].error.message`	Human readable error message.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains status and results of the validation.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. 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 included token expired or isn't valid. Or, you don'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.

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

Copied to clipboard.

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
`skillId`	Path	Identifies the skill. Valid values: 1–255 characters.	String	Yes
`stage`	Path	Indicates stage of the skill. Valid values: `development`, `live`.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "locales": ["en-US"]
}

Request body properties

Property	Description	Type	Required
`locales[]`	List of locales in which to validate the skill.	Array of string	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
`id`	Identifies the validation request.	String
`status`	Current state of the validation request. Valid values: `IN_PROGRESS`, `SUCCESSFUL`, `FAILED`. 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`	Result of the validation.	Object
`result.validations[]`	List of validations executed against the skill.	Array of objects
`result.validations[].locale`	Locale of the validation.	String
`result.validations[].title`	Short, human readable title of the validation performed. To determine if your skill is eligible for live skill update, look for `title` set to `Eligibility to update your live skill instantly`.	String
`result.validation[].description`	Human readable description of the validation performed. Might include instructions on how to address validation failures.	String
`result.validation[].category`	(Optional) Dot-delimited category name.	String
`result.validations[].status`	Status of the validation. Valid values: `SUCCESSFUL`, `FAILED`.	String
`result.validation[].importance`	Defines the importance of fixing the failure. Valid values: `REQUIRED`, `RECOMMENDED`.	String
`result.validation[].error`	(Optional) Included when an error occurs executing the validation.	Object
`result.validation[].error.code`	HTTP status code that reflects the error.	String
`result.validation[].error.message`	Human readable error message.	String

HTTP status codes

Status	Description
`202 Accepted`	Request to submit skill for validation succeeded. The response body contains the validation ID and status, along with the validation results, if any.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. 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 included token expired or isn't valid. Or, you don'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.

Object definitions

The Skill Validation API defines the following objects.

Locale values

The following table shows valid values for the locale property.

Locale code	Language
`ar-SA`	Arabic (SA)
`de-DE`	German (DE)
`en-AU`	English (AU)
`en-CA`	English (CA)
`en-GB`	English (UK)
`en-IN`	English (IN)
`en-US`	English (US)
`es-ES`	Spanish (ES)
`es-MX`	Spanish (MX)
`es-US`	Spanish (US)
`fr-CA`	French (CA)
`fr-FR`	French (FR)
`hi-IN`	Hindi (IN)
`it-IT`	Italian (IT)
`ja-JP`	Japanese (JP)
`pt-BR`	Portuguese (BR)

Was this page helpful?

Provide feedback

Last updated: Sep 08, 2023

Skill Validation REST API Reference

API endpoint

Authentication

Operations

Get validation status

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Submit for validation

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Object definitions

Locale values

Related topics

Was this page helpful?