Skill Package Management REST API Reference

---

Use the Skill Package Management REST API to import and export a skill package to a skill.

A skill package contains resources that describe the skill, such as the skill manifest. Based on the skill type, the skill package might contain other features, such as a custom voice interaction model, in-skill products, and image assets. For details about the layout of the skill package, see Skill package format.

To create and import a skill by using the skill package format, take the following steps.

1. Organize your skill components as shown in the skill package format diagram, and then zip the top-level folder.
2. Create an upload URL to Amazon S3.
   Or, if you upload your skill package to a publicly-accessible URL, skip this step.
3. Upload the zip file to Amazon S3 or to a publicly-accessible URL.
4. If you want to create a new skill and upload the skill package, call Create and import skill package.
5. If you want to import the uploaded skill package to an existing skill, call Import skill package.

To update an existing skill, call Export skill package, edit the skill package locally, and then import the updated package by using the preceding steps.

API endpoint

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

Operation	HTTP method and URI
Create and import skill package	POST /v1/skills/imports
Create upload URL	POST /v1/skills/uploads
Export skill package	POST /v1/skills/{skillId}/stages/{stage}/exports
Import skill package	POST /v1/skills/{skillId}/imports
Get export status	GET /v1/skills/exports/{exportId}
Get import status	GET /v1/skills/imports/{importId}

Create and import skill package

Create a new skill, and then import the skill package at the specified location to the new skill.

Request

To create a skill and import a skill package, you make a POST request to the imports resource.

Request path and header example

Request path and header parameters

Parameter	Located in	Description	Type	Required
access token	Header	LWA token.	String	Yes

Request body example

Request body properties

Property	Description	Type	Required
location	URL to the skill package location. Valid values: Amazon S3 URL or any publicly accessible URL.	String	Yes
vendorId	Identifies the vendor to which the skill belongs. For details about how to get your vendor ID, see Locate your customer ID and vendor ID.	String	No

Response

A successful response returns HTTP 202 Accepted, along with a Location in the header that contains the import ID. 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 create and import a new skill package succeeded. The response header contains a Location parameter that includes the importId string. For example: HTTP 202 Accepted Content-Type: application/json Location: /v1/skills/imports/{importId}
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.

Create upload URL

Create a presigned URL to Amazon S3. Then, upload your skill package zip file to S3 by using one of the following methods:

• Send an HTTP PUT request to the presigned URL that you receive in the response.
• Use an Amazon Web Services SDK. For more details, see Uploading Objects Using Presigned URLs.

If you upload your skill package to a publicly accessible URL, you can skip this API.

Request

To create a URL to S3, you make a POST request to the uploads resource.

Request path and header example

Request path and header parameters

Parameter	Located in	Description	Type	Required
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 201 Created. 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

Response body properties

Property	Description	Type
uploadUrl	Presigned URL to the S3 bucket location where you can upload your skill package.	String
expiresAt	Time the URL expires. Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.	String

HTTP status codes

Status	Description
201 Created	URL created 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.

Export skill package

Export an existing skill package to the specified location.

Request

To export a skill package, you make a POST request to the exports resource.

Request path and header example

Request path and header parameters

Parameter	Located in	Description	Type	Required
skillId	Path	Identifies the skill. Valid values: 1 – 255 characters.	String	Yes
stage	Path	Indicates stage of the skill. Valid values: development, live.	String	Yes
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 202 Accepted, along with a Location in the header that contains the export ID. 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 export a new skill package succeeded. The response header contains a Location parameter that includes the exportId string. For example: HTTP 202 Accepted Content-Type: application/json Location:/v1/skills/exports/{exportId}
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.

Import skill package

Import an existing skill package to the specified location.

Get the latest skill package

Sometimes, you might want to avoid overwriting an existing skill. For example, consider the following scenario in which a graphic designer and a developer work on the same skill simultaneously:

1. The graphic designer and the developer each use the Import skill package API to export separate copies of the skill to their own laptops.
2. The graphic designer adds new images to the skill package, and then uses the Import skill package API to upload and import the skill package to the existing skill.
3. The developer updates the interaction model, adds a new in-skill product, and then uses the Import skill package API to upload and import the skill package to the existing skill. This import overwrites the changes that the graphic designer made because the developer didn't have these changes in their local copy of the skill package.

To avoid this scenario, use the eTagopaque version identifier for a skill package. You get the latest eTag in the Get export status and Get import status responses.

The following example shows how eTag prevent overwriting:

1. The graphic designer and the developer each use the Export skill package API to export separate copies of the skill to their own laptops. They each save the eTag value and the skill package .zip file.
2. The graphic designer adds new images to the skill package, and then imports the skill package to the existing skill. The Import skill package request includes the eTag value in the HTTP header. The value matches the server-side eTag value for the skill package and the import request succeeds. The server creates a new eTag value for this latest version of the skill package.
3. The developer updates the custom interaction model, adds a new in-skill product, and then imports the updated skill package to the existing skill. The Import skill package request includes the eTag value in the HTTP header, which doesn't match the server-side eTag value for the skill package. As a result, the import request fails.
4. The developer exports the skill package to obtain the latest version and the corresponding eTag value. This version includes the previous updates that the graphic designer made.
5. The developer compares their local changes to the latest version, and then reconciles the differences.
6. The developer uses the imports the skill package to the existing skill. The Import skill package request includes the eTag value. The value matches the server-side eTag value for the skill package and the import request succeeds.

