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
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
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 |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Header |
String |
Yes |
Request body example
{
"repository": {
"url": "URL of the repository",
"type": "GIT"
}
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Identifies the code repository for your Alexa-hosted skill. |
Object |
Yes |
|
|
URL of the code repository. To get the URL, use Get repository metadata. |
String |
Yes |
|
|
Code repository type. |
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 |
|---|---|---|
|
|
Credentials for the code repository for the specified Alexa-hosted skill. |
Object |
|
|
Username that, along with the password, provides access to the repository for the skill. |
String |
|
|
Password that, along with the username, provides access to the repository for the skill. |
String |
|
|
Date and time after which the credentials expire. After expiration, call this API again to get new credentials. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains credentials to access the repository. |
|
|
Indicates that one or more properties in the request body are invalid. |
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
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. |
|
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
|
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
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 |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Header |
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 |
|---|---|---|
|
|
Metadata for the code repository. |
Object |
|
|
Repository information. |
String |
|
|
URL of the code repository. Use the URL to generate credentials to access the code repository from Git. |
String |
|
|
Type of repository. |
String |
|
|
Runtime for the Alexa-hosted skill. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the metadata for the code repository. |
|
|
Indicates that one or more properties in the request body are invalid. |
|
|
Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
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. |
|
|
Error occurred on the server. The skill can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |