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

Copied to clipboard.

POST /v1/skills/imports
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "location": "https://example.com/skillPackage",
    "vendorId": "your.vendor.id.1"
}

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 aren't valid.
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 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

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:

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

Copied to clipboard.

POST /v1/skills/uploads
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

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

{
  "uploadUrl": "https://example.com/skillPackage",
  "expiresAt": "2018-10-11T19:28:34.525Z"
}

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 aren't valid.
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 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

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

Copied to clipboard.

POST /v1/skills/{skillId}/stages/{stage}/exports
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

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 aren't valid.
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 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

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

Copied to clipboard.

POST /v1/skills/{skillId}/imports
Host: api.amazonalexa.com
Content-Type: application/json
If-Match: {eTag}
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

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

Copied to clipboard.

{
    "location": "https://example.com/skillPackage"
}

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 aren't valid.
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 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

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

Copied to clipboard.

GET /v1/skills/exports/{exportId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

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

{
    "status": "SUCCEEDED",
    "skill": {
        "expiresAt": "1550521786056",
        "location": "https://example.com/skillPackage",
        "eTag": "token.1"
  }
}

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 aren't valid.
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 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

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

Copied to clipboard.

GET /v1/skills/import/{importId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

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

{
    "status": "SUCCEEDED",
    "skill": {
        "expiresAt": "1550521786056",
        "location": "https://example.com/skillPackage",
        "eTag": "token.1"
  }
}

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 aren't valid.
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 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

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.

Was this page helpful?

Last updated: Nov 17, 2023