Alexa Skill Development Notifications API Reference

If you develop Alexa skills using the Alexa Skill Management API (SMAPI) or the Alexa Skills Kit Command-Line Interface (ASK CLI), you can use the Skill Development Notifications Service (SDNS) to notify you about Alexa skill development events. You might use SDNS if you're one of the following roles:

  • An independent skill developer who wants to get notifications about the skills that you create.
  • An organization or tool maker who wants to get notifications about the skills that you or your developers create, and distribute the notifications to your developers.
  • A developer who wants to get notifications about the skills that you create for an organization or through an organization's tool.

This topic describes all API operations that relate to SDNS. For an overview of SDNS and the steps to set up notifications, see Use the Alexa Skill Development Notifications API. For information about the skill development events that you can be notified about, see Alexa Skill Development Event Schemas.

API endpoint and header

The endpoint of the API is https://api.amazonalexa.com.

In each API request, the bearer token of the Authentication header must be an access token from Login with Amazon (LWA). The way that you get the access token depends on the way that you develop Alexa skills. For more information, see Prerequisites.

Create a subscriber

Creates a subscriber. You can subsequently use this subscriber to create a subscription to specified skill events.

When you create an SDNS subscriber, SDNS sends an empty JSON object to the endpoint that you defined in the subscriber. This empty notification enables you to verify that you set up the subscriber correctly. If you set up any form of Amazon SNS topic notification, such as email, mobile SMS, or another channel, you receive this empty object through that channel.

Request

POST /v0/developmentEvents/subscribers

Authorization

You must set the bearer token of the Authentication header of the request to an access token from LWA. For information about how to get the access token and which credentials you use to get it, see Prerequisites.

Example request body

{
  "name": "string",
  "vendorId": "string",
  "endpoint": {
    "uri": "string",
    "authorization": {
      "type": "AWS_IAM",
      "arn": "string"
    }
  }
}
Field Description
vendorId The unique ID of an Amazon developer account. You use this ID in the request to create a subscriber so that the resulting subscriber is authorized for and linked to that Amazon developer account.
name A name for the subscriber.
endpoint An object that encapsulates the endpoint that will receive the notifications, as well as the authorization required to publish to that endpoint.
endpoint.uri The URI of the endpoint that receives the notifications.
endpoint.authorization An object that describes the authorization that is required to publish a notification to the endpoint.
endpoint.authorization.type An enum that specifies the type of authorization. Supported value: AWS_IAM
endpoint.authorization.arn

The Amazon Resource Name (ARN) for the AWS Identity and Access Management (IAM) role to use for authentication.

Response

201 on success.

No response body is returned. The subscriberId is in the response's Location header. In the following example, amzn1.ask-subscriber.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is the subscriberId value.

Location: /v0/developmentEvents/subscribers/amzn1.ask-subscriber.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Response codes

Code Description
201 Created.
400 The server cannot process the request due to a client error.
401 The access token is invalid, expired, or doesn't have access to the resource.
403 The requested operation is not allowed.
429 The permitted request limit is exceeded. Throttling criteria includes total requests, per API, and client ID.
500 Internal server error.
503 The service is unavailable.

Delete a subscriber

Deletes the subscriber with the specified subscriberId. If you want to delete a subscriber, you must first delete all of the associated subscriptions.

Request

DELETE /v0/developmentEvents/subscribers/{subscriberId}

No request body.

Authorization

You must set the bearer token of the Authentication header of the request to an access token from LWA. For information about how to get the access token and which credentials you use to get it, see Prerequisites.

Response

204 on success. No response body.

Response codes

Code Description
204 The operation was successful.
400 The server cannot process the request due to a client error.
401 The access token is invalid, expired, or doesn't have access to the resource.
403 The requested operation is not allowed.
404 The requested resource is not found.
429 The permitted request limit is exceeded. Throttling criteria includes total requests, per API, and client ID.
500 Internal server error.
503 The service is unavailable.

Get the subscriber for a subscriber ID

Gets the subscriber for a specified subscriberId.

Request

GET /v0/developmentEvents/subscribers/{subscriberId}

No request body.

Authorization

You must set the bearer token of the Authentication header of the request to an access token from LWA. For information about how to get the access token and which credentials you use to get it, see Prerequisites.

FieldDescriptionParameter Type
subscriberId The unique ID of the subscriber.Path parameter

Response

200 on success.

Response body

The response body contains the requested subscriber object.

{
  "subscriberId": "string",
  "name": "string",
  "endpoint": {
    "uri": "string",
    "authorization": {
      "type": "AWS_IAM",
      "arn": "string"
    }
  }
}

Response codes

