Skill Certification REST API Reference

Use the Skill Certification REST API to manage the certification of your skill. Optionally, you can certify and publish your skill in a single command. For details about publishing your skill, see Skill Publication REST API.

API endpoint

The endpoint of the Skill Certification 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 Certification API includes the following operations.

Operation HTTP method and URI

Get certifications list

GET /v1/skills/{skillId}/certifications?maxResults={maxResults}&nextToken={nextToken}

Get certification review

GET /v1/skills/{skillId}/certifications/{certificationId}

Get skill versions

GET /v1/skills/{skillId}/versions?maxResults={maxResults}&nextToken={nextToken}

Submit for certification

POST /v1/skills/{skillId}/submit

Withdraw certification

POST /v1/skills/{skillId}/withdraw

Get certifications list

Get a summary of ongoing and completed certification reviews for the specified skill.

Request

To get the review list, you make a GET request to the certifications resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/certifications?maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/hal+json

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–50. Default: 50.

Integer

No

nextToken

Query

Token from the previous response.
Include if iterating over a paginated response.

String

No

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 certification reviews for the specified skill. 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

{
    "_links": {
        "self": {
            "href": "amzn1.ask.skill.1"
        },
        "next": {
            "href": "string"
        }
    },
    "isTruncated": false,
    "totalCount": 1,
    "items": [{
        "id": "certification ID",
        "status": "IN_PROGRESS",
        "skillSubmissionTimestamp": "2019-01-06T05:26:02.430Z",
        "reviewTrackingInfo": {
            "estimatedCompletionTimestamp": "2019-01-06T05:26:02.430Z",
            "actualCompletionTimestamp": "2019-01-06T05:26:02.430Z",
            "lastUpdated": "2019-01-06T05:26:02.430Z"
        }
    }]
}

Response body properties

Property Description Type

_links

Links for item navigation.
Defined in JSON Hypertext Application Language specification.

_links object

isTruncated

Indicates whether there are more items to return. If set to true, include nextToken a subsequent request. Or, you can get the remaining items by using the next link in the _links object.

Boolean

nextToken

(Optional) Included when the response is truncated. Use this value in a subsequent request.

String

totalCount

Number of items that satisfy the request. This value might be higher than the number of items returned.

Type

items[]

List of certification reviews.

Array of objects

items[].id

Unique identifier for the certification.

String

items[].status

Status of the certification review.
Valid values: IN_PROGRESS, SUCCEEDED, FAILED, CANCELLED.

String

items[].skillSubmissionTimestamp

Date and time when the skill was submitted for certification.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

items[].reviewTrackingInfo

Summary of the certification review.

Object

items[].reviewTrackingInfo.estimatedCompletionTimestamp

Estimated completion date and time of the certification.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

items[].reviewTrackingInfo.actualCompletionTimestamp

For completed certifications, date and time of completion.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

items[].reviewTrackingInfo.lastUpdated

Date and time of the most recent update.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

HTTP status codes

Status Description

200 OK

Response body contains an array of ongoing and completed certification reviews.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
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 token is invalid or expired. Or, the client doesn'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.

Get certification review

Get the certification tracking information for the specified skill under review.

Request

To get the tracking information, you make a GET request to the certifications resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/certifications/{certificationId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Accept-Language: {language}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

certificationId

Path

Identifies the certification review. To get the most recent review, use ~mostRecent. Otherwise, to get a specific certification ID, first use Get certifications list.

String

Yes

access token

Header

LWA token.

String

Yes

language

Header

To receive a localized response, set the language.
Valid values: en-US, ja-JP.

String

No

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 the details of the specified certification. 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": "certification ID",
    "status": "IN_PROGRESS",
    "skillSubmissionTimestamp": "2019-01-06T21:54:09.730Z",
    "reviewTrackingInfo": {
        "estimatedCompletionTimestamp": "2019-01-06T21:54:09.730Z",
        "actualCompletionTimestamp": "2019-01-06T21:54:09.730Z",
        "lastUpdated": "2019-01-06T21:54:09.730Z",
        "estimationUpdates": [{
            "originalEstimatedCompletionTimestamp": "2019-01-06T21:54:09.730Z",
            "revisedEstimatedCompletionTimestamp": "2019-01-06T21:54:09.730Z",
            "reason": "reason description"
        }]
    },
    "result": {
        "distributionInfo": {
            "publishedCountries": [
                "CA"
            ],
            "publicationFailures": [{
                "reason": "reason description",
                "countries": [
                    "US"
                ]
            }]
        }
    }
}

Response body properties

Property Description Type

id

Unique identifier for the certification.

String

status

Status of the certification review.
Valid values: IN_PROGRESS, SUCCEEDED, FAILED, CANCELLED.

String

skillSubmissionTimestamp

Date and time when the skill was submitted for certification.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

reviewTrackingInfo

Summary of the certification review.

Object

reviewTrackingInfo.estimatedCompletionTimestamp

Estimated completion date and time of the certification.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

reviewTrackingInfo.actualCompletionTimestamp

For completed certifications, date and time of completion.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

reviewTrackingInfo.lastUpdated

Date and time of the most recent update.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

reviewTrackingInfo.estimationUpdates[]

List of updates to estimated completion time for the certification review.

Array of objects

reviewTrackingInfo.estimationUpdates[].originalEstimatedCompletionTimestamp

