Skill Manifest REST API Reference
Use the Skill Manifest REST API to create and update the skill manifest. The skill manifest is the JSON representation of your skill, and provides Alexa with all the metadata required for your skill. For more details about the skill manifest, see Skill Manifest Schema.
As an option, you can manage the skill manifest by using the Alexa Skills Kit (ASK) Command Line Interface.
API endpoint
The endpoint of the Skill Manifest 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 Skill Manifest API includes the following operations.
Operation | HTTP method and URI |
---|---|
| |
| |
| |
| |
| |
|
Create skill manifest
Submit a request to create a skill defined by the specified skill manifest for the specified vendor.
Request
To create a skill manifest, you make a POST
request to the skills
resource.
Request path and header example
POST /v1/skills
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
String |
Yes |
Request body example
{
"vendorId": "your.vendor.id.1"
"manifest": {
"publishingInformation": {
"locales": {
"en-US": {
"summary": "This is a sample Alexa custom skill.",
"examplePhrases": [
"Alexa, open sample custom skill.",
"Alexa, play sample custom skill."
],
"keywords": [
"Descriptive_Phrase_1",
"Descriptive_Phrase_2",
"Descriptive_Phrase_3"
],
"smallIconUri": "https://smallUri.com",
"largeIconUri": "https://largeUri.com",
"name": "Sample custom skill name.",
"description": "This skill does interesting things."
}
},
"isAvailableWorldwide": false,
"testingInstructions": "1) Say 'Alexa, hello world",
"category": "HEALTH_AND_FITNESS",
"distributionCountries": [
"US",
"GB"
]
},
"apis": {},
"manifestVersion": "1.0",
"permissions": [],
"privacyAndCompliance": {},
"events": {}
}
}
Request body properties
Property | Description | Type |
---|---|---|
|
Identifies the vendor to which the skill belongs. |
String |
|
Identifies the vendor to which the skill belongs. |
Manifest object |
Response
A successful response returns HTTP 202 Accepted
, along with a Location
parameter in the response header with a URL to track the build status of the skill. The response body contains the skill ID.
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
The following example shows a response.
{
"skillId": "amzn1.ask.skill.1"
}
Response body properties
Property | Description | Type |
---|---|---|
|
Identifies the new skill. |
String |
HTTP status codes
Status | Description |
---|---|
|
Request to create the skill manifest succeeded. The response header contains a |
|
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. |
Delete skill manifest
Delete a skill manifest for the specified skill ID. This operation deletes your skill and the associated voice interaction model.
Request
To delete a skill manifest, you make a DELETE
request to the skill
resource.
Request path and header example
DELETE /v1/skills/{skillId}/
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
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 204 No Content
to indicate that the skill is deleted.
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
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Successful deletion of the specified skill and voice interaction model. |
|
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 skill manifest
Get the skill manifest for the specified skill and skill stage.
Request
To get the skill manifest, you make a GET
request to the manifest
resource.
Request path and header example
GET /v1/skills/{skillId}/stages/{stage}/manifest
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 |
|
Path |
Indicates stage of 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 skill manifest. The response header contains an If-Match
parameter with an entity tag that represents the current version of the skill manifest.
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
{
"manifest": {
"publishingInformation": {
"locales": {
"en-US": {
"summary": "This is a sample Alexa custom skill.",
"examplePhrases": [
"Alexa, open sample custom skill.",
"Alexa, play sample custom skill."
],
"keywords": [
"Descriptive_Phrase_1",
"Descriptive_Phrase_2",
"Descriptive_Phrase_3"
],
"smallIconUri": "https://smallUri.com",
"largeIconUri": "https://largeUri.com",
"name": "Sample custom skill name.",
"description": "This skill does interesting things."
}
},
"isAvailableWorldwide": false,
"testingInstructions": "1) Say 'Alexa, hello world",
"category": "HEALTH_AND_FITNESS",
"distributionCountries": [
"US",
"GB"
]
},
"apis": {},
"manifestVersion": "1.0",
"permissions": [],
"privacyAndCompliance": {},
"events": {}
}
}
Response body properties
Property | Description | Type |
---|---|---|
|
Identifies the vendor to which the skill belongs. |
Manifest object |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the skill manifest for the specified skill and stage. The response header contains an |
|
Response header contains a |
|
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 skill status
Get the status of the specified skill ID. You can define filter criteria based on a combination of resources.
Request
To get the status of a skill, you make a GET
request to the skill
resource.
Request path and header example
GET /v1/skills/{skillId}/status?resource={resource}
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 |
|
Query |
Filter the results based on the specified resource. You can specify this filter more than one time in a request. |
String |
No |
|
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 status of the specified skill resources.
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
{
"manifest": {
"eTag": "etag.id.1",
"lastUpdateRequest": {
"status": "FAILED",
"errors": [{
"code": "ErrorCode",
"message": "Please provide a valid url having a valid image for small icon or large icon"
},
{
"code": "ErrorCode",
"message": "Small icon size should be 108*108. Large icon size should be 512*512."
}
],
"warnings": []
}
},
"interactionModel": {
"en-US": {
"eTag": "etag.id.2",
"lastUpdateRequest": {
"status": "SUCCEEDED",
"errors": [],
"warnings": [],
"buildDetails": {
"steps": [{
"name": "LANGUAGE_MODEL_FULL_BUILD",
"status": "SUCCEEDED",
"errors": []
}]
}
},
"errors": [],
"warnings": [],
"version": "1"
},
"en-GB": {
"eTag": "etag.id.3",
"lastUpdateRequest": {
"status": "IN_PROGRESS",
"errors": [],
"warnings": [],
"buildDetails": {
"steps": [{
"name": "DIALOG_MODEL_BUILD",
"status": "IN_PROGRESS",
"errors": []
}]
}
},
"errors": [],
"warnings": [],
"version": "1"
}
},
"hostedSkillDeployment": {
"lastUpdatedRequest": {
"status": "SUCCEEDED",
"errors": [],
"warnings": [],
"deploymentDetails": {
"commitId": "commit.id.1",
"logUrl": "https://console.aws.amazon.com/cloudwatch/example.1"
}
}
},
"hostedSkillProvision": {
"lastUpdatedRequest": {
"status": "SUCCEEDED",
"errors": [],
"warnings": []
}
}
}
Response body properties
Property | Description | Type |
---|---|---|
|
Status of the skill manifest. |
Object |
|
Status of the last update to the skill manifest. |
Object |
|
Build status of the last requested update. |
String |
|
Errors that occurred during the last update request. |
Array of Error objects |
|
Warnings that occurred during the last update request. |
Array of Error objects |
|
(Optional) Created version of the skill manifest. Included for status of |
String |
|
Opaque identifier for last successful update. |
String |
|
Status of the interaction model by locale. |
Object |
|
Build status of the last requested update. |
String |
|
Errors that occurred during the last update request. |
Array of Error objects |
|
Warnings that occurred during the last update request. |
Array of Error objects |
|
Status of each build step. |
BuildDetails object |
|
Opaque identifier for last successful interaction model update. |
String |
|
Version of the interaction model. |
String |
|
(Optional) Status of the Alexa-hosted skill deployment to the Amazon Web Services (AWS) Lambda endpoint. Included for Alexa-hosted skills only. |
Object |
|
Status of the last request to deploy the skill. |
Object |
|
Status of the deployment. |
String |
|
Errors that occurred during the deployment. |
Array of Error objects |
|
Warnings that occurred during the deployment. |
Array of Error objects |
|
Details of the deployment. |
DeploymentDetails object |
|
(Optional) Status of the request to provision Alexa-hosted resources. Included for Alexa-hosted skills only. |
Object |
|
Status of the last request to provision the resources. |
Object |
|
Status of the provisioning request. |
String |
|
Errors that occurred during provisioning. |
Array of Error objects |
|
Warnings that occurred during provisioning. |
Array of Error objects |
HTTP status codes
Status | Description |
---|---|
|
Response body contains status of the skill resources. |
|
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. |
List skills
List the skills for the specified vendor.
Request
To list skills, you make a GET
request to the skill
resource.
Request path and header example
GET /v1/skills/vendorId={vendorId}&skillId={skillId}&maxResults={maxResults}&nextToken={nextToken}
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 |
---|---|---|---|---|
|
Query |
Identifies the vendor to which the skill belongs. |
String |
Yes |
|
Path |
Filter the list based on the specified skill ID. You can specify this filter more than one time in a request. |
String |
No |
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
Query |
Token from the previous response. If not included, the Alexa service returns the first page of results. |
String |
No |
|
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 a list of skills for the specified vendor.
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
{
"skills": [{
"lastUpdated": "2017-07-11T19:29:57.120Z",
"nameByLocale": {
"en-US": "example"
},
"stage": "development",
"apis": [
"custom"
],
"publicationStatus": "DEVELOPMENT",
"_links": {
"self": {
"href": "/v1/skills/amzn1.ask.skill.1/stages/development/manifest"
}
},
"skillId": "amzn1.ask.skill.1"
},
{
"lastUpdated": "2017-07-05T21:11:16.947Z",
"asin": "someASIN.1",
"nameByLocale": {
"en-US": "example1"
},
"stage": "live",
"apis": [
"video"
],
"publicationStatus": "PUBLISHED",
"_links": {
"self": {
"href": "/v1/skills/amzn1.ask.skill.2/stages/live/manifest"
}
},
"skillId": "amzn1.ask.skill.2"
}
],
"_links": {
"next": {
"href": "/v1/skills?vendorId=your.vendor.id.1"
},
"self": {
"href": "/v1/skills?vendorId=your.vendor.id.1"
}
},
"isTruncated": true,
"nextToken": "someToken.1"
}
Response body properties
Property | Description | Type |
---|---|---|
skills |
List of skills and summary information. The list might contain up to 3 entries with the same skill ID: one for development stage, one for certification stage, and one for the live stage. |
Array of objects |
skills[].skillId |
Identifies the skill. |
String |
skills[].stage |
Indicates stage of the skill. |
String |
skills[].apis |
List of APIs implemented by the skill. |
Array of string |
skills[].publicationStatus |
Identifies the skill. |
String |
skills[].lastUpdated |
Date and time of the most recent update. |
String |
skills[].asin |
(Optional) Amazon Standard Identification Number (ASIN) identifies the skill in the Alexa skill store. Available for published skills only. |
String |
skills[].nameByLocale |
Key value pair where keys are the locale name and value is the name of the skill in that locale. |
Object |
|
Link to the skill manifest. |
_links object |
|
Links for item navigation. |
_links object |
|
Indicates whether there are more items to return. If set to |
Boolean |
|
(Optional) Included when there are more results to return. Use this value in a subsequent request. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains …. |
|
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. |
Update manifest
Update the skill manifest for the specified skill and stage.
Request
To update a skill manifest, you make a PUT
request to the manifest
resource.
Request path and header example
PUT /v1/skills/{skillId}/stages/{stage}/manifest
Host: api.amazonalexa.com
Content-Type: application/json
If-Match: {etag}
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
Header |
Current version of the skill manifest. Use Get skill manifest to get the current version. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
{
"manifest": {
"publishingInformation": {
"locales": {
"en-US": {
"summary": "This is a sample Alexa custom skill.",
"examplePhrases": [
"Alexa, open sample custom skill.",
"Alexa, play sample custom skill."
],
"keywords": [
"Descriptive_Phrase_1",
"Descriptive_Phrase_2",
"Descriptive_Phrase_3"
],
"smallIconUri": "https://smallUri.com",
"largeIconUri": "https://largeUri.com",
"name": "Sample custom skill name.",
"description": "This skill does interesting things."
}
},
"isAvailableWorldwide": false,
"testingInstructions": "1) Say 'Alexa, hello world or good morning",
"category": "HEALTH_AND_FITNESS",
"distributionCountries": [
"US",
"GB"
]
},
"apis": {},
"manifestVersion": "1.0",
"permissions": [],
"privacyAndCompliance": {},
"events": {}
}
}
Request body properties
Property | Description | Type |
---|---|---|
|
JSON representation of the specified skill and stage. |
Manifest object |
Response
A successful response returns HTTP 202 Accepted
, along with a Location
parameter in the response header with a URL to track the build status of the updated skill manifest.
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
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Request to update the skill manifest succeeded. The response header contains a |
|
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. |
Object definitions
The Skill Manifest API defines the following object definitions.
BuildDetails object
The BuildDetails
object describes the steps involved in a build of the voice interaction model. As the build progresses, it adds new steps to the array.
Property | Description | Type |
---|---|---|
|
Steps involved in the in-progress build. |
Array of objects |
|
Name of the build step. |
String |
|
Status of the build. |
String |
|
(Optional) List of errors that occurred during the build. |
Array of Error objects |
DeploymentDetails object
The DeploymentDetails
object describes the deployment of the Alexa-hosted skill to the Lambda endpoint.
Property | Description | Type |
---|---|---|
|
Git commit ID. |
String |
|
URL to the AWS Cloudwatch logs. |
String |
Error object
The Error object describes the errors or warnings that occur during the last request update of a skill resource.
Property | Description | Type |
---|---|---|
|
HTTP status code that reflects the error. |
String |
|
Human readable error message. |
String |
Related topics
- Create and Manage Skills in the Alexa Developer Console
- Skill Manifest Schema
- Resource Schema REST API Reference
Last updated: Aug 01, 2024