Skill Management API
Use the Skill Management API to manage skills for Alexa for Residential units such as homes.
Get skill enablement record
Call GET /v1/skills/{skillId}/enablements?unitId={unitId}
to get the skill enablement record for a specific skill for a unit.
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 |
stage |
Skill stage: development , certification , or live . If present, the stage must be enabled. |
Enum |
No |
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 . If present, the stage must be enabled. |
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. The accountLink object is present only for skills that support account linking. |
String. Either LINKED or NOT_LINKED . |
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 all skill enablements
Call GET /v1/skills/enablements?unitId={unitId}
to get a list of all skill enablements for a unit.
GET /v1/skills/enablements?unitId={unitId}&stage={stage}&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 |
stage |
Skill stage: development , certification , or live . If present, the stage must be enabled. |
Enum |
No |
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 |
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 . If present, the stage must be enabled. |
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. The accountLink object is present only for skills that support account linking. |
String. Either LINKED or NOT_LINKED . |
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
Call POST /v1/skills/{skillId}/enablements
to enable a skill for a unit.
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",
"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 , certification , or live . If present, the stage must be enabled. |
Enum |
No |
accountLinkRequest |
Account linking request information. |
Object |
Yes, for skills that support account linking |
accountLinkRequest.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, for skills that support account linking |
accountLinkRequest.authCode |
A third-party cloud's OAuth 2.0 "Authorization Code." This value is required to perform account linking. For details, see Authorization code grant flow. |
String |
Yes, for skills that support account linking |
accountLinkRequest.type |
The type of account linking request, which is based on OAuth 2.0 authorization request protocols. |
String. Must be AUTH_CODE . |
Yes, for skills that support account linking |
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 , certification , or live . If present, the stage must be enabled. |
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. The accountLink object is present only for skills that support account linking. |
String. Either LINKED or NOT_LINKED . |
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
Call DELETE /v1/skills/{skillId}/enablements?unitId={unitId}
to disable a skill for a unit.
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 |
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 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. |