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 how to build an Alexa-hosted skill, see About Alexa-hosted skills. 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 aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. 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": "nodejs16.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 aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Related topics
- Create and Manage Alexa-hosted Skills from the Alexa Developer Console
- Create and Manage Alexa-hosted Skills Using the ASK CLI
Last updated: Aug 01, 2024