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->importancevalidations->statusOverall Status
Recommended/RequiredSuccessfulSuccessful
RecommendedFailedSuccessful
RequiredFailedFailed

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"
}