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.

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

Request format

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

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

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",
  "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

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": "{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.

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.
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment