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

POST /v1/skills

Delete skill manifest

DELETE /v1/skills/{skillId}/

Get manifest

GET /v1/skills/{skillId}/stages/{stage}/manifest

Get skill status

GET /v1/skills/{skillId}/status?resource={resource}

List skills

GET /v1/skills/vendorId={vendorId}&&skillId={skillId}&maxResults={maxResults}&nextToken={nextToken}

Update manifest

PUT /v1/skills/{skillId}/stages/{stage}/manifest

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

Copied to clipboard.

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

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "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

vendorId

Identifies the vendor to which the skill belongs.
For details about how to get your vendor ID, see Locate your customer ID and vendor ID.

String

manifest

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

skillId

Identifies the new skill.
Valid values: 1 – 255 characters.

String

HTTP status codes

Status Description

202 Accepted

Request to create the skill manifest succeeded. The response header contains a Location parameter with a URL to track the build status of the skill manifest. The response body contains the skill ID.

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.

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

Copied to clipboard.

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

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 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

204 No Content

Successful deletion of the specified skill and voice interaction model.

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 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

Copied to clipboard.

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

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

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 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

manifest

Identifies the vendor to which the skill belongs.

Manifest object

HTTP status codes

Status Description

200 OK

Response body contains the skill manifest for the specified skill and stage. The response header contains an If-Match parameter with an entity tag that represents the current version of the skill manifest.

303 See Other

Response header contains a Location parameter that includes a relative URL to get the skill status.

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 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

Copied to clipboard.

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

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

resource

Query

Filter the results based on the specified resource. You can specify this filter more than one time in a request.
Valid values: manifest, interactionModel, hostedSkillDeployment, hostedSkillProvisioning.

String

No

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 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

manifest

Status of the skill manifest.

Object

manifest.lastUpdateRequest

Status of the last update to the skill manifest.

Object

manifest.lastUpdateRequest.status

Build status of the last requested update.
Valid values: FAILED, IN_PROGRESS, SUCCEEDED.

String

manifest.lastUpdateRequest.errors

Errors that occurred during the last update request.

Array of Error objects

manifest.lastUpdateRequest.warnings

Warnings that occurred during the last update request.

Array of Error objects

manifest.lastUpdateRequest.version

(Optional) Created version of the skill manifest. Included for status of SUCCEEDED only.

String

manifest.eTag

Opaque identifier for last successful update.

String

interactionModel

Status of the interaction model by locale.

Object

interactionModel.lastUpdateRequest.status

Build status of the last requested update.
Valid values: FAILED, IN_PROGRESS, SUCCEEDED.

String

interactionModel.lastUpdateRequest.errors

Errors that occurred during the last update request.

Array of Error objects

interactionModel.lastUpdateRequest.warnings

Warnings that occurred during the last update request.

Array of Error objects

interactionModel.lastUpdateRequest.buildDetails

Status of each build step.

BuildDetails object

interactionModel.eTag

Opaque identifier for last successful interaction model update.

String

interactionModel.version

Version of the interaction model.

String

hostedSkillDeployment

(Optional) Status of the Alexa-hosted skill deployment to the Amazon Web Services (AWS) Lambda endpoint. Included for Alexa-hosted skills only.

Object

hostedSkillDeployment.lastUpdateRequest

Status of the last request to deploy the skill.

Object

hostedSkillDeployment.lastUpdateRequest.status

Status of the deployment.
Valid values: FAILED, IN_PROGRESS, SUCCEEDED.

String

hostedSkillDeployment.lastUpdateRequest.errors

Errors that occurred during the deployment.

Array of Error objects

hostedSkillDeployment.lastUpdateRequest.warnings

Warnings that occurred during the deployment.

Array of Error objects

hostedSkillDeployment.lastUpdateRequest.deploymentDetails

Details of the deployment.

DeploymentDetails object

hostedSkillProvisioning

(Optional) Status of the request to provision Alexa-hosted resources. Included for Alexa-hosted skills only.

Object

hostedSkillProvisioning.lastUpdateRequest

Status of the last request to provision the resources.

Object

hostedSkillProvisioning.lastUpdateRequest.status

Status of the provisioning request.
Valid values: FAILED, IN_PROGRESS, SUCCEEDED.

String

hostedSkillProvisioning.lastUpdateRequest.errors

Errors that occurred during provisioning.

Array of Error objects

hostedSkillProvisioning.lastUpdateRequest.warnings

Warnings that occurred during provisioning.

Array of Error objects

HTTP status codes

Status Description

200 OK

Response body contains status of the skill resources.

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.

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

Copied to clipboard.

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

vendorId

Query

Identifies the vendor to which the skill belongs.
For details about how to get your vendor ID, see Locate your customer ID and vendor ID.

String

Yes

skillId

Path

Filter the list based on the specified skill ID. You can specify this filter more than one time in a request.
Valid values: 1 – 255 characters.

String

No

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–50. Default: 10.

Integer

No

nextToken

Query

Token from the previous response. If not included, the Alexa service returns the first page of results.
Include if iterating over a paginated response.

String

No

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 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",
                "householdList"
            ],
            "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.
Valid values: development, live.

String

skills[].apis

List of APIs implemented by the skill.
Valid values: custom, smartHome, flashBriefing, video, music, householdList.

Array of strings

skills[].publicationStatus

Identifies the skill.
Valid values: DEVELOPMENT, CERTIFICATION, CERTIFIED, PUBLISHED, HIDDEN, REMOVED.

String

skills[].lastUpdated

Date and time of the most recent update.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

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

skills[]._links

Link to the skill manifest.
Defined in JSON Hypertext Application Language specification.

_links object

_links

Links for item navigation.
Defined in JSON Hypertext Application Language specification.

_links object

isTruncated

Indicates whether there are more items to return. If set to true, include nextToken a subsequent request. Or, you can get the remaining items by using the next link in the _links object.

Boolean

nextToken

(Optional) Included when there are more results to return. Use this value in a subsequent request.

String

HTTP status codes

Status Description

200 OK

Response body contains ….

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.

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

Copied to clipboard.

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

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

String

Yes

etag

Header

Current version of the skill manifest. Use Get skill manifest to get the current version.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "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

manifest

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

202 Accepted

Request to update the skill manifest succeeded. The response header contains a Location parameter with a URL to track the build status of the updated skill manifest.

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.

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

Steps involved in the in-progress build.

Array of objects

steps[].name

Name of the build step.
Valid values: DIALOG_MODEL_BUILD, LANGUAGE_MODEL_QUICK_BUILD, LANGUAGE_MODEL_FULL_BUILD, ALEXA_CONVERSATIONS_QUICK_BUILD, ALEXA_CONVERSATIONS_FULL_BUILD.

String

steps[].status

Status of the build.
Valid values: FAILED, IN_PROGRESS, SUCCEEDED.

String

steps[].errors

(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

commitId

Git commit ID.

String

logUrl

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

code

HTTP status code that reflects the error.

String

message

Human readable error message.

String

Last updated: Feb 03, 2023