Your Alexa Consoles
Sign In
Sign In

Alexa-hosted skill API

With an Alexa-hosted skill, you can get started quickly using Alexa-hosted 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 more information 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 directly access the repository.

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.

Request

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.

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. 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 value is nodejs8.10. 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 directly access the repository that contains an Alexa-hosted skill.

Request

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.

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