Skill Management API
Use the Skill Management API to manage skills for Alexa Smart Properties for hospitality units such as rooms.
Get a 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
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.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
Host
value is the same as the Host
value in the request.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
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.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
Host
value is the same as the Host
value in the request.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
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.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": "Room101-Kitchenette",
"accountLinkRequest": {
"redirectUri": "https://example.com",
"authCode": "3pauthcode",
"type": "AUTH_CODE"
}
}
Request body parameters
Field | Description | Type | Required |
---|---|---|---|
|
The unit ID, in the format |
String |
Yes |
|
Skill stage: |
Enum |
Yes |
|
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. Note: If there is an existing enablement for a given |
String |
No |
|
Account linking request information, as an AccountLinkRequest object. |
Object |
Yes, for skills that support account linking |
AccountLinkRequest object schema
Field | Description | Type | Required |
---|---|---|---|
|
The |
String |
Yes |
|
An OAuth 2.0 authorization code. This value is required to perform account linking. For details, see Authorization code grant flow. |
String |
Yes |
|
The type of account linking request, which is based on OAuth 2.0 authorization request protocols. Currently the only supported value is |
String |
Yes |
Success response header
Host
value is the same as the Host
value in the request.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
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.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
Host
value is the same as the Host
value in the request.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
Host
to one of the following, depending on the region of your organization: api.amazonalexa.com
or api.eu.amazonalexa.com
.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 |
---|---|---|---|
|
A list of request items. Each item represents an enablement request for a single unit. |
Array |
Yes |
|
A unique identifier for the request item. Must be unique within the request. |
Integer |
Yes |
|
The unit ID, in the format |
String |
Yes |
|
Skill stage: |
Enum |
Yes |
|
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. Note: If there is an existing enablement for a given |
String |
No |
|
Account linking request information, as an AccountLinkRequest object. |
Object |
Yes, for skills that support account linking |
Success response
Host
value is the same as the Host
value in the request.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 |
---|---|---|---|
|
A list of error responses, one for each request item. |
Array |
Yes |
|
The identifier for the request item. Optional if the error response is for the entire request and not for individual items. |
String |
No |
|
The response status code per request or request item. |
Integer |
Yes |
|
The error code for the error. |
Enum |
Yes |
|
A description of the error. |
String |
Yes |
HTTP response codes
Status code | errorDescription value | Scope |
---|---|---|
202 |
|
Request |
400 |
|
Request |
400 |
|
Request or Request item |
400 |
|
Request item |
400 |
|
Request |
401 |
|
Request |
403 |
|
Request item |
429 |
|
Request |
500 |
|
Request |
503 |
|
Request |