Skill Package API Reference
You can use the Skill Package API to interact with your skill as a single package, rather than by component.
- Skill package overview
- Use the skill package
- Skill package API endpoint
- APIs for importing and exporting the skill package
- Related topics
Skill package overview
A skill package must contain the following component:
- Skill manifest – The skill manifest contains metadata about the skill and configuration, including the display name, skill capabilities (video, smart home, custom), and endpoint for the skill service code (whether AWS Lambda or a separate web endpoint). The name of the skill manifest file is skill.json. Every skill must have a manifest.
The following components of a skill package are optional:
- Image assets – These images are associated with your skill, appearing as icons in the Alexa Skills Store, or your in-skill products.
- In-skill products (ISPs) – These define the in-skill products that users can purchase in your skill. They specify the type of purchase and other details such as pricing.
- Interaction models – These define the voice user interface for your skill which includes the invocation name, intents, slots, and so forth. Only custom skills include interaction models, with one model for each locale that the skill supports. The name of the interaction model is <locale>.json, for example en-US.json. In the skill package format, the interaction models must be in a folder named custom, which itself must be in a folder named interactionModels.
Your skill might also contain account linking information, which is currently not supported by the Skill Package API. You can still use the Skill Package API, but you also have to use SMAPI to manage account linking.
If you interact with your skill only through the Alexa Skills Kit developer console, these components still exist behind the scenes. If you interact with your skill through the Alexa Skills Kit Command Line Interface (ASK CLI) or the Skill Management API (SMAPI), you see these components as individual files. A skill package combines these components into a single file so that you can work with them as a unit.
Skill package format
A skill package file combines all the skill components into a zipped file with a .zip extension. 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
To create and import a skill by using the skill package format, take the following steps.
To create and import a skill by using the skill package format
- Organize your skill components as shown in the preceding diagram, and then zip the top-level folder.
Note: You can optionally skip the following two steps by uploading your skill package to a publicly-accessible URL on the internet.
- Create an upload URL.
- Use the URL that you created in the previous step to upload the .zip file to Amazon S3.
- After you upload the skill package, either to S3 or your own URL, you can:
You can also update an existing skill by exporting it in the skill package format, editing it locally, and then using the preceding steps to upload and import it.
Use the skill package
The following sections contain information about how to avoid overwriting an existing skill, and how to manage in-skill products.
Use eTag
to avoid overwriting a skill package
When you use the Skill Package API to import a skill package to an existing skill, the imported skill package overwrites the existing skill's components. 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:
- The graphic designer and the developer each use the Skill Package API to export separate copies of the skill to their own laptops.
- The graphic designer adds new images to the skill package, and then uses the Skill Package API to upload and import the skill package to the existing skill.
- The developer updates the skill's interaction model, adds a new ISP, and then uses the 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, you can use the skill package's eTag
. You can think of an eTag
as an opaque version identifier for a skill package. You get an eTag
in the body of the response when you call the Skill Package API for one of the following operations:
You can include an eTag
value in the If-Match
HTTP request header when you import a package for an existing skill.
The following example shows how eTags
prevent overwriting:
- The graphic designer and the developer each use the Skill Package API to export separate copies of the skill to their own laptops. They each save the
eTag
value in addition to the skill package .zip file. - The graphic designer adds new images to the skill package, and then uses the Skill Package API to upload and import the skill package to the existing skill. The graphic designer's import request includes the
If-Match
HTTP header with theeTag
value, which matches the server-sideeTag
value for the skill package. The import succeeds, which results in a neweTag
value for this latest version of the skill package. - The developer updates the skill's interaction model, adds a new ISP, and then uses the Skill Package API to upload and import the skill package to the existing skill. The developer's import request includes the
If-Match
HTTP header with theeTag
value, which does not match the server-sideeTag
value for the skill package, so the import request fails. - 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. - The developer compares their local changes to the latest version, and reconciles the differences.
- The developer uses the Skill Package API to upload and import the skill package to the existing skill. The developer's import request includes the
If-Match
HTTP header with theeTag
value, which now matches the server-sideeTag
value for the skill package, so the import request succeeds.
Manage in-skill products in a skill package
You can manage in-skill products by including them in your skill package. For details about ISPs, see In-Skill Purchasing Overview and In-Skill Purchasing Schemas.
When your skill package contains in-skill products, those products associated with your skill are defined in the folder named, isps
. This folder contains one or more product definition files and a file named, isps.json
, that describes the products to link to your skill.
The following example shows a skill package with two products named, product1.json
and product2.json
.
SkillPackageName.zip
├── assets
├── interactionModels
├── isps
│ ├── isps.json
│ ├── product1.json
│ └── exampleDirectory
│ └── product2.json
└── skill.json
The isps.json
file has two sections: the products to create or update and existing products to associate with the skill. Each product definition file that you create follows the ISP JSON schema format.
The following example shows the contents of the isps.json
file with two new products to create and two existing products to associate with the skill.
{
"isps": {
"Unique product name 1": {
"path": "file://isps/isp1.json"
},
"Unique product name 2": {
"path": "file://isps/exampleDirectory/isp2.json"
}
},
"associations": [
"amzn1.adg.UUID3",
"amzn1.adg.UUID4"
]
}
The following table describes each object in the isps.json
file:
Property | Description |
---|---|
|
List of one or more products, each with a unique reference name, that you want to create or update. Each product contains a |
|
List of existing products to link to your skill. Each product is identified with a product ID that Amazon generated when it created the product. To get the product ID, use the In-Skill Product Management API, ASK CLI or the developer console. |
isps.json
file. If you change the name, you have two products: one with the new name and one with the old name.The existence of products in the isps.json
file determines how products are associated with your skill.
- When the
isps.json
file containsisps
orassociations
that are new, the products are created and linked accordingly. - When the
isps.json
file contains updates toisps
that previously existed in the skill package, the product definitions are updated. - When the
isps.json
file omitsassociations
that previously existed in the skill package, the products still exist but are no longer linked to your skill.
If you don't want the Skill Package API to take these actions, you can omit the isps
folder from the skill package, and continue to manage ISPs separately.
Skill package API endpoint
The endpoint for the Skill Package API is https://api.amazonalexa.com
. Each API request must have an Authorization
header whose value is the access token retrieved from Login with Amazon. For details about how to get the access token, see Get an Access Token for SMAPI.
APIs for importing and exporting the skill package
The following table lists the APIs that relate to importing and exporting skill packages.
Description | HTTP method and path |
---|---|
POST /v1/skills/uploads |
|
POST /v1/skills/imports |
|
POST /v1/skills/{skillId}/imports |
|
GET /v1/skills/imports/{importId} |
|
POST /v1/skills/{skillId}/stages/{stage}/exports |
|
GET /v1/skills/exports/{exportId} |
Create a new upload URL
Use this API to create a presigned upload URL that you can use to upload a skill package to Amazon S3. You can upload a skill package to S3 by using one of the following methods:
- Send an HTTP
PUT
request to the presigned URL that you receive in the response to this API. - Use an AWS SDK. For details, see Uploading Objects Using Presigned URLs in the Amazon S3 documentation.
You can also bypass this API entirely by uploading your skill package to a publicly accessible URL on the internet.
After you upload the skill package, either to S3 or your own URL, you can do one of the following operations:
- Create a new skill from the uploaded skill package.
- Import the uploaded skill package to an existing skill.
Request
POST /v1/skills/uploads
Response
A successful request returns 201 Created
.
Response body structure
{
"uploadUrl": "string",
"expiresAt": "2018-10-11T19:28:34.525Z"
}
Response fields
Field | Location | Description | Type |
---|---|---|---|
|
Response body |
A URL you can use to upload a skill package. |
String |
|
Response body |
The expiration time of the URL. |
String |
Errors
Code | Description |
---|---|
401 |
The authorization token is invalid, expired, or doesn't have access to the resource. |
429 |
Exceeds the permitted request limit. |
500 |
Internal Server Error. |
503 |
Service Unavailable. |
Create a new skill package
Use this API to submit a request to create a new skill package.
Request
POST /v1/skills/imports
Request body structure
{
"vendorId": "string",
"location": "string"
}
Request parameters
Field | Location | Description | Type | Required |
---|---|---|---|---|
|
Request body |
The ID of the vendor that owns the skill. |
String |
No |
|
Request body |
The URL for the skill package. |
String |
Yes |
Response
A successful request returns 202 Accepted
.
The value of the Location
header is a relative URL that you use to track the status of the import request.
Errors
Code | Description |
---|---|
400 |
Server cannot process the request due to a client error. |
401 |
The authorization token is invalid, expired, or doesn't have access to the resource. |
413 |
Payload Too Large. |
429 |
Exceeds the permitted request limit. |
500 |
Internal Server Error. |
503 |
Service Unavailable. |
Import a package for an existing skill
This API submits a request to import a zipped package file for an existing skill specified by skillId
.
Request
POST /v1/skills/{skillId}/imports
Request body structure
{
"location": "string"
}
To avoid overwriting a previous update to the skill, you can optionally include the If-Match
HTTP header with an eTag
value. For details, see Use eTag
to avoid overwriting a skill package.
Request parameters
Field | Location | Description | Type | Required |
---|---|---|---|---|
|
Request path |
The ID of the skill for which to import the skill package. |
String |
Yes |
|
Request body |
The presigned URL that you previously obtained, or a publicly accessible URL from which the zipped skill package can be downloaded. For details, see Create upload URL. |
String |
Yes |
Response
A successful request returns 202 Accepted
.
The value of the Location
header is the URL that you specified in the request.
Errors
Code | Description |
---|---|
400 |
Server cannot process the request due to a client error. |
401 |
The authorization token is invalid, expired, or doesn't have access to the resource. |
409 |
Conflict. |
413 |
Payload Too Large. |
429 |
Exceeds the permitted request limit. |
500 |
Internal Server Error. |
503 |
Service Unavailable. |
Get the status for a specified importId
Gets the status for the specified importId
.
Request
GET /v1/skills/imports/{importId}
Request parameters
Field | Location | Description | Type | Required |
---|---|---|---|---|
|
Request path |
The skill package import for which to get the status. |
String |
Yes |
Response
A successful request returns 200 OK
.
Response body structure
{
"status": "enum",
"errors": [
{
"code": "string",
"message": "string"
}
],
"warnings": [
{
"code": "string",
"message": "string"
}
],
"skill": {
"skillId": "string",
"eTag": "string",
"resources": [
{
"name": "string",
"status": "enum",
"action": "enum",
"errors": [
{
"code": "string",
"message": "string"
}
],
"info": [
{
"message": "string"
}
],
"warnings": [
{
"code": "string",
"message": "string"
}
]
}
]
}
}
Response fields
Field | Location | Description | Type |
---|---|---|---|
|
Response body |
The
|
Enum |
|
Response body |
Errors related to the last modification request of the skill package. |
Array |
|
Response body |
Warnings related to the last modification request of the skill package. |
Array |
|
Response body |
The ID of the skill. |
String |
|
Response body |
An opaque version identifier for the skill package. For details, see Use eTag to avoid overwriting a skill package. |
String |
|
Response body |
List of skill resources. The
The
|
Array |
Errors
Code | Description |
---|---|
401 |
The authorization token is invalid, expired, or doesn't have access to the resource. |
404 |
The resource being requested is not found. |
429 |
Exceeds the permitted request limit. |
500 |
Internal Server Error. |
503 |
Service Unavailable. |
Create an export request for an existing skill
Creates an export request for an existing skill. You can then get the status of the export request, including a URL that you can use to download the exported skill.
Request
POST /v1/skills/{skillId}/stages/{stage}/exports
Request parameters
Field | Location | Description | Type | Required |
---|---|---|---|---|
|
Request path |
The ID of the skill for which to export the skill package. |
String |
Yes |
|
Request path |
The |
String |
Yes |
Response
A successful request returns 202 Accepted
.
The response has no body. To get the status of the export request, including a URL that you can use to download the exported skill, send a GET
request to the path in the response's Location
header. For details, see Get the status for an export request.
Errors
Code | Description |
---|---|
401 |
The authorization token is invalid, expired, or doesn't have access to the resource. |
404 |
The resource being requested is not found. |
409 |
The request could not be completed due to a conflict with the current state of the target resource. |
429 |
Exceeds the permitted request limit. |
500 |
Internal Server Error. |
503 |
Service Unavailable. |
Get the status for an export request
Gets the status of an export request that you created previously. When the status of the export request is SUCCEEDED
, the response contains a URL that you can use to download a zip archive of the exported skill.
Send a GET
request to the path contained in the Location
header of the response to a previous export request. The exportId
is in this path, so you don't need to do anything extra to obtain it.
Request
GET /v1/skills/exports/{exportId}
Request parameters
Field | Location | Description | Type | Required |
---|---|---|---|---|
|
Request path |
The skill package export request for which you want to get the status. |
String |
Yes |
Response
A successful request returns 200 OK
.
Response body structure
{
"skill": {
"expiresAt": "1550521786056",
"location": "URL to download the exported skill",
"eTag": "string"
},
"status": "SUCCEEDED"
}
Response fields
Field | Location | Description | Type |
---|---|---|---|
|
Response body |
The expiration time of the URL. |
String |
|
Response body |
When the |
String |
|
Response body |
An opaque version identifier for the skill package. For details, see Use |
String |
|
Response body |
The
|
Enum |
Errors
Code | Description |
---|---|
401 |
The authorization token is invalid, expired, or doesn't have access to the resource. |
404 |
The resource being requested is not found. |
429 |
Exceeds the permitted request limit. |
500 |
Internal Server Error. |
503 |
Service Unavailable. |