Code Description
200 The operation was successful.
400 The server cannot process the request due to a client error.
401 The access token is invalid, expired, or doesn't have access to the resource.
403 The requested operation is not allowed.
404 The requested resource is not found.
429 The permitted request limit is exceeded. Throttling criteria includes total requests, per API, and client ID.
500 Internal server error.
503 The service is unavailable.

List the subscribers for a vendor ID

Lists the subscribers for a specified vendorId.

Request

GET /v0/developmentEvents/subscribers?vendorId=<vendorId-value>&maxResults=<integer>&nextToken=<nextToken-value>

No request body.

Authorization

You must set the bearer token of the Authentication header of the request to an access token from LWA. For information about how to get the access token and which credentials you use to get it, see Prerequisites.

FieldDescriptionParameter Type
vendorId The unique ID of an Amazon developer account.
Query parameter
maxResults Optional. Maximum number of results to display per page of listed subscribers. The value of this parameter must not exceed 50.Query parameter
nextToken Optional. Continuation token returned in response object of last response. If this is parameter is null, the response will include subscribers from the first set.Query parameter

Response

200 on success.

Response body

The response body includes pagination information, and an array of the requested subscriber objects.

{
  "_links": {
    "self": {
      "href": "string"
    },
    "next": {
      "href": "string"
    }
  },
  "nextToken": "string",
  "subscribers": [
    {
      "subscriberId": "string",
      "name": "string",
      "clientId": "string",
      "status": "ACTIVE" | "INACTIVE",  
      "endpoint": {
        "uri": "string",
        "authorization": {
          "type": "AWS_IAM",
          "arn": "string"
        }
      }
    }
  ]
}

Response codes

Code Description
200 The operation was successful.
400 The server cannot process the request due to a client error.
401 The access token is invalid, expired, or doesn't have access to the resource.
403 The requested operation is not allowed.
404 The requested resource is not found.
429 The permitted request limit is exceeded. Throttling criteria includes total requests, per API, and client ID.
500 Internal server error.
503 The service is unavailable.

Update a subscriber

Updates the mutable properties of a subscriber. Only the Amazon developer account (vendor ID) that created the subscriber can update it.

Request

PUT /v0/developmentEvents/subscribers/{subscriberId}

Request body

The request body should be the new desired subscriber object. All values declared will overwrite the existing values. The subscriberId field cannot be changed.

{
  "name": "string",
  "endpoint": {
    "uri": "string",
    "authorization": {
      "type": "AWS_IAM",
      "arn": "string"
    }
  }
}

Authorization

You must set the bearer token of the Authentication header of the request to an access token from LWA. For information about how to get the access token and which credentials you use to get it, see Prerequisites.

Response

204 on success.

Response codes

Code Description
204 Updated.
400 The server cannot process the request due to a client error.
401 The access token is invalid, expired, or doesn't have access to the resource.
404 The requested resource is not found.
429 The permitted request limit is exceeded. Throttling criteria includes total requests, per API, and client ID.
500 Internal server error.
503 The service is unavailable

Create a subscription

Creates a subscription. A subscription maps an Amazon developer account to the subscriber that the notifications are sent to, and specifies which events trigger a notification.

Amazon SNS does not guarantee chronologically ordered, singular message deliveries to Amazon SNS topics. Therefore, you might receive multiple identical notifications for the same event.

Request

POST /v0/developmentEvents/subscriptions

Request body

{
  "name": "string",
  "events": [
    "<event-name>", ..., "<event-name>" 
  ],
  "vendorId": "string",
  "subscriberId": "string"
}

Authorization

You must set the bearer token of the Authentication header of the request to an access token from LWA. For information about how to get the access token and which credentials you use to get it, see Prerequisites.

Field Description
vendorId The unique ID of the Amazon developer account that will own the subscription.
subscriberId The unique ID of the subscriber that will receive notifications of the events.
name A name for the subscription.
events An array of events that will trigger notifications to the endpoint that the subscriber encapsulates. For more information about events, see Alexa Skill Development Event Schemas.

Response

201 on success.

There is no body in the response. The subscriptionId is in the response's Location header. In the following example, the subscriptionId is amzn1.ask-subscription.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Location: /v0/developmentEvents/subscriptions/amzn1.ask-subscription.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Response codes

Code Description
201 Created.
400 The server cannot process the request due to a client error.
401 The access token is invalid, expired, or doesn't have access to the resource.
403 The requested operation is not allowed.
404 The requested resource is not found.
429 The permitted request limit is exceeded. Throttling criteria includes total requests, per API, client ID, and customer ID.
500 Internal Server Error
503 The service is unavailable

Delete a subscription

Deletes the subscription with the specified subscriptionId.

Request

DELETE /v0/developmentEvents/subscriptions/{subscriptionId}

Authorization

You must set the bearer token of the Authentication header of the request to an access token from LWA. For information about how to get the access token and which credentials you use to get it, see Prerequisites.

