Alexa Skill Development Notifications API Reference

Note: Sign in to the developer console to build or publish your skill.

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
Create a subscriber
Delete a subscriber
Get the subscriber for a subscriber ID
List the subscribers for a vendor ID
Update a subscriber
Create a subscription
Delete a subscription
Get the subscription for a subscription ID
List subscriptions
Update a subscription

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

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

Field	Description	Parameter 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

Field	Description	Parameter 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.

Note: Make sure that your code handles unknown values for the status enum. Currently, the possible values are "ACTIVE" and "INACTIVE", but there may be more values in the future.

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

Important: If SDNS fails to deliver a notification to a subscriber due to a nonexistent endpoint or invalid publishing permissions, the subscriber is marked as inactive. SDNS doesn't deliver future notifications to that subscriber. After you correct the problem, you must call the Update Subscriber API to reactivate the subscriber, even if the credentials haven't changed.

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

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

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

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

Field	Description	Parameter 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

Field	Description	Parameter 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

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.

Last updated: Mar 30, 2022