Skill Management API


Use the Skill Management API to manage skills for Alexa Smart Properties units such as rooms.

API endpoint

In the request header, set Host to one of the following, depending on the region of your organization:

Country Endpoint

CA, US

https://api.amazonalexa.com

DE, ES, FR, IT, UK

https://api.eu.amazonalexa.com

JP

https://api.fe.amazonalexa.com

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

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}

Get skill enablement for multiple units

POST /v1/skills/enablements/batchGet

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

Disable a skill for multiple units

POST /v1/skills/{skillId}/enablements/batchDelete

Get skill enablements

The following operations allow you to get information about a skills enabled on a unit or multiple units.

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.

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 format examples

List skill enablement and account linking details only

The following example lists the skill enablement record for the unit. By default, the results aren't expanded with name-free interaction details.

This call only returns the enablement record for a given skill. To get all skill enablements for a unit, see List skill enablements for a unit.

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

GET /v1/skills/{skillId}/enablements?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Include name-free interaction details

This example shows how to include the name-free interaction details for the enablement, use the expand=nameFreeInvocation parameter.

GET /v1/skills/{skillId}/enablements?unitId={unitId}&expand=nameFreeInvocation HTTP/1.1

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

expand

An attribute (or set of attributes) to include in the response. Current values supported: nameFreeInvocation

String

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 parameters

Field Description Type

skill.stage

Skill stage: development 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

nameFreeInvocation.status

Name-free interaction enablement status: DISABLED or ENABLED. For skills that don't support name-free interaction, DISABLED is returned.

Enum

nameFreeInvocation.locales

Available locales for name-free interaction on the unit: en-US, es-US, en-CA, fr-CA, en-GB, fr-FR, es-ES, it-IT, de-DE. This value is only returned if nameFreeInvocation.status is ENABLED. Limit of 5 locales.

Array

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.

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 operator doesn't have the right 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.

500

Internal Server Error

The request couldn't be handled because of an internal service error when retrieving NameFreeInvocation.

503

Service Unavailable

The server is temporarily unavailable.

503

Service Unavailable

The server is temporarily unavailable for fetching NameFreeInvocation.

List skill enablements for a unit

Call GET /v1/skills/enablements?unitId={unitId} to get a list of all skill enablements for a 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 format examples

List skill enablement and account linking details only

The following example lists all skill enablement records for a unit. By default, the results aren't expanded with name-free interaction details.

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

