Thank you for your visit. This page is only available in English at this time.

Skill Certification and Publication

 

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:
  • Changing invocation name
  • Published by mistake
  • It takes time to maintain my skill
  • My infrastructure costs are too high
  • Technical issues
  • Other
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