Alexa-hosted Skill Management REST API Reference

Use the Alexa-hosted Skill Management REST API to get the URL for the code repository that contains your Alexa-hosted skill, and to generate credentials to access the repository. With these credentials, you can access the repository directly with your preferred Git client or use Git from the command line.

For details about Alexa-hosted skills, see Build a Skill End-to-end Using an Alexa-hosted Skill. You can also use the Alexa Skills Kit Command Line Interface (ASK CLI) to edit and deploy an Alexa-hosted skill.

API endpoint

The endpoint of the Alexa-hosted skill 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 Alexa-hosted skill management API includes the following operations.

Operation HTTP method and URI

Generate repository credentials

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

Get repository metadata

GET /v1/skills/{skillId}/alexaHosted

Generate repository credentials

Generate username and password credentials to access the code repository that contains the specified Alexa-hosted skill. Then, use the repository URL to generate repository credentials.

Request

To generate the credentials, you make a POST request to the alexaHosted resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/alexaHosted/repository/credentials/generate
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

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "repository": {
        "url": "URL of the repository",
        "type": "GIT"
    }
}

Request body properties

Property Description Type Required

repository

Identifies the code repository for your Alexa-hosted skill.

Object

Yes

repository.url

URL of the code repository. To get the URL, use Get repository metadata.

String

Yes

repository.type

Code repository type.
Valid value: GIT.

String

Yes

Response

A successful response returns HTTP 200 OK, along with the credentials to access the repository. 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

{
    "repositoryCredentials": {
        "username": "your.amzn1.ask.account.1",
        "password": "your.amzn1.ask.account.password.1",
        "expiresAt": "2022-08-16T17:44:36.231Z"
    }
}

Response body properties

Property Description Type

repositoryCredentials

Credentials for the code repository for the specified Alexa-hosted skill.

Object

repositoryCredentials.username

Username that, along with the password, provides access to the repository for the skill.

String

repositoryCredentials.password

Password that, along with the username, provides access to the repository for the skill.

String

repositoryCredentials.expiresAt

Date and time after which the credentials expire. After expiration, call this API again to get new credentials.

String

HTTP status codes

Status Description

200 OK

Response body contains credentials to access the repository.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
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 token is invalid or expired. Or, the client doesn'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 repository metadata

Get the metadata for the code repository.

Request

To get the repository metadata, you make a GET request to the alexaHosted resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/alexaHosted
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

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters

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 repository metadata. 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

{
    "alexaHosted": {
        "repository": {
            "url": "URL to the repository",
            "type": "GIT"
        },
        "runtime": "nodejs12.x"
    }
}

Response body properties

Property Description Type

alexaHosted

Metadata for the code repository.

Object

alexaHosted.repository

Repository information.

String

alexaHosted.repository.url

URL of the code repository. Use the URL to generate credentials to access the code repository from Git.

String

alexaHosted.repository.type

Type of repository.

String

runtime

Runtime for the Alexa-hosted skill.

String

HTTP status codes

Status Description

200 OK

Response body contains the metadata for the code repository.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
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 token is invalid or expired. Or, the client doesn'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.

Last updated: Oct 31, 2022