About in-skill product updates

The existence of in-skill products in the isps.json file determines how the import request associates products with your skill.

• When the isps.json file contains isps or associations that are new, the products are created and linked accordingly.
• When the isps.json file contains updates to isps that previously existed in the skill package, the product definitions are updated.
• When the isps.json file omits associations that existed in the skill package previously, the products still exist but are no longer linked to your skill.

If you don't want the import to take these actions, you can omit the isps folder from the skill package, and continue to manage in-skill products separately.

Request

To import a skill package, you make a POST request to the imports resource.

Request path and header example

Request path and header parameters

Parameter	Located in	Description	Type	Required
skillId	Path	Identifies the skill. Valid values: 1 – 255 characters.	String	Yes
etag	Header	Identifies the current version of the skill package. Include to avoid overwriting other imported changes after you last exported the skill package. Use Get export status or Get import status to get the current version.	String	No
access token	Header	LWA token.	String	Yes

Request body example

Request body properties

Property	Description	Type	Required
location	URL to the skill package location. Valid values: Amazon S3 URL from Create upload URL or any publicly accessible URL.	String	Yes

Response

A successful response returns HTTP 202 Accepted, along with a Location in the header that contains the import ID. 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 import a new skill package succeeded. The response header contains a Location parameter that includes the importId string. For example: HTTP 202 Accepted Content-Type: application/json Location: /v1/skills/imports/{importId}
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 export status

Get the status of a previously requested export. Use the exportId from the Location header of the Export skill package response.

Request

To get the export status, you make a GET request to the exports resource.

Request path and header example

Request path and header parameters

Parameter	Located in	Description	Type	Required
exportId	Path	Identifies the export request for which you want the status. Use the value returned in the Location header of the Export skill package response.	String	Yes
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 the export status and URL to the skill package zip file. 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

Response body properties

Property	Description	Type
status	Identifies the status of the export. Valid values: FAILED, IN_PROGRESS, SUCCEEDED.	String
skill	Description	Object
skill.expiresAt	Time in milliseconds until the URL expires.	String
skill.location	(Optional) URL to download the skill package zip file. Included when the status is SUCCEEDED.	String
skill.eTag	Opaque token that identifies the current version of the skill package.	String

HTTP status codes

Status	Description
200 OK	Response body contains the export status and URL to the skill package zip file.
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 import status

Get the status of a previously requested import. Use the importId from the Location header of the Import skill package response.

Request

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

Request path and header example

Request path and header parameters

Parameter	Located in	Description	Type	Required
importId	Path	Identifies the import request for which you want the status. Use the value returned in the Location header of the Export skill package response.	String	Yes
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 the import status and URL to the skill package zip file. 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

Response body properties

Property	Description	Type
status	Identifies the status of the import. Valid values: FAILED, IN_PROGRESS, SUCCEEDED.	String
skill	Description	Object
skill.expiresAt	Time in milliseconds until the URL expires.	String
skill.location	(Optional) URL to download the skill package zip file. Included when the status is SUCCEEDED.	String
skill.eTag	Opaque token that identifies the current version of the skill package.	String

HTTP status codes

Status	Description
200 OK	Response body contains the import status and URL to the skill package zip file.
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.

Skill package format

A skill package file combines all the skill components into a zipped file with a .zip extension. If you manage with your skill through the Alexa developer console, these components exist behind the scenes. If you interact with your skill through the Alexa Skills Kit Command Line Interface (ASK CLI) or the Skill Management REST APIs, you see these components as individual files.

The skill package has the following organization.

SkillPackageName.zip
├── assets
│   └── images
│       ├── en-US_largeIcon.png
│       ├── en-US_smallIcon.png
│       ├── isp1
│       │   ├── en-US_largeIcon.png
│       │   └── en-US_smallIcon.png
│       └── isp2
│           ├── en-US_largeIcon.png
│           └── en-US_smallIcon.png
├── interactionModels
│   └── custom
│       └── en-US.json
├── isps
│   ├── isps.json
│   ├── isp1.json
│   └── exampleDirectory
│       └── isp2.json
└── skill.json

Folder or file	Description	Required
skill.json	Skill manifest file that contains metadata about the skill, including the display name, skill capabilities (video, smart home, custom), and the endpoint for the skill service code, either AWS Lambda or a web endpoint. For details, see skill manifest schema.	Yes
assets	Folder that contains images associated with your skill, appearing as icons in the Alexa Skills Store or your in-skill products.	No
interactionModels/custom	Folder that contains definition for a custom voice interaction model, such as invocation name, intents, and slots. The folder contains one model file for each locale that the skill supports, such as en-US.json. Valid for custom skills only.	No
isps	Folder that contains the in-skill products that users can purchase in your skill. They specify the type of purchase and other details, such as pricing. You can add files that define in-skill products to link to the skill. For more details about the files in the isps folder, see Skill package file structure for in-skill products.	No

Your skill might also contain other folders, such as account linking. You can still import and export the skill package, but use the appropriate REST APIs to manage these files.

Related topics

• Create a Skill in the Alexa Developer Console
• Skill Manifest Schema
• Skill Manifest REST API Reference
• Resource Schema REST API Reference

---

Last updated: May 11, 2023