Skill Management API
Use the Skill Management API to manage skills for Alexa Smart Properties core units such as rooms.
Operations
The Skill Management API includes the following operations.
Description | HTTP method and path |
---|---|
| |
| |
| |
| |
|
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
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 |
---|---|---|---|
|
Skill ID, in the format |
String |
Yes |
Request query parameters
Field | Description | Type | Required |
---|---|---|---|
|
Unit ID, in the format |
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 |
---|---|---|
|
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
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: |
Enum |
|
Unique identifier for a skill. |
String |
|
Unit ID, in the format |
String |
|
Current account linking status between the user's Amazon account and their account in your service: |
String |
|
Skill enablement status: |
Enum |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type |
---|---|---|
|
Error type. |
String |
|
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 |
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 skill ID or unit ID can't be found. |
429 |
Too many requests |
The request is throttled. |
500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. |
503 |
Service Unavailable |
The server 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 |
---|---|---|---|
|
Unit ID, in the format |
String |
Yes |
|
Continuation token returned in response object of previous list skill enablements response. For details, see Handling Pagination in Query Results. |
String |
No |
|
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 |
---|---|---|
|
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
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 |
---|---|---|
|
Context contains all data needed to control pagination. |
Object |
|
Token used to retrieve subsequent data. This token doesn't exist if there are no extra records. |
String |
|
List of skill enablements. |
List (Set) |
|
Skill stage: |
Enum |
|
Unique identifier for a skill. |
String |
|
Unit ID, in the format |
String |
|
Current account linking status between the user's Amazon account and their account in your service: |
String |
|
Skill enablement status: |
Enum |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type |
---|---|---|
|
Error type. |
String |
|
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 |
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. |
429 |
Too many requests |
The request is throttled. |
500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. |
503 |
Service Unavailable |
The server 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 |
---|---|---|---|
|
Skill ID, in the format |
String |
Yes |
Request body example
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
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 |
|
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
HTTP/1.1 201 Created
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type |
---|---|---|
|
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Response body example
{
"skill": {
"stage": "stage",
"id": "{skillId}"
},
"unit": {
"id": "{unitId}"
},
"accountLink": {
"status": "LINKED"
},
"status": "ENABLING",
}
Response body parameters
Field | Description | Type |
---|---|---|
|
Skill stage: |
Enum |
|
Unique identifier for a skill, in the format |
String |
|
Unit ID, in the format |
String |
|
Current account linking status between the user's Amazon account and their account in your service: |
String |
|
Skill enablement status: |
Enum |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type |
---|---|---|
|
Error type. |
String |
|
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 |
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 |
The request is throttled. |
500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. |
503 |
Service Unavailable |
The server 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 |
---|---|---|---|
|
Unit ID, in the format |
String |
Yes |
|
Skill ID, in the format |
String |
Yes |
|
Skill stage: |
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 |
---|---|---|
|
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Success response parameters
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type |
---|---|---|
|
Error type. |
String |
|
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 |
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 |
The request is throttled. |
500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. |
503 |
Service Unavailable |
The server 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 |
---|---|---|---|
|
Skill ID, in the format |
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
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 |
|
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 |
---|---|---|
|
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
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 | Name | Description |
---|---|---|
202 |
Accepted |
The request was accepted. |
400 |
Bad Request |
The request is malformed or is missing one or more required parameters. Example reasons:
|
401 |
Unauthorized |
The access token is missing, expired, or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
429 |
Too many requests |
The request is throttled. |
500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. |
503 |
Service Unavailable |
The server is temporarily unavailable. |