Skill Certification and Publishing
Use the following API operations in the Skill Management API (SMAPI) to manage the certification and publishing of an Alexa skill.
The SMAPI endpoint is https://api.amazonalexa.com. Each API request must have an Authorization header whose value is the access token retrieved from Login with Amazon.
- Submit a skill for certification and publishing
- Get a list of certification reviews for a skill
- Get details about a specific certification review
- Withdraw a skill from certification
- Hide or remove a live skill
Submit a skill for certification and publishing
Submit a skill for certification and potential publication.
Request
POST /v1/skills/{skillId}/submit
Parameters
| Field | Description | Parameter type | Required? |
|---|---|---|---|
skillId |
Unique identifier of skill. | Path | Yes |
Response
HTTP/1.1 202 Accepted
Headers
Location: "<relative path to track submission status>"
Exceptions
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Get a list of certification reviews for a skill
Get a list of all completed and ongoing certification reviews for a skill.
Request
GET /v1/skills/{skillId}/certifications
Parameters
| Field | Description | Parameter type | Required? |
|---|---|---|---|
skillId
|
Unique identifier of skill. | Path | Yes |
nextToken
|
Use this parameter to get more certification reviews, after you receive a response with truncated results. Set it to the value of nextToken from the truncated response you just received.
|
Query | No |
maxResults
|
The maximum number of items to return in the response. When you don't include this parameter, the default maximum is 50. When you include this parameter, the response might contain fewer items than the value you specify, but will never contain more. You should not specify a value higher than 50. | Query | No |
Response
HTTP/1.1 200 OK
Response body structure (JSON)
{
"_links": {
"self": {
"href": "string"
},
"next": {
"href": "string"
}
},
"isTruncated": false,
"nextToken": "string",
"totalCount": 1,
"items": [
{
"id": "string",
"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 elements
| Field | Description | Parameter type |
|---|---|---|
_links
|
Links for API navigation. The structure of this field is defined in the JSON Hypertext Application Language specification. |
_links object (spec)
|
isTruncated
|
A flag that indicates whether there are more items in the list than those returned in the response. When this value is true, the list in this response is truncated. To get more items, pass the value of the nextToken field to the nextToken parameter in a subsequent request.
|
Boolean |
nextToken
|
When isTruncated is true, this element is present and contains the value to use for the nextToken parameter in a subsequent request.
|
String |
totalCount
|
The total number of items that satisfy the request. This number might be higher than the number of items returned in this response. | Integer |
items object
| Field | Description | Parameter type |
|---|---|---|
id
|
Unique identifier for the certification review item. | String |
status
|
Status of the certification review. Status is one of IN_PROGRESS, SUCCEEDED, FAILED, or CANCELLED.
|
String |
skillSubmissionTimestamp
|
Date and time when the skill was submitted for certification. | Date and time stamp in ISO 8601 format |
reviewTrackingInfo object
| Field | Description | Parameter type |
|---|---|---|
estimatedCompletionTimestamp
|
Estimated date and time when the certification review will be complete. | Date and time stamp in ISO 8601 format |
actualCompletionTimestamp
|
Date and time when the certification review was completed. | Date and time stamp in ISO 8601 format |
lastUpdated
|
Date and time of the most recent update to the reviewTrackingInfo values.
|
Date and time stamp in ISO 8601 format |
Exceptions
HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
Get details about a specific certification review
Get the details about a specific certification review for a skill.
A request for an ongoing certification review will always return a response, but requests for old certifications might not. When the details about an old certification are not available, you receive an HTTP 404 Not Found response.
Request
GET /v1/skills/{skillId}/certifications/{certificationId}
Request Headers
You can optionally send the Accept-Language header to receive a localized response. You can set the header's value to en-US or ja-JP.
Parameters
| Field | Description | Parameter type | Required? |
|---|---|---|---|
skillId
|
Unique identifier of skill. | Path | Yes |
certificationId
|
Unique identifier of the certification review item to get. To get the most recent certification review item, use a value of ~mostRecent. To get a certification review item which is not the most recent, first get a list of certification reviews for the skill, then use the ID of the certification review item you want to get.
|
Path | Yes |
Response
HTTP/1.1 200 OK
Response body structure (JSON)
{
"id": "string",
"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": "string"
}
]
},
"result": {
"distributionInfo": {
"publishedCountries": [
"string"
],
"publicationFailures": [
{
"reason": "string",
"countries": [
"string"
]
}
]
}
}
}
Response body elements
| Field | Description | Parameter type |
|---|---|---|
id
|
Unique identifier for the certification review item. | String |
status
|
Status of the certification review. Status is one of IN_PROGRESS, SUCCEEDED, FAILED, or CANCELLED.
|
String |
skillSubmissionTimestamp
|
Date and time when the skill was submitted for certification. | Date and time stamp in ISO 8601 format |
reviewTrackingInfo object
| Field | Description | Parameter type |
|---|---|---|
estimatedCompletionTimestamp
|
Estimated date and time when the certification review will be complete. | Date and time stamp in ISO 8601 format |
actualCompletionTimestamp
|
Date and time when the certification review was completed. | Date and time stamp in ISO 8601 format |
lastUpdated
|
Date and time of the most recent update to the reviewTrackingInfo values.
|
Date and time stamp in ISO 8601 format |
estimationUpdates object
| Field | Description | Parameter type |
|---|---|---|
originalEstimatedCompletionTimestamp
|
Date and time of the original estimate for when the certification review will be complete. | Date and time stamp in ISO 8601 format |
revisedEstimatedCompletionTimestamp
|
Date and time of the up-to-date estimate for when the certification review will be complete. | Date and time stamp in ISO 8601 format |
reason
|
The reason why the original estimate was revised. | String |
distributionInfo object
| Field | Description | Parameter type |
|---|---|---|
publishedCountries
|
When the certification review is complete, contains a list of countries where the skill was published. Each country is specified as a two letter country code according to ISO 3166-1 alpha-2. | List of string |
publicationFailures
|
When the certification review is complete, contains a list of countries where the skill was not published, and the reason it was not published. Each country is specified as a two letter country code according to ISO 3166-1 alpha-2. |
List of reason and countries values (strings)
|
Exceptions
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
Withdraw a skill from certification
Withdraw a skill from the certification process.
Request
POST /v1/skills/{skillId}/withdraw
Body
{
"reason" : "OTHER",
"message" : "TEST SKILL"
}
Parameters
| Field | Description | Parameter type | Required? |
|---|---|---|---|
| skillId | Unique identifier of skill. | Path | Yes |
| reason | One of the following enum values indicating the reason for the withdrawal: TEST_SKILL, MORE_FEATURES, DISCOVERED_ISSUE, NOT_RECEIVED_CERTIFICATION_FEEDBACK, NOT_INTEND_TO_PUBLISH, OTHER |
Request body element | Yes |
| message | String that indicates why the skill is being withdrawn, when OTHER is specified as a reason. |
Request body element | Yes for reason OTHER, otherwise no. |
Response
HTTP/1.1 204 No Content
Exceptions
HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Hide or remove a live skill
Use this operation to unpublish (hide or remove) a published skill.
When you unpublish a skill, you choose whether to hide or remove the skill.
After you receive a response indicating that the operation succeeded, it might take a few days before the unpublishing is complete.
When a skill is hidden or removed, its stage value continues to be live. Thus, the live stage refers to skills that are currently available publicly in production, to hidden skills, and to removed skills.
To republish a skill after you unpublish it, you must resubmit the skill for certification.
Request
POST /v1/skills/{skillId}/unpublish
Body
{
"type": "string",
"reason": "string"
}
Parameters
| Field | Description | Parameter type | Required? |
|---|---|---|---|
| skillId | Unique identifier of the skill to unpublish. | Path | Yes |
| type | Specifies whether to hide or remove the skill. Valid values are HIDE and REMOVE. For more information, see Hide or Remove a Skill.
|
Request body element | Yes |
| reason | The reason for unpublishing the skill. Provide one of the following reasons:
|
Request body element | Yes |
Response
HTTP/1.1 202 Accepted
Body
{
"message": "string"
}
Parameters
| Field | Description | Parameter type |
|---|---|---|
| message | A message returned in the response. | Response body element |
Exceptions
HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable