Skill Publishing REST API Reference

Use the Skill Publishing REST API to manage the publication of your skill. Optionally, you can certify and publish your skill in a single request. For more details, see Submit for certification.

API endpoint

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

Operation HTTP method and URI

Get publication status

GET /v1/skills/{skillId}/publications/~latest

Submit for publication

POST /v1/skills/{skillId}/publications

Unpublish skill

POST /v1/skills/{skillId}/unpublish

Get publication status

Get the publication status of the specified skill.

Request

To get the publication status, you make a GET request to the publications resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/publications/~latest
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
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

access token

Header

LWA token.

String

Yes

language

Header

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

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 publication status. 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

{
  "publishesAt": "2019-11-01T02:03:07.023Z",
  "status": "IN_PROGRESS"
}

Response body properties

Property Description Type

publishesAtDate

Requested date for publication.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

status

Publication status.
Valid values: IN_PROGRESS, SUCCEEDED, FAILED, CANCELLED, SCHEDULED.

String

HTTP status codes

Status Description

200 OK

Response body contains the publication status.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code 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 included token expired or isn't valid. Or, you don'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

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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 publication

Submit the certified skill for publication. You can specify a publication date, or request to publish now. You can submit a skill for publishing or rollback, but not both at the same time.

Request

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

Request path and header example

Copied to clipboard.

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

{
    "publishesAt": "2019-11-01T00:38:29.708Z"
}

Request body properties

Property Description Type Required

publishesAtDate

Requested date for publication. Can be up to six months from the current date. If not included, the requested publication date is the current date.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

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

Request to submit skill for publication succeeded.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code 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 included token expired or isn't valid. Or, you don'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

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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.

Unpublish skill

Unpublish the specified skill so that users can't enable it. You can choose to allow the skill to remain active for current users or disable the skill for all users.

Request

To unpublish a skill, you make a POST request to the unpublish resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/unpublish
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
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

access token

Header

LWA token.

String

Yes

language

Header

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

Request body example

Copied to clipboard.

{
    "type": "HIDE",
    "reason": "Published by mistake"
}

Request body properties

Property Description Type Required

type

Specifies whether to disable the skill for all users, or for new users only.
For more details, see Hide or remove a skill.
Valid values: HIDE, REMOVE.

String

Yes

reason

Reason that you want to unpublish the skill.
Valid values:

  • Changing invocation name
  • Published by mistake
  • It takes time to maintain my skill
  • My infrastructure costs are too high
  • Technical issues
  • Other

String

Yes

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

Request to unpublish skill succeeded.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code 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 included token expired or isn't valid. Or, you don'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

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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.

Was this page helpful?

Last updated: Aug 01, 2024