Skill Management API

Use the Skill Management API to manage skills for Alexa for Hospitality units such as rooms.

Get skill enablement record for a unit

Call GET /v1/skills/{skillId}/enablements?unitId={unitId} to get the skill enablement record for a specific skill for a unit.

Request format

GET /v1/skills/{skillId}/enablements?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request path parameters

Field Description Type Required
skillId The skill ID, in the format "amzn1.alexa.skill.{id}". String Yes

Request query parameters

Field Description Type Required
unitId The unit ID, in the format "amzn1.alexa.unit.did.{id}". String Yes

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required
X-Amzn-RequestId Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. String Yes

Response body example

{
   "skill": {
      "stage": "stage",
      "id": "amzn1.ask.skill.skillId"
   },
   "unit": {
      "id": "amzn1.alexa.unit.unitId"
   },
   "accountLink": {
      "status": "LINKED"
  },
   "status": "ENABLED",
}

Response body parameters

Field Description Type
skill.stage Skill stage: development, certification, or live. Enum
skill.id The unique identifier for a skill. String
unit.id The unit ID, in the format "amzn1.alexa.unit.did.{id}". String
accountLink.status The current account linking status between the user's Amazon account and their account in your service: LINKED or NOT_LINKED. For skills that don't support account linking, NOT_LINKED is returned. String
status Skill enablement status: ENABLING or ENABLED. Enum

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field Description Type Required
type The error type. String No
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status Code Name Description
200 OK The request succeeded.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing, expired, or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The requested enablement wasn't found.
429 Too many requests Request has been throttled.
500 Internal Server Error The request couldn't be handled because of an internal service error.
503 Service Unavailable Service is temporarily unavailable.

List skill enablements for a unit

Call GET /v1/skills/enablements?unitId={unitId} to get a list of all skill enablements for a unit.

Request format