GET /v1/skills/enablements?unitId={unitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Include name-free interaction details

This example shows how to include the name-free interaction details for each skill enablement record, use the expand=nameFreeInvocation parameter.

/v1/skills/enablements?unitId={unitId}&maxResults={maxResults}&expand=nameFreeInvocation&nextToken={nextToken} HTTP/1.1

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

expand

An attribute (or set of attributes) to include in the response. Current values supported: nameFreeInvocation

String

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 parameters

Field Description Type

paginationContext

Context that 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 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

nameFreeInvocation.status

Name-free interaction enablement status: DISABLED or ENABLED. For skills that don't support name-free interaction, DISABLED is returned.

Enum

nameFreeInvocation.locales

Available locales for name-free interaction on the unit: en-US, es-US, en-CA, fr-CA, en-GB, fr-FR, es-ES, it-IT, de-DE. This value is only returned if nameFreeInvocation.status is ENABLED. Limit of 5 locales.

Array

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.

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 operator doesn't have the right 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.

500

Internal Server Error

The request couldn't be handled because of an internal service error when retrieving NameFreeInvocation.

503

Service Unavailable

The server is temporarily unavailable.

503

Service Unavailable

The server is temporarily unavailable for fetching NameFreeInvocation.

Get skill enablement for multiple units

Call POST /v1/skills/enablements/batchGet to get the skill enablement for multiple units in a single request.

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 format examples

List skill enablement and account linking details only

The following example lists all skill enablement records for a single skill across multiple units. By default, the results aren't expanded with name-free interaction details.

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

POST /v1/skills/enablements/batchGet HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Include name-free interaction details

This example shows how to include the name-free interaction details for each skill enablement record, use the expand=nameFreeInvocation parameter.

Request path parameters

The request path has no parameters.

Request body example

The following example shows the body of a request to get the skill enablement for four units.

Request body parameters

Field Description Type Required

paginationContext

Context that contains all data needed to control pagination.

Object

No

paginationContext.maxResults

Maximum number of results to display. The value of this parameter must be between 1 and 10. Default is 10.

Integer

No

paginationContext.nextToken

Continuation token returned in response object of previous list skill enablements response. For details, see Handling Pagination in Query Results.

String

No

items

List of request items. Each item represents a single unit.

Array

Yes

items[*].itemId

Unique identifier for the request item. Must be unique within the request.

Integer

Yes

items[*].unitId

Unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

Yes

expand

An attribute (or set of attributes) to include in the response. Current values supported: nameFreeInvocation

Array

Yes

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

Response body example

Response body parameters

Field Description Type

paginationContext

Context that 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

results

List of skill enablements.

List (Set)

results[*].itemId

A unique identifier for the request item. You specified this value in the request.

Integer

results[*].enablements

List of enablements for the skill.

List (Set)

results[*].enablements[*].skill

Skill stage and ID.

Object

results[*].enablements[*].skill.stage

Skill stage: development, certification, or live.

Enum

results[*].enablements[*].skill.id

Unique identifier for a skill.

String

results[*].enablements[*].unit

Unique identifier for the unit.

String

results[*].enablements[*].unit.id

Unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

results[*].enablements[*].accountLink

Current account linking status between the user's Amazon account and their account in your service.

Object

results[*].enablements[*].accountLink.status

Account linking status: LINKED or NOT_LINKED. For skills that don't support account linking, NOT_LINKED is returned.

String

results[*].enablements[*].status

Skill enablement status: ENABLING or ENABLED.

Enum

results[*].enablements[*].nameFreeInvocation.status

Name-free interaction enablement status: DISABLED or ENABLED. For skills that don't support name-free interaction, DISABLED is returned.

Enum

results[*].enablements[*].nameFreeInvocation.locales

Available locales for name-free interaction on the unit: en-US, es-US, en-CA, fr-CA, en-GB, fr-FR, es-ES, it-IT, de-DE. This value is only returned if nameFreeInvocation.status is ENABLED. Limit of 5 locales.

Array

Error response header

HTTP/1.1 {ErrorCode}
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response body example

The following example shows an error response body.

{
    "errors": [
        {
            "itemId": 0,
            "status": 401,
            "errorCode": "UNAUTHENTICATED",
            "errorDescription": "The access token is invalid."
        }
    ]
}

Error response parameters

Field Description Type

errors

A list of error responses, one for each request item.

Array

errors[*].itemId

The identifier for the request item. Optional if the error response is for the entire request and not for individual items.

String

errors[*].status

The response status code per request or request item.

Integer

errors[*].errorCode

The error code for the error.

Enum

errors[*].errorDescription

A description of the error.

String

HTTP response codes

Status Code Name Description

200

Accepted

The request was accepted. If a request is successful (even if only partially), the API returns a 200 status code with a response body that lists the enablements for each unit. If a unit doesn't have any enablements, the response contains an empty array for the associated itemId.

400

INVALID_PARAM

The request has a missing or invalid parameter.

400

BAD_REQUEST

The number of request items exceeds the limit.

401

UNAUTHENTICATED

The access token is missing, expired, or invalid.

403

FORBIDDEN

The operator doesn't have the right 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.

500

Internal Server Error

The request couldn't be handled because of an internal service error when retrieving NameFreeInvocation.

503

Service Unavailable

The server is temporarily unavailable.

503

Service Unavailable

The server is temporarily unavailable for fetching NameFreeInvocation.

Enable skills

The following operations allow you to enable a skill on one or multiple units.

Enable a skill for a unit

Call POST /v1/skills/{skillId}/enablements to enable a skill for a 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 format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 examples

Enable skill without account linking or name-free interaction

The following example shows a basic skill enablement on a unit without additional details such as account linking or name-free interaction.

Request body example
{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live"
}
Enable skill with account linking

The following example shows a skill enablement on a unit with account linking using partitions.

Request body example
{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live",
  "partitionName": "Room101-Kitchenette",
  "accountLinkRequest": {
    "redirectUri": "https://example.com",
    "authCode": "3pauthcode",
    "type": "AUTH_CODE"
  }
}
Enable skill with name-free interaction

The following example shows a skill enablement on a unit with name-free interaction.

Request body example
{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live",
  "nameFreeInvocationRequest": {
      "locales" : ["en-US"]
  }
}

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.
For example, "Room-101" and "Room101, Room202" are valid values for this parameter. The following aren't valid values: "" (empty list), "Room101, ,Room202" (not properly comma-separated), "Room 101" (contains whitespace).

String

No

accountLinkRequest

Account linking request information, as an AccountLinkRequest object.

Object

Yes, for skills that require account linking

nameFreeInvocationRequest

Name-free interaction request information, as an NameFreeInvocationRequest object.

Object

No. Only available for skills that support name-free interaction

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

NameFreeInvocationRequest object schema

Field Description Type Required

locales

The locales that for the unit that should be enabled for name-free interaction. The skill must have an interaction model that supports the locale. Supported values: en-US, es-US,en-CA,fr-CA,en-GB,fr-FR,it-IT,de-DE,es-ES. Limit of 5 locales.

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"
  },
  "nameFreeInvocation": {
    "status": "ENABLED",
    "locales": ["en-US"]
  },
  "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

nameFreeInvocation.status

Name-free interaction enablement status: DISABLED or ENABLED. For skills that don't support name-free interaction, DISABLED is returned.

Enum

nameFreeInvocation.locales

