Skill Operations, v0

Note: Sign in to the developer console to build or publish your skill.

Warning: You are viewing the SMAPI v0 API documentation. The current version of SMAPI is Version 1. Switch to v1 to view the latest documentation.

This reference describes all API operations related to the skill resource. Each request must have an Authorization header whose value should be the access token retrieved from Login with Amazon.

The ASK CLI also uses the Skill Management API, but through a command line interface.

See: Alexa Skills Kit Command Line Interface (ASK CLI) Overview

Get Skill Information

Gets the skill manifest for a specified skill.

Request

GET /v0/skills/{skillId}

Field	Description	Parameter Type	Required
`skillId`	Unique identifier of skill.	Path	Yes

Response

HTTP/1.1 200 OK

Body

A skillManifest object as described in Skill Manifest Schema.

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 /v0/skills

Body

The body includes the vendorId, and a manifest object as described in Skill Manifest Schema, as shown in the following example.

{
    "vendorId": "MT25O3ZVSAXZOAX",
    "skillManifest": {
        "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

Content-Type: application/json
HTTP/1.1 202 Accepted

Headers

Location: <Returns a relative URL to track the status>

Body

{
  "skillId": "{skillId}"
}

Field	Description	Parameter Type
`skillId`	Unique identifier of newly created skill.	Response Header Response Body Element

HTTP/1.1 400

Server cannot process the request due to a client error.

HTTP/1.1 401 Unauthorized

HTTP/1.1 500 Internal Server Error

Update an existing skill

Updates the skill manifest associated with the specified skill ID.

Request

PUT /v0/skills/{skillId}

Body

skillManifest object as described in Skill Manifest Schema.

Parameter Description

Field	Description	Parameter Type	Required
`skillId`	Unique identifier of skill.	Path	Yes

Response

HTTP/1.1 202 Accepted

Headers

Location: <Returns a relative URL to track the status>

HTTP/1.1 400 Server cannot process the request due to a client error.

HTTP/1.1 401 Unauthorized

HTTP/1.1 404 Not Found

HTTP/1.1 500 Internal Server Error

Get the status of a skill

Request

GET /v0/skills/{skillId}/status

Parameter Description

Field	Description	Parameter Type	Required
`skillId`	Unique identifier of skill.	Path	Yes

Response

HTTP/1.1 200 OK

Response body for a successful build of the model. Checking the status of a skill.

{
    "manifest": {
        "lastModified": {
            "time": "2017-09-05T05:36:41.530Z",
            "status": "SUCCESSFUL"
        }
    }
}

The status values can also be FAILED and IN_PROGRESS.

HTTP/1.1 400 Server cannot process the request due to a client error.

HTTP/1.1 401 Unauthorized

HTTP/1.1 404 Not Found

HTTP/1.1 500 Internal Server Error

List skills

List the skills for the specified vendorId, which is a mandatory parameter. The optional maxResults and nextToken values provide paging for the results.

Request

GET /v0/skills?vendorId={vendorId}&maxResults={num}&nextToken={token}

Parameter Description

Field	Description	Parameter Type
`vendorId`	Unique identifier of the vendor.	string
`maxResults`	Maximum number of results to display per page of listed skills.	integer
`nextToken`	Encrypted value of the token.	string

Response

HTTP/1.1 200 OK

Response body lists the skills.

{
    "_links": {
            "next": {
                "href": "/v0/skills?vendorId=MA2384AJJ2NAJ&nextToken=eyJkIjoiVGFmRStsVy9YL1BWczZVaGZTMmt0WTFYajdOK3g1Z0xIS3B1aUxRUHpkQ0xtTmtxVkR6cDIxYk10cUpTTlRUU2phS3ZFK2VGclVlQmQ2NDBlK3ltUDdrRyt1UmVtazBhdmFUTlN5RVd5WXVLTjhhTzhyTERJd1p5VU9ZWXFFb1k5MnF1M3RlaUMrOStyQVY1Z1B0MVhNYkh3L0VycWZvL2k0VzhBNGFSWEwyaVRRVTl3NEJCQ0RlV1lrZ2FXMmlobGpMT2FiYitlNk1IVkVrNHBIak1PZz09IiwiaXYiOiJLN09peDd3TE5MUmxKWVFnYVEwU0R3PT0iLCJ2IjoxfQ=="
            },
            "self": {
                "href": "/v0/skills?vendorId=MA2384AJJ2NAJ"
            }
    },
    "isTruncated": true,
    "nextToken": "eyJkIjoiVGFmRStsVy9YL1BWczZVaGZTMmt0WTFYajdOK3g1Z0xIS3B1aUxRUHpkQ0xtTmtxVkR6cDIxYk10cUpTTlRUU2phS3ZFK2VGclVlQmQ2NDBlK3ltUDdrRyt1UmVtazBhdmFUTlN5RVd5WXVLTjhhTzhyTERJd1p5VU9ZWXFFb1k5MnF1M3RlaUMrOStyQVY1Z1B0MVhNYkh3L0VycWZvL2k0VzhBNGFSWEwyaVRRVTl3NEJCQ0RlV1lrZ2FXMmlobGpMT2FiYitlNk1IVkVrNHBIak1PZz09IiwiaXYiOiJLN09peDd3TE5MUmxKWVFnYVEwU0R3PT0iLCJ2IjoxfQ==",
    "skills": [
        {
            "lastUpdated": "2017-07-11T19:29:57.120Z",
            "nameByLocale": {
                "en-US": "example"
            },
            "stage": "development",
            "_links": {
                "self": {
                    "href": "/v0/skills/amzn1.ask.skill.6acdbdf8-8420-440e-823e-aaaaaaaabbbb"
                }
            },
            "skillId": "amzn1.ask.skill.6acdbdf8-8420-440e-823e-aaaaaaaabbbb"
        },
        {
            "lastUpdated": "2017-07-05T21:11:16.947Z",
            "nameByLocale": {
                "en-US": "example1"
            },
            "stage": "live",
            "_links": {
                "self": {
                    "href": "/v0/skills/amzn1.ask.skill.81ded88f-0d0a-4612-aaaaaaaabbbb"
                }
            },
            "skillId": "amzn1.ask.skill.81ded88f-0d0a-4612-aaaaaaaabbbb"
        }
    ]
}

HTTP/1.1 400 Server cannot process the request due to a client error.

HTTP/1.1 401 Unauthorized

HTTP/1.1 500 Internal Server Error

Delete a skill

Delete a skill.

Request

DELETE /v0/skills/{skillId}/

Parameter Description

Field	Description	Parameter Type	Required
`skillId`	Unique identifier of skill.	Path	Yes

Response

HTTP/1.1 204 NoContent

HTTP/1.1 400 Bad Request

Body:

{
    "message": "Cannot delete the skill because it has a cert/live stage. Please follow our documentation for next steps."
    "type": "BadRequest"
}

HTTP/1.1 500 Internal Service Error

{
    "message": // error message (String)
    "type": "InternalError"
}

Was this page helpful?

Provide feedback

Last updated: Mar 30, 2022