Date and time of the original completion estimate.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

reviewTrackingInfo.estimationUpdates[].revisedEstimatedCompletionTimestamp

Up-to-date estimate for certification completion.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

reviewTrackingInfo.estimationUpdates[].reason

Reason for update to the original estimate.

String

result

For status = SUCCEEDED, outcome of the certification review.

Object

result.distributionInfo

Identifies where Amazon distributed the skill.

Object

result.distributionInfo.publishedCountries[]

Countries where Amazon published the skill.
Defined in ISO 3166-1 alpha-2 format, two letter country codes.

Array of string

result.distributionInfo.publicationFailures[]

For status = SUCCEEDED, identifies where Amazon distributed the skill.

Array of object

result.distributionInfo.publicationFailures[].reason

Reason why Amazon didn't publish the skill in this country.

String

result.distributionInfo.publicationFailures[].countries[]

Countries where Amazon didn't publish the skill.
Defined in ISO 3166-1 alpha-2 format, two letter country codes.

Array of string

HTTP status codes

Status Description

200 OK

Response body contains the details of the specified certification.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
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 token is invalid or expired. Or, the client doesn'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.

Get skill versions

Get a list of versions for the specified skill.

Request

To get skill versions, you make a GET request to the versions resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/versions?maxResults={maxResults}&nextToken={nextToken}
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

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–50. Default: 50.

Integer

No

nextToken

Query

Token from the previous response.
Include if iterating over a paginated response.

String

No

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The response has no body.

Response

A successful response returns HTTP 200 OK, along with a list of versions for the specified skill. Depending on the stage of the skill, the list might include up to three versions: DEVELOPMENT, CERTIFIED, LIVE. 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

{
    "_links": {
        "self": {
            "href": "amzn1.ask.skill.1"
        }
    },
    "isTruncated": false,
    "skillVersions": [{
            "version": "2",
            "creationTime": "2019-01-07T21:54:09.730Z",
            "message": "Updating the skill icon, and description message.",
            "submissions": [{
                "status": "LIVE",
                "submissionTime": "2019-01-07T21:54:09.730Z"
            }]
        },
        {
            "version": "1",
            "creationTime": "2019-01-06T21:54:09.730Z",
            "message": "Initial submission, excited to try this new feature.",
            "submissions": [{
                "status": "CERTIFIED",
                "submissionTime": "2019-01-06T21:54:09.730Z"
            }]
        }
    ]
}

Response body properties

Property Description Type

_links

Links for item navigation.
Defined in JSON Hypertext Application Language specification.

_links object

isTruncated

Indicates whether there are more items to return. If set to true, include nextToken a subsequent request. Or, you can get the remaining items by using the next link in the _links object.

Boolean

nextToken

(Optional) Included when the response is truncated. Use this value in a subsequent request.

String

skillVersion[]

List of versions.

Array of objects

skillVersion[].version

Version number of the skill.

String

skillVersion[].creationTime

List of versions.

String

skillVersion[].message

Custom message for this skill version.
Maximum length: 300 characters.

String

skillVersion[].submissions[]

List of submissions for the version.

Array of objects

skillVersion[].submissions[].status

List of versions.
Valid values: LIVE, CERTIFIED, IN_REVIEW, FAILED_CERTIFICATION, HIDDEN, REMOVED, WITHDRAWN_FROM_CERTIFICATION

String

skillVersion[].submissions[].submissionTime

Data and time of submission of this version.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

HTTP status codes

Status Description

200 OK

Response body contains list of skill versions.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
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 token is invalid or expired. Or, the client doesn'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 certification

Submit the specified skill for certification, or submit for certification and publishing.

Request

To submit for certification, you make a POST request to the submit resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/submit
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

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
  "publicationMethod": "MANUAL_PUBLISHING",
  "versionMessage": "Version 1"
}

Request body properties

Property Description Type Required

publicationMethod

Indicates whether to submit the skill for certification only, or to submit for certification and publication. Default: AUTO_PUBLISHING.
Valid values: MANUAL_PUBLISHING, AUTO_PUBLISHING.

String

No

versionMessage

Description of the skill version.
Maximum length: 300 characters.

String

No

Response

A successful response returns HTTP 202 Accepted, along with a Location in the header that contains a path to the certification. 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 response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

202 Accepted

Skill submitted for certification successfully.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
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 token is invalid or expired. Or, the client doesn'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.

Withdraw certification

Withdraw the specified skill from certification.

Request

To withdraw a certification, you make a POST request to the withdraw resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/withdraw
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

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
  "reason": "DISCOVERED_ISSUE",
  "message": "Issue found in testing account linking"
}

Request body properties

Property Description Type Required

reason

Indicates why you want to withdraw the skill from certification. Default: AUTO_PUBLISHING.
Valid values: TEST_SKILL, MORE_FEATURES, DISCOVERED_ISSUE, NOT_RECEIVED_CERTIFICATION_FEEDBACK, NOT_INTEND_TO_PUBLISH, OTHER.

String

Yes

message

Description of the reason that you want to withdraw the skill from certification. Required when reason set to OTHER.
Maximum length: 300 characters.

String

No

Response

A successful response returns HTTP 202 Accepted. 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 response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

202 Accepted

Skill withdrawn request submitted successfully.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
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 token is invalid or expired. Or, the client doesn'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.