Response

204 on success.

Response codes

Code Description
204 The operation was successful.
400 The server cannot process the request due to a client error.
401 The access token is invalid, expired, or doesn't have access to the resource.
403 The requested operation is not allowed.
404 The requested resource is not found.
429 The permitted request limit is exceeded. Throttling criteria includes total requests, per API, and client ID.
500 Internal server error.
503 The service is unavailable.

Get the subscription for a subscription ID

Returns the subscription object for a specified subscriptionId.

Request

GET /v0/developmentEvents/subscriptions/{subscriptionId}

No request body.

Authorization

You must set the bearer token of the Authentication header of the request to an access token from LWA. For information about how to get the access token and which credentials you use to get it, see Prerequisites.

FieldDescriptionParameter Type
subscriptionId The unique ID of the subscription.Path parameter

Response

200 on success.

Response body

The response body includes pagination information and an array of the requested subscription objects.

{
  "name": "string",
  "subscriptionId": "string",
  "subscriberId": "string",
  "vendorId": "string",
  "events": [
    "AlexaDevelopmentEvent.ManifestUpdate"
  ]
}

Response codes

Code Description
200 The operation was successful
400 The server cannot process the request due to a client error.
401 The access token is invalid, expired, or doesn't have access to the resource.
403 The requested operation is not allowed.
404 The requested resource is not found.
429 The permitted request limit is exceeded. Throttling criteria includes total requests, per API, and client ID.
500 Internal server error.
503 The service is unavailable.

List subscriptions

Lists the subscriptions for a vendorId, subscriberId, or both.

Request

Lists all of the subscriptions for the specified vendorId.

GET /v0/developmentEvents/subscriptions?vendorId=<vendorId-value>&maxResults=<integer>&nextToken=<nextToken-value>

Lists all of the subscriptions for the specified subscriberId.

GET /v0/developmentEvents/subscriptions?subscriberId=<subscriberId-value>&maxResults=<integer>&nextToken=<nextToken-value>

Provides a filtered list of subscriptions by both vendorId and subscriberId.

GET
/v0/developmentEvents/subscriptions?subscriberId=<subscriberId-value>&vendorId=<vendorId-value>&maxResults=<integer>&nextToken=<nextToken-value>

In each case, there is no request body.

Authorization

You must set the bearer token of the Authentication header of the request to an access token from LWA. For information about how to get the access token and which credentials you use to get it, see Prerequisites.

FieldDescriptionParameter Type
vendorId The unique ID of the Amazon developer account to list subscriptions for.Query parameter
subscriberId The unique ID of the subscriber to list subscriptions for.Query parameter
maxResults (Optional) The maximum number of results to display per page of listed subscriptions. The value of this parameter must not exceed 50.Query parameter
nextToken (Optional) Continuation token returned in the response object of the last response. If this parameter is null, the response will include subscriptions from the first set. Used in conjunction with maxResults. Query parameter

Response

200 on success.

Response body

The response body includes the request subscription object.

{
  "_links": {
    "self": {
      "href": "string"
    },
    "next": {
      "href": "string"
    }
  },
  "nextToken": "string",
  "subscriptions": [
    {
      "name": "string",
      "subscriptionId": "string",
      "subscriberId": "string",
      "vendorId": "string",
      "events": [
        "AlexaDevelopmentEvent.ManifestUpdate"
      ]
    }
  ]
}

Response codes

Code Description
200 The operation was successful.
400 The server cannot process the request due to a client error.
401 The access token is invalid, expired, or doesn't have access to the resource.
403 The requested operation is not allowed.
404 The requested resource is not found.
429 The permitted request limit is exceeded. Throttling criteria includes total requests, per API, and client ID.
500 Internal server error.
503 The service is unavailable.

Update a subscription

Updates the subscription's name and the list of events to which the subscription is subscribed. The request body should be the new desired subscription object. All values declared will overwrite the existing values. The subscriberId and subscriptionId cannot be updated.

Request

PUT /v0/developmentEvents/subscriptions/{subscriptionId}

Request body

{
   "name": "string",
  "events": [
    "<event-name>", ..., "<event-name>" 
    ]
}

For information about the available event types, see Alexa Skill Development Event Schemas.

Authorization

You must set the bearer token of the Authentication header of the request to an access token from LWA. For information about how to get the access token and which credentials you use to get it, see Prerequisites.

Response

204 on success.

Response codes

Code Description
204 Updated.
400 The server cannot process the request due to a client error.
401 The access token is invalid, expired, or doesn't have access to the resource.
403 The requested operation is not allowed.
404 The requested resource is not found.
429 The permitted request limit is exceeded. Throttling criteria includes total requests, per API, and client ID.
500 Internal server error.
503 The service is unavailable.