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 /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.

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.

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?

Last updated: Jan 26, 2024