Skill Management API

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

Note: This API is only available to registered Alexa Smart Properties core partners. See Get Started with Alexa Smart Properties Core APIs.

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	`GET /v1/skills/{skillId}/enablements?unitId={unitId}`
List skill enablements for a unit	`GET /v1/skills/enablements?unitId={unitId}`
Enable a skill for a unit	`POST /v1/skills/{skillId}/enablements`
Disable a skill for a unit	`DELETE /v1/skills/{skillId}/enablements?unitId={unitId}`
Enable a skill for multiple units	`POST /v1/skills/{skillId}/enablements/batch`

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
`skillId`	Skill ID, in the format `"amzn1.alexa.skill.{id}"`.	String	Yes

Request query parameters

Field	Description	Type	Required
`unitId`	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
`X-Amzn-RequestId`	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`	Skill stage: `development`, `certification`, or `live`.	Enum
`skill.id`	Unique identifier for a skill.	String
`unit.id`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String
`accountLink.status`	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
`type`	Error type.	String
`message`	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
`unitId`	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
`X-Amzn-RequestId`	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
`paginationContext`	Context contains all data needed to control pagination.	Object
`paginationContext.nextToken`	Token used to retrieve subsequent data. This token doesn't exist if there are no extra records.	String
`items`	List of skill enablements.	List (Set)
`skill.stage`	Skill stage: `development`, `certification`, or `live`.	Enum
`skill.id`	Unique identifier for a skill.	String
`unit.id`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String
`accountLink.status`	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
`type`	Error type.	String
`message`	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
`skillId`	Skill ID, in the format `"amzn1.alexa.skill.{id}"`.	String	Yes

Request body example

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. 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

AccountLinkRequest object schema

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
`X-Amzn-RequestId`	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`	Skill stage: `development` or `live`.	Enum
`skill.id`	Unique identifier for a skill, in the format `"amzn1.ask.skill.{id}"`.	String
`unit.id`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String
`accountLink.status`	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
`type`	Error type.	String
`message`	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
`unitId`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes
`skillId`	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
`X-Amzn-RequestId`	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
`type`	Error type.	String
`message`	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
`skillId`	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. 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
`X-Amzn-RequestId`	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
`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	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: • The `skillId` is missing or invalid. • The `unitId` is missing or invalid. • The requested `skillId` and `stage` combination couldn't be found. • The number of request items exceeds the limit.
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.