Deine Alexa Konsolen
?
Support
Vielen Dank für Ihren Besuch. Diese Seite ist momentan nur auf Englisch verfügbar. Wir arbeiten an der deutschen Version. Vielen Dank für Ihr Verständnis.

Skill Operations (Skill Management API)

This reference describes all API operations related to the skill resource. The API's endpoint is https://api.amazonalexa.com. Each API request must have an Authorization header whose value should be the access token retrieved from Login with Amazon.

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

See: Alexa Skills Kit Command Line Interface and Alexa Skill Management API Overview

Get Skill Information

Gets the manifest for a specified skill.

Request

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

Parameters

FieldDescriptionParameter TypeRequired
skillIdUnique identifier of skill.PathYes
stageIndicates stage of the skill. Accepted values are development and live (case sensitive).PathYes

Response

HTTP/1.1 200 OK

Headers

ETag: <etag_value>

Body

A manifest object.

Exceptions

HTTP/1.1 303 See Other
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
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

Headers

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

Body

{
  "skillId": "{skillId}"
}

Exceptions

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 429 Too Many Requests
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

FieldDescriptionParameter TypeRequired
skillIdUnique identifier of skill.PathYes
stageStage of the skill. Accepted value is development (case sensitive).PathYes

Headers

If-Match: <etag_value>

Body

manifest object as described in Skill Manifest

Response

HTTP/1.1 202 Accepted

Headers

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

Exceptions

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict
HTTP/1.1 412 Precondition Failed
HTTP/1.1 429 Too Many Requests
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 a specified skill's resources and optionally filter status by resource to see if that resource has been successfully built.

Request

GET /v1/skills/{skillId}/status?resource=name1&resource=name2

Each resource parameter is an optional filter.

Parameters

FieldDescriptionParameter TypeRequired
skillIdUnique identifier of skill.PathYes
resourceAccepted values are interactionModel and/or manifest.Query parameterNo

Response

The response returns the status for the skill resource and specified sub-resources.

HTTP/1.1 200 OK

Body

Here is how a sample response looks like:

{
    "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."
                }
            ]
        }
    },
    "interactionModel": {
        "en-US": {
            "eTag": "agasguhq34894hjk",
            "lastUpdateRequest": {
                "status": "SUCCEEDED"
            },
        },
        "en-GB": {
            "eTag": "ahsadfahq34894hjk",
            "lastUpdateRequest": {
                "status": "IN_PROGRESS"
            },
        }
    }
}

Exceptions

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
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

FieldDescriptionParameter TypeRequired
vendorIdUnique identifier of the vendor.Query parameterYes
skillIdSkill 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 parameterNo
maxResultsMaximum number of results to display per page of listed skills. The value of this parameter must not exceed 50.Query parameterNo
nextTokenContinuation token returned in response object of last list skills response. If this is parameter is null, response will include skills from first set.Query parameterNo

 

Response

HTTP/1.1 200 OK
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",
            "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"
        }
    ]
}
FieldDescription
_linksHypertext Application Language links to navigate through resources.
isTruncatedfalse if there are no more results to return.
nextTokenwhen isTruncated is true, it allows to query next page of result.
skillsList of objects containing summary about skillId and stage

Exceptions

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 429 Too Many Requests
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

FieldDescriptionParameter TypeRequired
skillIdUnique identifier of skill.PathYes

Response

HTTP/1.1 204 NoContent

Exceptions

HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Service Error
HTTP/1.1 503 Service Unavailable