Alexa-Hosted Skill API

With an Alexa-hosted skill, you can get started quickly by using Amazon Web Services (AWS) resources to power your skill. An Alexa-hosted skill works with a code editor in the Alexa Skills Kit developer console that you can use to edit and deploy changes to your AWS Lambda code. You can also use the Alexa Skills Kit Command Line Interface (ASK CLI) to edit and deploy an Alexa-hosted skill.

For details about Alexa-hosted skills, see Build a Skill End-to-end Using an Alexa-hosted Skill.

You can use this API to get the URL for the repository that contains your Alexa-hosted skill, and to generate credentials (a username and password) that you can use to access the repository. To access the repository directly, use your preferred Git client, or use Git from the command line.

Get metadata about an Alexa-hosted skill

Use this API to get information about an Alexa-hosted skill, including the URL of the repository that contains the Alexa-hosted skill. After you get the URL of the repository, you can generate repository credentials to access the repository directly with your preferred Git client or by using Git from the command line.

Request

The API 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.

HTTP method and URI path

GET /v1/skills/{skillId}/alexaHosted

Request fields

Field Description Type
skillId Required. Part of the URI path. The ID of an Alexa-hosted skill. String

Response

A successful request returns HTTP 200 OK.

Response body structure

{
  "alexaHosted": {
    "repository": {
      "url": "string",
      "type": "string"
    },
    "runtime": "string"
  }
}

Response body fields

Field Description Type
alexaHosted.repository.url The URL of the repository that contains the Alexa-hosted skill. With this URL, you can generate repository credentials to access the repository directly with your preferred Git client or by using Git from the command line. String
alexaHosted.repository.type The type of the repository. The only valid value is GIT. String
alexaHosted.runtime The runtime for the Alexa-hosted skill. The only valid values are nodejs12.x and python3.7. String

Error responses

An unsuccessful request returns one of the following errors:

  • HTTP 400 Bad Request
  • HTTP 401 Unauthorized
  • HTTP 404 Not Found
  • HTTP 429 Too Many Requests
  • HTTP 500 Internal Server Error
  • HTTP 503 Service Unavailable

Generate repository credentials for an Alexa-hosted skill

Use this API to generate credentials (a username and password) that you can use to access the repository that contains the specified Alexa-hosted skill. To access the repository directly, use your preferred Git client, or use Git from the command line.

Request

The API 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.

HTTP method and URI path

POST /v1/skills/{skillId}/alexaHosted/repository/credentials/generate

Request body structure

{
  "repository": {
    "url": "string",
    "type": "string"
  }
}

Request fields

Field Description Type
skillId Required. Part of the URI path. The ID of an Alexa-hosted skill. String
repository.url Required. Part of the request body. The URL of the repository that contains the Alexa-hosted skill. To get this value, first get metadata about an Alexa-hosted skill. String
repository.type Required. Part of the request body. The type of the repository. The only valid value is GIT. String

Response

A successful request returns HTTP 200 OK.

Response body structure

{
  "repositoryCredentials": {
    "username": "string",
    "password": "string",
    "expiresAt": "2019-04-16T17:44:36.231Z"
  }
}

Response body fields

Field Description Type
username The username that, along with the password, provides access to the repository for the Alexa-hosted skill. String
password The corresponding password that, along with the username, provides access to the repository for the Alexa-hosted skill. String
expiresAt The date and time at which the credentials (username and password) expire. After they expire, you must call this API again to get new credentials. String

Error responses

An unsuccessful request returns one of the following errors:

  • HTTP 400 Bad Request
  • HTTP 401 Unauthorized
  • HTTP 404 Not Found
  • HTTP 429 Too Many Requests
  • HTTP 500 Internal Server Error
  • HTTP 503 Service Unavailable