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
- 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
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.
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
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 | 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.
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.
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.
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
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 | 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
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. |
Last updated: Mar 30, 2022