Grato por sua visita. Neste momento esta página está apenas disponível em inglês.

Skill Package API Reference

You can use the Skill Package API 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 is 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 Alexa Skills Kit developer console, these components still exist behind the scenes. If you interact with your skill through ASK CLI or SMAPI, you will see these components as individual files.

  • Manifest – General metadata and configuration like 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 is skill.json. This manifest is a requirement for every skill.

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

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

  • 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 might 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.

To manually create your zipped skill package file, place your skill components in the format shown, then 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 can then use to import a skill package. The URL will be located on Amazon S3. For more information, see Uploading Objects Using Presigned URLs in the Amazon S3 documentation. Note that you can also upload your package to the given presigned URL using a PUT request.

Request

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 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

The request body takes the following form:

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

Response

202 Accepted

The value of the Location header is a relative URL that should be used 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.

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

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. For more information, see Create upload URL.

{
  "location": "string"
}

Response

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.
413 Payload Too Large.
429 Exceeds the permitted request limit.
500 Internal Server Error.
503 Service Unavailable.

Get the status for a specified importId

Obtains the importStatus for the specified importId.

Request

GET /v1/skills/imports/{importId}

Response

200 OK

The status is one of: FAILED, IN_PROGRESS, or SUCCEEDED. In addition, the resources object status has one of these values: FAILED, IN_PROGRESS, SUCCEEDED, ROLLBACK_IN_PROGRESS, ROLLBACK_SUCCEEDED, or 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 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 to download the exported skill.

Request

The stage value must be either live (for a live, published skill) or development (for a skill in the development stage).

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

Response

202 Accepted

The response has no body. To get the status of the export request, including a URL to download the exported skill, send a GET request to the path in the response's Location header. For more information, 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 to download a zip archive of the exported skill.

Request

Send a GET request to the path contained in the Location header of the response to a previous export request. The exportId is provided in this path, so you don't need to do anything extra to obtain it.

GET /v1/skills/exports/{exportId}

Response

200 OK

The body of the response contains one of these statuses: FAILED, IN_PROGRESS, or SUCCEEDED. When the status is SUCCEEDED, the skill.location value contains a URL that you can use to download a zip archive of the exported skill.

Example response body

{
  "skill": {
    "expiresAt": "1550521786056",
    "location": "URL to download the exported skill"
  },
  "status": "SUCCEEDED"
}

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.