Skill Management API

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}&stage={stage} 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 enablement is returned only if the specified stage is 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 enablement is returned only if the specified stage is 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}
{
    "code": "{ErrorCode}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field Description Type Required
code The error code for the error. Integer Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to 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/{skillId}/enablements?unitId={unitId}&stage={stage} 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}" for which roles are to be fetched. String Yes
stage Skill stage: development, certification, or live. If present, the enablement is returned only if the specified stage is 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 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 if returned in response. It will not 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 enablement is returned only if the specified stage is 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}
{
    "code": "{ErrorCode}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field Description Type Required
code The error code for the error. Integer Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to 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 enablement is returned only if the specified stage is 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 enablement is returned only if the specified stage is 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}
{
    "code": "{ErrorCode}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field Description Type Required
code The error code for the error. Integer Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to 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 cannot 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}&stage={stage} 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 enablement is returned only if the specified stage is 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}
{
    "code": "{ErrorCode}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field Description Type Required
code The error code for the error. Integer Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to 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 cannot 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.