Your Alexa Consoles
Sign In
Sign In

Skill Package API Reference

The Skill Package APIs can be used to interact with your skill as a single package, rather than by component.

The API's endpoint is https://api.amazonalexa.com. Each API request must have an Authorization header whose value should be the access token retrieved from Login with Amazon.

Skill package format

A skill consists of the following components, some of which are optional. If you interact with your skill only through the developer console, these components are still present behind the scenes. If you interact with your skill through ASK CLI or SMAPI, you will see these specific separate individual files.

  • Manifest: General metadata and configuration like the display name, skill capabilities (video, smart home, custom), and endpoints for skill service code (whether AWS Lambda or a separate web endpoint). The name of the skill manifest is skill.json. This manifest is a requirement for every skill.

The remaining components may or may not be present in your skill.

  • Image assets like small and large icons that appear in the Alexa skills store. You may have uploaded these through the developer console, through ASK CLI, or through SMAPI.

  • Skill service code.

  • Interaction model: Defines the voice user interface of the skill which includes the invocation name, intents, slots, and so forth. The name of the interaction model is <locale>.json, such as en-US.json.

Note that while your skill may also contain account linking information and in-skill products, these are not currently supported by the Skill Package API. You can still use the Skill Package API, but you will also have to use SMAPI for these specific features.

A skill package file combines all of these components into a zipped file with a .zip extension. The skill package folder should be set up as shown in the following image. If you have a smart home skill, you will not have an interaction model folder. The skill package folder should be set up as shown in the following image.

To manually create your zipped skill package file, place your skill components in the format shown, zip the top-level folder. You can then import the skill package starting with creation of the upload URL and then Create a new import for an existing skill.

If you already have a skill on the developer portal, you can create a skill export to download your skill to a zipped .zip format.

Skill package format
Skill package format

Create a new upload URL

Use this API to create a presigned upload URL, that you will then use to import a skill package. The URL will be located on Amazon S3. See Uploading Objects Using Presigned URLs. Note that you can also upload your package to the given presigned URL using a PUT request.

Request

HTTP/1.1

POST /v1/skills/uploads

Response

201 Created. The response body includes the uploadUrl value and the expiry date, as shown in the following sample.

{
  "uploadUrl": "string",
  "expiresAt": "2018-10-11T19:28:34.525Z"
}

Errors

Code Description
401 The auth token is invalid/expired or doesn’t have access to the resource.
429 Exceeds the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.
503 Service Unavailable.

Create a new skill package for the current vendor

Use this API to submit a request to create a new skill package for the current vendor. This API returns the value of the "Location" header, which is a relative URL from which you can download the zipped package file from S3.

Request

HTTP/1.1

POST /v1/skills/imports

The request body takes the following form:

{
  "vendorId": "string",
  "location": "string"
}

Response

202 Accepted. The value of the "Location" header is a relative URL from which you can download the zipped package file from S3.

{
  HTTP/1.1 202 Accepted
   "headers": {
    "Location": "/v1/skills/imports/{importId}"
}

Errors

Code Description
400 Server cannot process the request due to a client error.
401 The auth token is invalid/expired or doesn’t have access to the resource.
413 Payload Too Large.
429 Exceeds the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.
503 Service Unavailable.

Create a package for an existing skill

This API submits a request to create a zipped package file from an existing skill specified by skillId. This package can then be imported using a presigned URL if desired.

Request

HTTP/1.1

POST /v1/skills/{skillId}/imports

The request body takes the following form, with the location value being the presigned URL that you have previously obtained, or a public url from which the zipped skill package can be downloaded. See Create upload URL.

{
  "location": "string"
}

Response

202 Accepted. The value of the "Location" header is the URL that you have specified in the request.

{
   HTTP/1.1 202 Accepted
   "headers": {
    "Location": "/v1/skills/imports/{importId}"
}

Errors

Code Description
400 Server cannot process the request due to a client error.
401 The auth token is invalid/expired or doesn’t have access to the resource.
413 Payload Too Large.
429 Exceeds the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.
503 Service Unavailable.

Get the status for a specified importId

Obtains the importStatus for the specified importId.

Request

HTTP/1.1

GET /v1/skills/imports/{importId}

Response

200 OK. The status is one of: FAILED, IN_PROGRESS, SUCCEEDED. In addition, the resources object status has one of these values: FAILED, IN_PROGRESS, SUCCEEDED, ROLLBACK_IN_PROGRESS, ROLLBACK_SUCCEEDED, ROLLBACK_FAILED.

Response body

{
  "status": "FAILED",
  "skill": {
    "skillId": "string",
    "eTag": "string",
    "resources": [
      {
        "name": "string",
        "status": "FAILED",
        "errors": [
          {
            "message": "string"
          }
        ],
        "warnings": [
          {
            "message": "string"
          }
        ]
      }
    ]
  }
}

Errors

Code Description
401 The auth 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. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
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. If the export is successful, a zip file containing the skill package is created.

Request

The stage value is one of: live, development.

HTTP/1.1

POST /v1/skills/{skillId}/stages/{stage}/exports

Response

202 Accepted. The value of the "Location" header is a relative URL from which you can download the zipped package file from S3.

Errors

Code Description
401 The auth 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. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.
503 Service Unavailable.

Get the status for a given exportId

Request

A skill export to a package can either succeed or fail. The exportId is obtained when you create an export for an existing skill.

HTTP/1.1

GET /v1/skills/exports/{exportId}

Response

200 OK. Returns one of these statuses: FAILED, IN_PROGRESS, SUCCEEDED. The location value indicates where the resulting zipped skill package, with the name <skillname>.zip is located.

Sample response body

{
  "status": "FAILED",
  "skill": {
    "location": "string",
    "expiresAt": "2018-10-11T19:14:04.070Z"
  }
}

Errors

Code Description
401 The auth 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. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
500 Internal Server Error.
503 Service Unavailable.