Skill Resource Operations (Skill Management API)
This reference describes the Skill Management API (SMAPI) operations related to creating and updating skills and skill manifests.
The endpoint for SMAPI operations is https://api.amazonalexa.com. Each request must have an Authorization header whose value should be the access token retrieved from Login with Amazon.
You can also access SMAPI operations by using the ASK Command Line Interface (ASK CLI). For details, see ASK CLI Command Reference.
- Get Skill Information
- Create a skill
- Update an existing skill
- Get the status of a skill
- List skills
- Delete a skill
Get Skill Information
Gets the skill manifest for a specified skill.
Request
GET /v1/skills/{skillId}/stages/{stage}/manifest
Parameters
| Field | Description | Parameter Type | Required |
|---|---|---|---|
skillId | Unique identifier of skill. | Path | Yes |
stage | Indicates stage of the skill. Value is one of development or live (case sensitive). | Path | Yes |
Response
HTTP/1.1 200 response contains the latest version of skill manifest.
Headers
ETag: <etag_value>
Body
A Skill Manifest object.
Exceptions
HTTP/1.1 303 See Other
HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.
HTTP/1.1 403 The operation being requested is not allowed.
HTTP/1.1 404 The resource being requested is not found.
HTTP/1.1 429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Create a skill
Submits a skill creation request for a specified vendorId. This is an asynchronous operation that may result in failure when the server processes the request. Use the Location header to track the status of this request.
Request
POST /v1/skills
Body
The body includes the vendorId, and a manifest object as described in Skill Manifest, as shown in the following example.
{
"vendorId": "MT25O3ZVSAXZOAX",
"manifest": {
"publishingInformation": {
"locales": {
"en-US": {
"summary": "This is a sample Alexa skill.",
"examplePhrases": [
"Alexa, open sample skill.",
"Alexa, turn on kitchen lights.",
"Alexa, blink kitchen lights."
],
"keywords": [
"Smart Home",
"Lights",
"Smart Devices"
],
"name": "Sample custom skill name.",
"description": "This skill has basic and advanced smart devices control features."
}
},
"isAvailableWorldwide": false,
"testingInstructions": "1) Say 'Alexa, discover my devices' 2) Say 'Alexa, turn on sample lights'",
"category": "SMART_HOME",
"distributionCountries": [
"US",
"GB"
]
},
"apis": {
"custom": {
"endpoint": {
"uri": "arn:aws:lambda:us-east-1:032174894474:function:ask-custom-custome_cert"
}
}
},
"manifestVersion": "1.0",
"privacyAndCompliance": {
"allowsPurchases": false,
"locales": {
"en-US": {
"termsOfUseUrl": "http://www.termsofuse.sampleskill.com",
"privacyPolicyUrl": "http://www.myprivacypolicy.sampleskill.com"
}
},
"isExportCompliant": true,
"isChildDirected": false,
"usesPersonalInfo": false
}
}
}
Response
HTTP/1.1 202 Accepted; Returns a URL to track the status in `Location` header.
Headers
Location: <Returns a relative URL to track the status>
Body
{
"skillId": "{skillId}"
}
The 202 status means the request was accepted successfully for processing. The skillId that is returned is intended as a reference for GET /v1/skills/{skillId}/status. Because the workflow is asynchronous, GET /v1/skills/{skillId}/status may return a 404 response for a short period of time after the initial POST /v1/skills request, until the skill is successfully created.
Thus, if you submit a skill creation request, you should subsequently use GET /v1/skills/{skillId}/status to check the status of the skill in order to verify the skill has been successfully created.
Exceptions
HTTP/1.1 400 Server cannot process the request due to a client error.
HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.
HTTP/1.1 403 The operation being requested is not allowed.
HTTP/1.1 429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Update an existing skill
Updates the Skill Manifest associated with the specified skill ID.
Request
PUT /v1/skills/{skillId}/stages/{stage}/manifest
Parameters
| Field | Description | Parameter Type | Required |
|---|---|---|---|
skillId | Unique identifier of skill. | Path | Yes |
stage | Stage of the skill. Accepted value is development (case sensitive). | Path | Yes |
Headers
If-Match: <etag_value>
Body
manifest object as described in Skill Manifest.
Response
HTTP/1.1 202 Accepted; Returns a URL to track the status in 'Location' header.
Headers
Location: <Returns a relative URL to track the status>
Exceptions
HTTP/1.1 400 Server cannot process the request due to a client error.
HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.
HTTP/1.1 403 The operation being requested is not allowed.
HTTP/1.1 404 The resource being requested is not found.
HTTP/1.1 409 The request could not be completed due to a conflict with the current state of the target resource.
HTTP/1.1 412 Precondition failed
HTTP/1.1 429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Get the status of a skill
You can obtain the status of your last request to create or update a skill by using the status API. Use this API after you create or update a skill to verify that the skill has been built successfully.
Request
The following example illustrates a request for the status of a skill.
GET /v1/skills/{skillId}/status
The following example illustrates a request for the status of a skill and that specifies two optional resources as filters.
GET /v1/skills/{skillId}/status?resource={resource1}&resource={resource2}
Each resource parameter is an optional filter.
Parameters
| Field | Description | Parameter Type | Required |
|---|---|---|---|
skillId |
The identifier for the skill. | Path | Yes |
resource |
You can specify resources to filter the results. One or more of: interactionModel, manifest, HostedSkillDeploymentStatus, HostedSkillProvision. |
Query parameter | No |
Response
The response returns the status for the skill and specified sub-resources. For details about the interaction model, see Save and Build the Model.
HTTP/1.1 200
Body
The following example shows the structure of the response body:
{
"manifest": {
"eTag": "ahsdfuhq34894hjk",
"lastUpdateRequest": {
"status": "FAILED",
"errors": [
{
"message": "Please provide a valid url having a valid image for small icon or large icon"
},
{
"message": "Small icon size should be 108*108. Large icon size should be 512*512."
}
],
"warnings": []
}
},
"interactionModel": {
"en-US": {
"eTag": "agasguhq34894hjk",
"lastUpdateRequest": {
"status": "SUCCEEDED",
"errors": [],
"warnings": [],
"buildDetails": {
"steps": [
{
"name": "DIALOG_MODEL_BUILD | LANGUAGE_MODEL_QUICK_BUILD | LANGUAGE_MODEL_FULL_BUILD",
"status": "IN_PROGRESS | SUCCEEDED | FAILED",
"errors": [
{
"code": "ErrorCode",
"message": "This is the error message"
}
]
}
]
}
},
"errors": [],
"warnings": [],
"version": "1"
},
"en-GB": {
"eTag": "ahsadfahq34894hjk",
"lastUpdateRequest": {
"status": "IN_PROGRESS",
"errors": [],
"warnings": [],
"buildDetails": {
"steps": [
{
"name": "DIALOG_MODEL_BUILD | LANGUAGE_MODEL_QUICK_BUILD | LANGUAGE_MODEL_FULL_BUILD",
"status": "IN_PROGRESS | SUCCEEDED | FAILED",
"errors": [
{
"code": "ErrorCode",
"message": "This is the error message"
}
]
}
]
}
},
"errors": [],
"warnings": [],
"version": "1"
}
},
"hostedSkillDeployment": {
"lastUpdatedRequest": {
"status": "SUCCEEDED | IN_PROGRESS | FAILED",
"errors": [],
"warnings": [],
"deploymentDetails": {
"commitId": "<commit id>",
"logUrl": "https://console.aws.amazon.com/cloudwatch/home?region=us-east-1"
}
}
},
"hostedSkillProvision": {
"lastUpdatedRequest": {
"status": "SUCCEEDED | IN_PROGRESS | FAILED",
"errors":[],
"warnings": []
}
}
}
Exceptions
HTTP/1.1 400 Server cannot process the request due to a client error.
HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.
HTTP/1.1 403 The operation being requested is not allowed.
HTTP/1.1 404 The resource being requested is not found.
HTTP/1.1 429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
List skills
List the skills for the specified vendorId. The optional maxResults and nextToken values provide paging for the results. Multiple skillId values can be used as shown to retrieve skill summary for desired skills only, instead of skills by pages.
Request
GET /v1/skills?vendorId={vendorId}&maxResults={num}&nextToken={token}
or
GET /v1/skills?vendorId={vendorId}&skillId={skillId1}&skillId={skillId2}
Parameters
| Field | Description | Parameter Type | Required |
|---|---|---|---|
vendorId | Unique identifier of the vendor. | Query parameter | Yes |
skillId | Skill identifier for which information is requested. One request can include up to 10 `skillId` values. Parameter `maxResults` and `nextToken` must not be used when `skillId` parameter is in use. | Query parameter | No |
maxResults | Maximum number of results to display per page of listed skills. The value of this parameter must not exceed 50. | Query parameter | No |
nextToken | Continuation token returned in response object of last list skills response. If this is parameter is null, response will include skills from first set. | Query parameter | No |
Response
HTTP/1.1 200 Returns list of skills for the vendor.
Content-Type: application/json+hal
Body
{
"_links": {
"next": {
"href": "/v1/skills?vendorId=MA2384AJJ2NAJ&nextToken=eyJkIjoiVGFmRStsVy9YL1BWczZVaGZTMmt0WTFYajdOK3g1Z0xIS3B1aUxRUHpkQ0xtTmtxVkR6cDIxYk10cUpTTlRUU2phS3ZFK2VGclVlQmQ2NDBlK3ltUDdrRyt1UmVtazBhdmFUTlN5RVd5WXVLTjhhTzhyTERJd1p5VU9ZWXFFb1k5MnF1M3RlaUMrOStyQVY1Z1B0MVhNYkh3L0VycWZvL2k0VzhBNGFSWEwyaVRRVTl3NEJCQ0RlV1lrZ2FXMmlobGpMT2FiYitlNk1IVkVrNHBIak1PZz09IiwiaXYiOiJLN09peDd3TE5MUmxKWVFnYVEwU0R3PT0iLCJ2IjoxfQ=="
},
"self": {
"href": "/v1/skills?vendorId=MA2384AJJ2NAJ"
}
},
"isTruncated": true,
"nextToken": "eyJkIjoiVGFmRStsVy9YL1BWczZVaGZTMmt0WTFYajdOK3g1Z0xIS3B1aUxRUHpkQ0xtTmtxVkR6cDIxYk10cUpTTlRUU2phS3ZFK2VGclVlQmQ2NDBlK3ltUDdrRyt1UmVtazBhdmFUTlN5RVd5WXVLTjhhTzhyTERJd1p5VU9ZWXFFb1k5MnF1M3RlaUMrOStyQVY1Z1B0MVhNYkh3L0VycWZvL2k0VzhBNGFSWEwyaVRRVTl3NEJCQ0RlV1lrZ2FXMmlobGpMT2FiYitlNk1IVkVrNHBIak1PZz09IiwiaXYiOiJLN09peDd3TE5MUmxKWVFnYVEwU0R3PT0iLCJ2IjoxfQ==",
"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.6acdbdf8-8420-440e-823e-aaaaaaaabbbb/stages/development/manifest"
}
},
"skillId": "amzn1.ask.skill.6acdbdf8-8420-440e-823e-aaaaaaaabbbb"
},
{
"lastUpdated": "2017-07-05T21:11:16.947Z",
"asin": "ACIS-QA-xxxxxxx",
"nameByLocale": {
"en-US": "example1"
},
"stage": "live",
"apis": [
"video"
],
"publicationStatus": "PUBLISHED",
"_links": {
"self": {
"href": "/v1/skills/amzn1.ask.skill.81ded88f-0d0a-4612-aaaaaaaabbbb/stages/live/manifest"
}
},
"skillId": "amzn1.ask.skill.81ded88f-0d0a-4612-aaaaaaaabbbb"
}
]
}
| Field | Description |
|---|---|
_links | Hypertext Application Language links to navigate through resources. |
isTruncated | false if there are no more results to return. |
nextToken | when isTruncated is true, it allows to query next page of result. |
asin | Amazon Standard Identification Number, a product identifier. |
skills | List of objects containing summary about skillId and stage |
Exceptions
HTTP/1.1 400 Server cannot process the request due to a client error.
HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.
HTTP/1.1 429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable
Delete a skill
Delete a skill.
Request
DELETE /v1/skills/{skillId}/
Parameters
| Field | Description | Parameter Type | Required |
|---|---|---|---|
skillId | Unique identifier of skill. | Path | Yes |
Response
HTTP/1.1 204 Success. No content.
Exceptions
HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.
HTTP/1.1 403 The operation being requested is not allowed.
HTTP/1.1 404 The resource being requested is not found.
HTTP/1.1 429 Exceed the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
HTTP/1.1 500 Internal Service Error
HTTP/1.1 503 Service Unavailable