Skill Certification and Publication
- Submit a skill for certification and optional publication
- Publish a certified skill
- Get current publishing details for a certified skill
- 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
Use the following API operations in the Skill Management API (SMAPI) to manage the certification and publication of an Alexa skill. You can decide to separate the certification and publication operations, or you can do both in a single combined operation. If you separate the operations, you can control the release date of your skill in the Alexa Skill Store.
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.
- TOC
Submit a skill for certification and optional publication
Submit a skill for certification, and optionally for publication in the same operation.
Request
POST /v1/skills/{skillId}/submit
Parameters
Field | Description | Parameter type | Required? |
---|---|---|---|
skillId |
Unique identifier of skill. | Path | Yes |
Request body
Optional. If omitted, or if you use AUTO_PUBLISHING
for the publicationMethod
, the submission for certification and publication operations are combined. If you use MANUAL_PUBLISHING
, you can publish the skill in a separate operation after the skill has been certified, with publish-skill.
{
"publicationMethod": "MANUAL_PUBLISHING"
}
Field | Description | Parameter type | Required? |
---|---|---|---|
publicationMethod |
One of: AUTO_PUBLISHING , MANUAL_PUBLISHING |
String | No |
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
Publish a certified skill
Publish a certified skill. You can set a date for publication, or initiate publishing immediately.
Each API request must have an Accept-Language header whose value is either en-US
or ja-JP
, to localize the response from the operation.
Request
POST /v1/skills/{skillId}/publications
Parameters
Field | Description | Parameter type | Required? |
---|---|---|---|
skillId |
Unique identifier of skill. | Path | Yes |
Request body
Optional. If not specified, publishing is initiated immediately. Otherwise, you can specify a date for publication, no more than six months in the future.
{
"publishesAt": "2019-11-01T00:38:29.708Z"
}
Field | Description | Parameter type | Required? |
---|---|---|---|
publishesAt |
Specify the time in UTC format. | String | No |
Response
HTTP/1.1 202 Accepted
Response body
The response body returns the publication date and the current status of the publication. Possible status values are: IN_PROGRESS
, SUCCEEDED
, FAILED
, CANCELLED
, SCHEDULED
.
{
"publishesAt": "2019-11-01T01:51:23.113Z",
"status": "IN_PROGRESS"
}
Exceptions
HTTP/1.1 400 Invalid
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 current publishing details for a certified skill
Get current publishing details for a certified skill, in particular the date of publication and the current publication status.
Each API request must have an Accept-Language header whose value is either en-US
or ja-JP
, to localize the response from the operation.
Request
GET /v1/skills/{skillId}/publications/~latest
Parameters
Field | Description | Parameter type | Required? |
---|---|---|---|
skillId |
Unique identifier of skill. | Path | Yes |
Request body
None.
Response
HTTP/1.1 200 Accepted
Response body
The response body returns the publication date and the current status of the publication. Possible status values are: IN_PROGRESS
, SUCCEEDED
, FAILED
, CANCELLED
, NOT_SCHEDULED
, SCHEDULED
.
{
"publishesAt": "2019-11-01T02:03:07.023Z",
"status": "IN_PROGRESS"
}
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
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