Skill Management API

Note: This API is only available to registered Alexa for Residential partners. See Get Started with Alexa for Residential APIs.

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.

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

Response header

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"
   },
   "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
`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.

Request format

GET /v1/skills/enablements?unitId={unitId} 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.	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

Response header

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"
      },
      "status": "ENABLED"
    },
    {
      "skill": {
        "stage": "live",
        "id": "amzn1.ask.skill.skillId2"
      },
      "unit": {
        "id": "amzn1.alexa.unit.unitId"
      },
      "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
`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.

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

Request body example

{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live"
}

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

Response header

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

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

Response header

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.