Skill Management API
Use the Skill Management REST API to enable and disable skills for Alexa Smart Properties (ASP) units, such as rooms.
API endpoint
Based on the country of your organization, set the Host parameter in the request header to one of the following API endpoints.
| Country | Endpoint |
|---|---|
|
CA, US |
|
|
DE, ES, FR, IT, UK |
|
|
JP |
|
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.
Operations
The Skill Management API includes the following operations.
| Description | HTTP method and path |
|---|---|
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
|
Disable skill for unit
Disable a skill for the specified unit.
This operation is available in the following countries.
| Healthcare | Hospitality | Senior Living | Core |
|---|---|---|---|
|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To disable a skill, you make a DELETE request to the /v1/skills/{skillId}/enablements resource.
Request path and header example
DELETE /v1/skills/{skillId}/enablements?unitId={unitId}&stage={stage} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Query |
Filter on the specified unit. |
String |
Yes |
|
|
Query |
Filter on the skill stage. |
String |
No |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 204 No Content.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Skill disabled on the specified unit successfully. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Disable skill for multiple units
Disable the specified skill for a list of units.
This operation is available in the following countries.
| Healthcare | Hospitality | Senior Living | Core |
|---|---|---|---|
|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To disable a skill for multiple units, you make a POST request to the /v1/skills/{skillId}/enablements/batchDelete resource.
Request path and header example
POST /v1/skills/{skillId}/enablements/batchDelete HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"items": [{
"itemId": 0,
"unitId": "amzn1.alexa.unit.101",
"stage": "live"
},
{
"itemId": 1,
"unitId": "amzn1.alexa.unit.102",
"stage": "development"
},
{
"itemId": 2,
"unitId": "amzn1.alexa.unit.103"
}
]
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
List of units on which to disable the specified skill. |
Array of objects |
Yes |
|
|
Unique identifier for the disablement. |
Integer |
Yes |
|
|
Identifies the unit. |
String |
Yes |
|
|
Identifies the skill stage. |
String |
No |
Response
A successful response returns HTTP 202 Accepted.
On error, the response returns the appropriate HTTP status code and includes a response body with a BatchError object.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Skill disabled successfully. |
|
|
Indicates that one or more properties in the request body aren't valid.
|
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found.
|
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Enable skill for unit
Enable the skill on the specified unit. You can provide partition, name-free interaction, and account linking information. If you include account linking information, Alexa attempts to link the accounts.
This operation is available in the following countries.
| Healthcare | Hospitality | Senior Living | Core |
|---|---|---|---|
|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To enable a skill, you make a POST request to the /v1/skills/{skillId}/enablements resource.
Request path and header example
POST /v1/skills/{skillId}/enablements HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body examples
The following example shows a basic skill enablement on a unit without additional details, such as account linking or name-free interaction.
The following example shows a skill enablement on a unit with account linking and partition information.
The following example shows a skill enablement for a skill that supports name-free interaction.
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Identifies the unit. |
String |
Yes |
|
|
Identifies the skill stage. |
String |
Yes |
|
|
Identifies a logical grouping of resources, such as devices, endpoints, or skills. Contains either 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, the Enable skill for unit operation for the same skillId and unitId with a different partitionName value (new, updated, or none) updates the existing enablement with the latest partitionName value. Similarly, if you provide both accountLinkRequest and partitionName in the request for an existing enablement, this operation updates the existing account linking and the partition name values. |
String |
No |
|
|
Account linking information. |
Object |
No |
|
|
Use the same value as the |
String |
Yes |
|
|
OAuth 2.0 authorization code. For details, see Authorization code grant flow. |
String |
Yes |
|
|
Type of account linking request based on OAuth 2.0 authorization request protocols. |
String |
Yes |
|
|
Name-free interaction information. |
Object |
No |
|
|
Locales to enable for name-free interaction. The skill must have an interaction model that supports the locales. Include up to five locales. |
Array of strings |
Yes |
Response
A successful response returns HTTP 201 Created, along with the enablement details for the specified unit.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.
Response body example
{
"skill": {
"stage": "stage",
"id": "{skillId}"
},
"unit": {
"id": "{unitId}"
},
"accountLink": {
"status": "LINKED"
},
"nameFreeInvocation": {
"status": "ENABLED",
"locales": ["en-US"]
},
"status": "ENABLING",
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Skill information. |
Object |
|
|
Identifies the skill. |
String |
|
|
Indicates stage of the skill. |
String |
|
|
Identifies the unit. |
Object |
|
|
ID of the unit. |
String |
|
|
Status of account linking between the your Amazon business account and the your account in your system. Included for skills that require account linking. |
Object |
|
|
Accounting linking status. Set to |
String |
|
|
Name-free interaction information. |
Object |
|
|
Name-free interaction enablement status. Set to |
String |
|
|
(Optional) Locales to enable for name-free interaction. The skill must have an interaction model that supports the locales. Include up to five locales. |
Array of strings |
|
|
Enablement status of the skill.
|
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the enablement results. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Enable skill for multiple units
Enable a skill for multiple units in a single request. You can provide partition, name-free interaction, and account linking information. If you include account linking information, Alexa attempts to link the accounts.
This operation is available in the following countries.
| Healthcare | Hospitality | Senior Living | Core |
|---|---|---|---|
|
US |
US, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To enable a skill on multiple units, you make a POST request to the XYZ resource.
Request path and header example
POST /v1/skills/{skillId}/enablements/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body examples
The following example shows a basic skill enablement on multiple units without additional details, such as account linking or name-free interaction.
The following example shows a skill enablement on multiple units with account linking and partition information.
The following example shows a skill enablement for a skill that supports name-free interaction.
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
List of units on which to enable the specified skill. |
Array of objects |
Yes |
|
|
Unique identifier for the enablement. |
Integer |
Yes |
|
|
Identifies the unit. |
String |
Yes |
|
|
Identifies the skill stage. |
String |
No |
|
|
Identifies a logical grouping of resources, such as devices, endpoints, or skills. Contains either 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, the Enable skill for unit operation for the same skillId and unitId with a different partitionName value (new, updated, or none) updates the existing enablement with the latest partitionName value. Similarly, if you provide both accountLinkRequest and partitionName in the request for an existing enablement, this operation updates the existing account linking and the partition name values. |
String |
No |
|
|
Account linking information. |
Object |
No |
|
|
Use the same value as the |
String |
Yes |
|
|
OAuth 2.0 authorization code. For details, see Authorization code grant flow. |
String |
Yes |
|
|
Type of account linking request based on OAuth 2.0 authorization request protocols. |
String |
Yes |
|
|
Name-free interaction information. |
Object |
No |
|
|
Locales to enable for name-free interaction. The skill must have an interaction model that supports the locales. Include up to five locales. |
Array of strings |
Yes |
Response
A successful response returns HTTP 202 Accepted.
On error, the response returns the appropriate HTTP status code and includes a response body with a BatchError object.
Response body examples
The response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Skill enabled on each unit successfully. |
|
|
Indicates that one or more properties in the request body aren't valid.
|
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found.
|
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get skill enablement for unit
Get the skill enablement record for a specific skill and unit.
This operation is available in the following countries.
| Healthcare | Hospitality | Senior Living | Core |
|---|---|---|---|
|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To get enablement record, you make a GET request to the /v1/skills/{skillId}/enablements resource.
Request path and header example
GET /v1/skills/{skillId}/enablements?unitId={unitId}&stage={stage}&expand={expand} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the skill. |
String |
Yes |
|
|
Query |
Filter on the specified unit. |
String |
Yes |
|
|
Query |
Filter on the skill stage. |
String |
No |
|
|
Query |
Identify an attribute or set of attributes to include in the response. |
String |
No |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK, along with enablement details for the specified skill and unit.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.
Response body examples
The following example shows skill enablement details for the specified skill and unit.
The following example shows skill enablement details for the specified skill and unit, for a request with the expand attribute.
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Skill information. |
Object |
|
|
Identifies the skill. |
String |
|
|
Indicates stage of the skill. |
String |
|
|
Identifies the unit. |
Object |
|
|
ID of the unit. |
String |
|
|
Status of account linking between the your Amazon business account and the your account in your system. |
Object |
|
|
Accounting linking status. |
String |
|
|
Name-free interaction information. |
Object |
|
|
Name-free interaction enablement status. Set to |
String |
|
|
(Optional) Locales to enable for name-free interaction. The skill must have an interaction model that supports the locales. Includes up to five locales for skills that support name-free invocation. |
Array of strings |
|
|
Enablement status of the skill.
|
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains enablement details for the specified skill and unit. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get skill enablement for multiple units
Get the skill enablement record for a specific skill and one or more specified units.
This operation is available in the following countries.
| Healthcare | Hospitality | Senior Living | Core |
|---|---|---|---|
|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
Request
To get enablements, you make a POST request to the /v1/skills/enablements/batchGet resource.
Request path and header example
GET /v1/skills/enablements/batchGet HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The following example requests skill enablement records for four units. The example request includes the expand parameter.
{
"items": [
{
"itemId": 0,
"unitId": "amzn1.alexa.unit.101"
},
{
"itemId": 1,
"unitId": "amzn1.alexa.unit.102"
},
{
"itemId": 2,
"unitId": "amzn1.alexa.unit.103"
},
{
"itemId": 3,
"unitId": "amzn1.alexa.unit.104"
},
],
"expand": ["nameFreeInvocation"],
"paginationContext": {
"maxResults" : 5,
"nextToken": "someToken.1"
}
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
List of requested units. |
Array of objects |
Yes |
|
|
Unique identifier for the request. |
Integer |
Yes |
|
|
Identifies the unit. |
String |
Yes |
|
|
Identify an attribute or set of attributes to include in the response. |
String |
No |
|
|
Include to get the next set of results. |
Object |
No |
|
|
Maximum number of results to return in the response. |
Integer |
No |
|
|
Include from the previous response. |
String |
No |
Response
A successful response returns HTTP 200 OK, along with a list of enabled skills for the specified units.
On error, the response returns the appropriate HTTP status code and includes a response body with a BatchError object.
Response body example
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
List of enabled skills for the specified units. |
Array of objects |
|
|
Identifies the item from the request. |
Integer |
|
|
List of enabled skills for the unit. |
Array of objects |
|
|
Skill information. |
Object |
|
|
Identifies the skill. |
String |
|
|
Indicates stage of the skill. |
String |
|
|
Identifies the unit. |
Object |
|
|
ID of the unit. |
String |
|
|
Status of account linking between the your Amazon business account and the your account in your system. |
Object |
|
|
Accounting linking status. |
String |
|
|
Name-free interaction information. |
Object |
|
|
Name-free interaction enablement status. Set to |
String |
|
|
(Optional) Locales to enable for name-free interaction. The skill must have an interaction model that supports the locales. Includes up to five locales. |
Array of strings |
|
|
Enablement status of the skill.
|
String |
|
|
Indicates whether there are more results to return. |
Object |
|
|
Included when the response is truncated. Use this value in a subsequent request. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains list of enablement status per specified unit. |
|
|
Indicates that one or more properties in the request body aren't valid.
|
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found.
|
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List enabled skills for unit
List the enabled skills for the specified unit.
This operation is available in the following countries.
| Healthcare | Hospitality | Senior Living | Core |
|---|---|---|---|
|
US |
US, UK, FR, CA, IT, DE, ES, JP |
US, UK, FR, CA, IT, DE, ES, JP |
US |
To list skills, you make a GET request to the /v1/skills/enablements resource.
Request path and header example
GET /v1/skills/enablements?unitId={unitId}&expand={expand}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Query |
Filter on the unit. |
String |
Yes |
|
|
Query |
Identify an attribute or set of attributes to include in the response. |
String |
No |
|
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
|
Query |
Token from the previous response. |
String |
No |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK, along with a list of skills enabled for the specified unit.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.
Response body example
The following example lists all enabled skills for the specified unit.
The following example lists all enabled skills for the specified unit for a request with the expand attribute.
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
List of enabled skills for the specified unit. |
Array of objects |
|
|
Skill information. |
Object |
|
|
Identifies the skill. |
String |
|
|
Indicates stage of the skill. |
String |
|
|
Unit to which the skill is associated. |
Object |
|
|
ID of the unit. |
String |
|
|
Status of account linking between the your Amazon business account and the your account in your system. |
Object |
|
|
Accounting linking status. |
String |
|
|
Enablement status of the skill.
|
String |
|
|
(Optional) Name-free interaction information. Included in the response if you included the |
Object |
|
|
Name-free interaction enablement status. Set to |
String |
|
|
(Optional) Locales to enable for name-free interaction. The skill must have an interaction model that supports the locales. Includes up to five locales. |
Array of strings |
|
|
Indicates whether there are more results to return. |
Object |
|
|
Included when the response is truncated. Use this value in a subsequent request. |
String |
Object definitions
The Skill Management API defines the following object definitions.
BatchError object
The BatchError object defines the error code and description included in the response when an error occurs during a batch operation. The itemId represents the item from the request that failed.
The following example shows the response body.
{
"errors": [
{
"itemId": 0,
"status": 400,
"errorCode" : "INVALID_PRINCIPAL_ID",
"errorDescription": "Invalid principalId specified."
},
{
"itemId": 3,
"status": 400,
"errorCode" : "REQUEST_LIMIT_EXCEEDED",
"errorDescription": "The number of request items in the batch request exceeds the limit (50)."
}
]
}
The BatchError object defines the following properties.
| Property | Description | Type |
|---|---|---|
|
|
(Optional) Identifies the request item that failed. |
Integer |
|
|
HTTP status code. |
String |
|
|
Type of error that occurred. |
String |
|
|
Human-readable error message. 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 |
Error object
The Error object defines the error type and message included in the response when an error occurs.
The following example shows the response body.
{
"type": "BAD_REQUEST",
"message": "The request is malformed or is missing any required parameters."
}
The Error object defines the following properties.
| Property | Description | Type |
|---|---|---|
|
|
Type of error that occurred. |
String |
|
|
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 |
Related topics
Last updated: Oct 31, 2024