GET /v1/skills/enablements?unitId={unitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request query parameters

Field Description Type Required
unitId The unit ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
nextToken Continuation token returned in response object of previous list skill enablements response. For details, see Handling Pagination in Query Results. String No
maxResults Maximum number of results to display. The value of this parameter must be between 1 and 10. Default is 10. Integer No

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required
X-Amzn-RequestId Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. String Yes

Response body example

{
  "paginationContext": {
    "nextToken": "amzn1.ask.skill.tokenUUID"
  },
  "items": [
    {
      "skill": {
        "stage": "live",
        "id": "amzn1.ask.skill.skillId1"
      },
      "unit": {
        "id": "amzn1.alexa.unit.unitId"
      },
      "accountLink": {
        "status": "NOT_LINKED"
      },
      "status": "ENABLED"
    },
    {
      "skill": {
        "stage": "live",
        "id": "amzn1.ask.skill.skillId2"
      },
      "unit": {
        "id": "amzn1.alexa.unit.unitId"
      },
      "accountLink": {
        "status": "NOT_LINKED"
      },
      "status": "ENABLED",
    }
  ]
}

Response body parameters

Field Description Type
paginationContext The context contains all data needed to control pagination. Object
paginationContext.nextToken The token used to retrieve subsequent data. This token doesn't exist if there are no extra records. String
items A list of skill enablements. List (Set)
skill.stage Skill stage: development, certification, or live. Enum
skill.id The unique identifier for a skill. String
unit.id The unit ID, in the format "amzn1.alexa.unit.did.{id}". String
accountLink.status The current account linking status between the user's Amazon account and their account in your service: LINKED or NOT_LINKED. The accountLink object is present only for skills that support account linking. String
status Skill enablement status: ENABLING or ENABLED. Enum

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field Description Type Required
type The error type. String No
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status Code Name Description
200 OK The request succeeded.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing, expired, or invalid.
403 Forbidden The user doesn't have permission to access the service.
429 Too many requests Request has been throttled.
500 Internal Server Error The request couldn't be handled because of an internal service error.
503 Service Unavailable Service is temporarily unavailable.

Enable a skill for a unit

Call POST /v1/skills/{skillId}/enablements to enable a skill for a unit.

Request format

POST /v1/skills/{skillId}/enablements HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
skillId The skill ID, in the format "amzn1.alexa.skill.{id}". String Yes

Request body example

{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live",
  "partitionName": "Home101-Kitchenette",
  "accountLinkRequest": {
    "redirectUri": "https://example.com",
    "authCode": "3pauthcode",
    "type": "AUTH_CODE"
  }
}

Request body parameters

Field Description Type Required

unitId

The unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

Yes

stage

Skill stage: development or live.

Enum

Yes

partitionName

A partition name is an identifier for a logical grouping of resources such as devices, endpoints, or skills. This parameter is a string containing a single partition name or a comma-separated list of partition names. A partition name is a single nonempty string that can contain alphanumeric characters and hyphens but not whitespace.
For example, "Room-101" and "Room101, Room202" are valid values for this parameter. The following aren't valid values: "" (empty list), "Room101, ,Room202" (not properly comma-separated), "Room 101" (contains whitespace).
Note: If there is an existing enablement for a given skillId and unitId, a POST enablement request for the same skillId and unitId with a different partitionName value (new, updated, or none) updates the existing enablement with the latest partitionName value.
Note: If you provide both accountLinkRequest and partitionName in a POST enablement request for an existing enablement, the API call updates the existing account linking and the partition name.

String

No

accountLinkRequest

Account linking request information, as an AccountLinkRequest object.

Object

Yes, for skills that support account linking

Field Description Type Required

redirectUri

The redirect_uri parameter that was included in the authorization request to your OAuth 2.0 server to obtain the user's authorization code. This enables Amazon to retrieve access tokens from your token server. This URL must be opaque to Amazon.

String

Yes

authCode

An OAuth 2.0 authorization code. This value is required to perform account linking. For details, see Authorization code grant flow.

String

Yes

type

The type of account linking request, which is based on OAuth 2.0 authorization request protocols. Currently the only supported value is AUTH_CODE.

String

Yes

Success response header

HTTP/1.1 201 Created
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required
X-Amzn-RequestId Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. String Yes

Response body example


{
  "skill": {
    "stage": "stage",
    "id": "{skillId}"
  },
  "unit": {
    "id": "{unitId}"
  },
  "accountLink": {
    "status": "LINKED"
  },
  "status": "ENABLING",
}

Response body parameters

Field Description Type
skill.stage Skill stage: development or live. Enum
skill.id The unique identifier for a skill, in the format "amzn1.ask.skill.{id}". String
unit.id The unit ID, in the format "amzn1.alexa.unit.did.{id}". String
accountLink.status The current account linking status between the user's Amazon account and their account in your service: LINKED or NOT_LINKED. The accountLink object is present only for skills that support account linking. String
status Skill enablement status: ENABLING or ENABLED. Enum

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field Description Type Required
type The error type. String No
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status Code Name Description
201 Created The skill enablement was successfully created.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing, expired, or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The requested skill ID or unit ID can't be found.
429 Too many requests Request has been throttled.
500 Internal Server Error The request couldn't be handled because of an internal service error.
503 Service Unavailable Service is temporarily unavailable.

Disable a skill for a unit

Call DELETE /v1/skills/{skillId}/enablements?unitId={unitId} to disable a skill for a unit.

Request format

DELETE /v1/skills/{skillId}/enablements?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request parameters

Field Description Type Required
unitId The unit ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
skillId The skill ID, in the format "amzn1.alexa.skill.{id}". String Yes
stage Skill stage: development, certification, or live. If present, the stage must be enabled. Enum No

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required
X-Amzn-RequestId Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. String Yes

Success response parameters

None.

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field Description Type Required
type The error type. String No
message The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status Code Name Description
204 No content The skill enablement was successfully deleted.
400 Bad Request The request is malformed or is missing one or more required parameters.
401 Unauthorized The access token is missing, expired, or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The requested skill ID or unit ID can't be found.
429 Too many requests Request has been throttled.
500 Internal Server Error The request couldn't be handled because of an internal service error.
503 Service Unavailable Service is temporarily unavailable.

Enable a skill for multiple units

Call POST /v1/skills/{skillId}/enablements/batch to enable a skill for multiple units in a single request.

Request format

POST /v1/skills/{skillId}/enablements/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
skillId The skill ID, in the format "amzn1.alexa.skill.{id}". String Yes

Request body example

The following example shows the body for a request to enable a skill for two units. The body contains two items, one for each unit.

{
   "items": [
         {
             "itemId": 0,
             "unitId": "amzn1.alexa.unit.unitId1",
             "stage": "live",
             "partitionName": "10-101", // Optional
             "accountLinkRequest": { // Optional, only for skills that support account linking
                 "redirectUri": "https://redirecturi.com",
                 "authCode": "3pauthcode1",
                 "type": "AUTH_CODE"
             }
         },
         {
             "itemId": 1,
             "unitId": "amzn1.alexa.unit.unitId2",
             "stage": "live",
             "partitionName": "11-101,11-102,11-103" // Optional
         }
     ]
}

Request body parameters

Field Description Type Required

items

A list of request items. Each item represents an enablement request for a single unit.

Array

Yes

itemId

A unique identifier for the request item. Must be unique within the request.

Integer

Yes

unitId

The unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

Yes

stage

Skill stage: development, certification, or live.

Enum

Yes

partitionName

A partition name is an identifier for a logical grouping of resources such as devices, endpoints, or skills. This parameter is a string containing a single partition name or a comma-separated list of partition names.
For example, "Room101" and "Room101, Room202" are valid values for this parameter. The following are not valid values: "" (empty list), "Room101, ,Room202" (not properly comma-separated), "Room 101" (contains whitespace).
Note: If there is an existing enablement for a given skillId and unitId, the next POST enablement request for the same skillId and unitId with a different partitionName value (new, updated or none) updates the existing enablement with the latest partitionName value.

String

No

accountLinkRequest

Account linking request information, as an AccountLinkRequest object.

Object

Yes, for skills that support account linking

Success response

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required
X-Amzn-RequestId Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. String Yes

Success response parameters

None.

Error response header

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response body examples

The following example shows an error response body for an entire request, not for individual items.

{
    "errors": [
        {
            "status": 401,
            "erorrCode": "INVALID_LWA_TOKEN",
            "errorDescription": "The access token is invalid."
        }
    ]
}

The following example shows an error response body for individual items.

{
    "errors": [
        {
            "itemId": 0,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "unitId is missing or invalid"
        },
        {
            "itemId": 20,
            "status": 403,
            "errorCode": "FORBIDDEN",
            "errorDescription": "The operator doesn't have the right permission to perform the operation."
        }
    ]
}

Error response parameters

Field Description Type Required

errors

A list of error responses, one for each request item.

Array

Yes

itemId

The identifier for the request item. Optional if the error response is for the entire request and not for individual items.

String

No

status

The response status code per request or request item.

Integer

Yes

errorCode

The error code for the error.

Enum

Yes

errorDescription

A description of the error.

String

Yes

HTTP response codes

Status code errorDescription value Scope

202

"Accepted"

Request

400

"skillId is missing or invalid"

Request

400

"unitId is missing or invalid"

Request or Request item

400

"The requested skillId and stage combination could not be found. Please verify that your inputs are correct."

Request item

400

"The number of request items exceeds the limit."

Request

401

"The access token is invalid."

Request

403

"The operator doesn't have the right permission to perform the operation."

Request item

429

"Exceeded the permitted request limit."

Request

500

"Internal Server Error."

Request

503

"Service Unavailable."

Request