Available locales for name-free interaction on the unit: en-US, es-US, en-CA, fr-CA, en-GB, fr-FR, es-ES, it-IT, de-DE. This value is only returned if nameFreeInvocation.status is ENABLED. Limit of 5 locales.

Array

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.

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 operator doesn't have the right 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.

500

Internal Server Error

The request couldn't be handled because of an internal service error when retrieving NameFreeInvocation.

503

Service Unavailable

The server is temporarily unavailable.

503

Service Unavailable

The server is temporarily unavailable for fetching NameFreeInvocation.

Enable a skill for multiple units

Call POST /v1/skills/{skillId}/enablements/batch to enable a skill for multiple units in a single request.

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 format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 examples

Enable skill without account linking or name-free interaction

The following example shows a basic skill enablement on multiple units without additional details such as account linking or name-free interaction.

Request body example
{
    "items": [
        {
            "itemId": 0,
            "unitId": "amzn1.alexa.unit.unitId1",
            "stage": "live"
        },
        {
            "itemId": 1,
            "unitId": "amzn1.alexa.unit.unitId2",
            "stage": "live"
        }
    ]
}
Enable skill with account linking

The following example shows a skill enablement on multiple units with account linking using partitions.

Request body example
{
    "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
        }
    ]
}
Enable skill with name-free interaction

The following example shows a skill enablement on multiple units with name-free interaction.

Request body example
{
    "items": [
        {
            "itemId": 0,
            "unitId": "amzn1.alexa.unit.unitId1",
            "stage": "live",
            "nameFreeInvocationRequest": {
                "locales" : ["en-CA"]
            }
        },
        {
            "itemId": 1,
            "unitId": "amzn1.alexa.unit.unitId2",
            "stage": "live",
            "nameFreeInvocationRequest": {
                "locales" : ["en-CA","fr-CA"]
            }
        }
    ]
}

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 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.
For example, "Room-101" and "Room101, Room202" are valid values for this parameter. The following aren't valid values: "" (empty list), "Room101, ,Room202" (not properly comma-separated), "Room 101" (contains whitespace).

String

No

accountLinkRequest

Account linking request information, as an AccountLinkRequest object.

Object

Yes, for skills that require account linking

nameFreeInvocationRequest

Name-free interaction request information, as an NameFreeInvocationRequest object.

Object

No. Only available for skills that support name-free interaction

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 operator doesn't have the right 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.

500

Internal Server Error

The request couldn't be handled because of an internal service error when retrieving NameFreeInvocation.

503

Service Unavailable

The server is temporarily unavailable.

503

Service Unavailable

The server is temporarily unavailable for fetching NameFreeInvocation.

Disable skills

The following operations allow you to disable a skill on one or multiple units.

Disable a skill for a unit

Call DELETE /v1/skills/{skillId}/enablements?unitId={unitId} to disable a skill for a 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 format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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 operator doesn't have the right 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 multiple units

Call POST /v1/skills/{skillId}/enablements/batchDelete to disable a skill for multiple units in a single request.

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 format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

POST /v1/skills/{skillId}/enablements/batchDelete 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 of a request to disable a skill for three units.

{
  "items": [
    {
        "itemId": 0,
        "unitId": "amzn1.alexa.unit.unitId1",
        "stage": "live"
    },
    {
        "itemId": 1
        "unitId": "amzn1.alexa.unit.unitId2",
        "stage": "development"
    },
    {
        "itemId": 2
        "unitId": "amzn1.alexa.unit.unitId3"
    }
  ]
}

Request body parameters

Field Description Type Required

items

List of request items. Each item represents an disablement request for a single unit.

Array

Yes

items[*].itemId

Unique identifier for the request item. Must be unique within the request.

Integer

Yes

items[*].unitId

Unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

Yes

stage

Skill stage: development or live. If present, the specified skill stage will be disabled.

Enum

No

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}
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response body example

The following example shows an error response body.

{
    "errors": [
        {
            "itemId": 0,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Unit ID is missing or invalid"
        }
    ]
}

Error response parameters

Field Description Type

errors

A list of error responses, one for each request item.

Array

errors[*].itemId

The identifier for the request item. Optional if the error response is for the entire request and not for individual items.

String

errors[*].status

The response status code per request or request item.

Integer

errors[*].errorCode

The error code for the error.

Enum

errors[*].errorDescription

A description of the error.

String

HTTP response codes

Status Code Name Description

202

Accepted

The request was accepted.

400

INVALID_PARAM

The request has a missing or invalid parameter.

400

BAD_REQUEST

The number of request items exceeds the limit.

401

UNAUTHENTICATED

The access token is missing, expired, or invalid.

403

FORBIDDEN

The operator doesn't have the right permission to perform the operation.

404

ENABLEMENT_NOT_FOUND

The requested enablement couldn't be found.

404

SKILL_STAGE_NOT_FOUND

The requested skill ID and stage combination couldn'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.


Was this page helpful?

Last updated: Feb 13, 2024