Skill Development Notifications REST API Reference


Use the Skill Development Notifications Service (SDNS) REST API to create and manage subscribers and subscriptions for skill development notifications. SDNS is a message delivery system for Alexa skill development events.

If you develop Alexa skills by using the Alexa Skill Management API (SMAPI) or the Alexa Skills Kit Command-Line Interface (ASK CLI), you can use the SDNS to notify you about Alexa skill development events. Before you use the SDNS REST API, you must create an Amazon Simple Notification Service (SNS) topic to receive notifications.

For an overview of SDNS and the steps to set up notifications, see Use the Alexa Skill Development Notifications. For more details about the skill development events, see Alexa Skill Development Event Schemas.

API endpoint

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

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see SDNS Prerequisites.

Operations

The SDNS API includes the following operations.

Operation HTTP method and URI

Create subscriber

POST /v0/developmentEvents/subscribers

Create subscription

POST /v0/developmentEvents/subscriptions

Delete subscriber

DELETE /v0/developmentEvents/subscribers/{subscriberId}

Delete subscription

DELETE /v0/developmentEvents/subscriptions/{subscriptionId}

Get subscriber

GET /v0/developmentEvents/subscribers/{subscriberId}

Get subscription

` GET /v0/developmentEvents/subscriptions/{subscriptionId}`

List subscribers

GET /v0/developmentEvents/subscribers?vendorId={vendorId}&maxResults={maxResults}&nextToken={nextToken}

List subscriptions

GET /v0/developmentEvents/subscriptions?vendorId={vendorId}&subscriberId={subscriberId}&maxResults={maxResults}&nextToken={nextToken}

Update subscriber

PUT /v0/developmentEvents/subscribers/{subscriberId}

Update subscriptions

PUT /v0/developmentEvents/subscriptions/{subscriptionId}

Create subscriber

Create a subscriber to the specified the Amazon SNS topic. You use the subscriber to create a subscription to skill development events.

When you create a subscriber, SDNS sends an empty JSON object to the endpoint that you define in the request. 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

To create a subscriber, you make a POST request to the developmentEvents/subscribers resource.

Request path and header example

Copied to clipboard.

POST /v0/developmentEvents/subscribers
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "name": "subscriber.name.1",
    "vendorId": "your.vendor.id.1",
    "endpoint": {
        "uri": "https://sns.amazonaws.com/example.topic",
        "authorization": {
            "type": "AWS_IAM",
            "arn": "arn:aws:iam::us-east-1:1"
        }
    }
}

Request body properties

Property Description Type Required

vendorId

Identifies the vendor to which the SNS topic belongs.
For details about how to get your vendor ID, see Locate your customer ID and vendor ID.

String

Yes

name

Name for the subscriber.

String

Yes

endpoint

Defines the SNS endpoint to receive the notifications, as well as the authorization required to publish to that endpoint.

Object

Yes

endpoint.uri

URI of the endpoint that receives the notifications.

String

Yes

endpoint.authorization

Describes the authorization required to publish a notification to the endpoint.

Object

Yes

endpoint.authorization.type

Specifies the type of authorization.
Valid values: AWS_IAM

String

Yes

endpoint.authorization.arn

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

String

Yes

Response

A successful response returns HTTP 201 Created, along with a Location parameter in the response header that contains the subscriberId URL to retrieve the subscriber. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

201 Created

Subscriber created successfully. The response header contains a Location parameter that includes the subscriberId. For example:

HTTP 201 Created
Content-Type: application/json
Location: /v0/developmentEvents/subscribers/amzn1.ask-subscriber.1

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create subscription

Create a new subscription for the specified subscriber. The subscription defines the events that trigger a notification to the subscriber.

Request

To create a subscription, you make a POST request to the developmentEvents/subscriptions resource.

Request path and header example

Copied to clipboard.

POST /v0/developmentEvents/subscriptions
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "vendorId": "your.vendor.id.1",
    "subscriberId": "amzn1.ask-subscriber.1",
    "name": "your.subscription.name",
    "events": [
        "AlexaDevelopmentEvent.SkillPublish", 
        "AlexaDevelopmentEvent.SkillCertification"
    ]
}

Request body properties

Property Description Type Required

vendorId

Identifies the vendor to which the subscription belongs.
For details about how to get your vendor ID, see Locate your customer ID and vendor ID.

String

Yes

subscriberId

Identifies the subscriber to receive the notifications.
Formatted in the Amazon Common Identifier (ACI) format, amzn1.alexa.subscriber.{id}.
Valid values: 1 – 255 characters.

String

Yes

name

Name for the subscription.

String

Yes

events

List of skill development events that trigger notifications to the subscriber endpoint. For more details about events, see Alexa Skill Development Event Schemas.

Valid values: AlexaDevelopmentEvent.ManifestUpdate, AlexaDevelopmentEvent.SkillPublish, AlexaDevelopmentEvent.SkillCertification, AlexaDevelopmentEvent.InteractionModelUpdate, AlexaDevelopmentEvent.All, AlexaCustomerFeedbackEvent.SkillReviewPublish.

Array of strings

Yes

Response

A successful response returns HTTP 201 Created, along with a Location parameter in the response header that contains the subscriptionId URL to retrieve the subscription. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

201 Created

Subscription created successfully. The response header contains a Location parameter that includes the subscriptionId. For example:

HTTP 201 Created
Content-Type: application/json
Location: /v0/developmentEvents/subscribers/amzn1.ask-subscription.1

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete subscriber

Deletes the subscriber with the specified subscriberId from the topic. To delete a subscriber, you must delete the associated subscriptions first.

Request

To remove a subscriber, you make a DELETE request to the developmentEvents/subscribers resource.

Request path and header example

Copied to clipboard.

DELETE /v0/developmentEvents/subscribers/{subscriberId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

subscriberId

Path

Identifies the subscriber to an SNS topic.
Formatted in the ACI format, amzn1.alexa.subscriber.{id}.
Valid values: 1 – 255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Subscriber deleted successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete subscription

Delete the specified subscription. The vendor who created the subscriber and the vendor that published the event can delete a subscription.

Request

To delete a subscription, you make a DELETE request to the developmentEvents/subscriptions resource.

Request path and header example

Copied to clipboard.

DELETE /v0/developmentEvents/subscriptions/{subscriptionId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

subscriptionId

Path

Identifies the subscription.
Formatted in the ACI format, amzn1.alexa.subscription.{id}.
Valid values: 1 – 255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Subscription deleted successfully

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get subscriber

Get the details for the specified subscriber.

Request

To get a subscriber, you make a GET request to the developmentEvents/subscribers resource.

Request path and header example

Copied to clipboard.

GET /v0/developmentEvents/subscribers/{subscriberId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

subscriberId

Path

Identifies the subscriber to an SNS topic.
Formatted in the ACI format, amzn1.alexa.subscriber.{id}.
Valid values: 1 – 255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the subscriber information. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "subscriberId": "amzn1.ask-subscriber.1",
    "name": "subscriber.name.1",
    "vendorId": "your.vendor.id.1",
    "endpoint": {
        "uri": "https://sns.amazonaws.com/example.topic",
        "authorization": {
            "type": "AWS_IAM",
            "arn": "arn:aws:iam::us-east-1:1"
        }
    }
}

Response body properties

Property Description Type

subscriberId

Identifies the subscriber to an SNS topic.
Formatted in the ACI format, amzn1.alexa.subscriber.{id}.
Valid values: 1 – 255 characters.

String

name

Name for the subscriber.

String

vendorId

Identifies the vendor to which the SNS topic belongs.
For details about how to get your vendor ID, see Locate your customer ID and vendor ID.

String

endpoint

Defines the SNS endpoint to receive the notifications, as well as the authorization required to publish to that endpoint.

Object

endpoint.uri

URI of the endpoint that receives the notifications.

String

endpoint.authorization

Describes the authorization required to publish a notification to the endpoint.

Object

endpoint.authorization.type

Specifies the type of authorization.
Valid values: AWS_IAM

String

endpoint.authorization.arn

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

String

HTTP status codes

Status Description

200 OK

Response body contains the subscriber information.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get subscription

Get the details for the specified subscription.

Request

To get a subscription, you make a GET request to the developmentEvents/subscriptions resource.

Request path and header example

Copied to clipboard.

GET /v0/developmentEvents/subscriptions/{subscriptionId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

subscriptionId

Path

Identifies the subscription.
Formatted in the ACI format, amzn1.alexa.subscription.{id}.
Valid values: 1 – 255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the subscription information. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "vendorId": "your.vendor.id.1",
    "subscriberId": "amzn1.ask-subscriber.1",
    "subscriptionId": "amzn1.ask-subscription.1",
    "name": "your.subscription.name",
    "events": [
        "AlexaDevelopmentEvent.SkillPublish", 
        "AlexaDevelopmentEvent.SkillCertification"
    ]
}

Response body properties

Property Description Type

vendorId

Identifies the vendor to which the subscription belongs.
For details about how to get your vendor ID, see Locate your customer ID and vendor ID.

String

subscriberId

Identifies the subscriber to receive the notifications.
Formatted in the Amazon Common Identifier (ACI) format, amzn1.alexa.subscriber.{id}.
Valid values: 1 – 255 characters.

String

subscriptionId

Identifies the subscription.
Formatted in the Amazon Common Identifier (ACI) format, amzn1.alexa.subscriptionId.{id}.
Valid values: 1 – 255 characters.

String

name

Name for the subscription.

String

events

List of skill development events that trigger notifications to the subscriber endpoint. For more details about events, see Alexa Skill Development Event Schemas.

Valid values: AlexaDevelopmentEvent.ManifestUpdate, AlexaDevelopmentEvent.SkillPublish, AlexaDevelopmentEvent.SkillCertification, AlexaDevelopmentEvent.InteractionModelUpdate, AlexaDevelopmentEvent.All, AlexaCustomerFeedbackEvent.SkillReviewPublish.

Array of strings

HTTP status codes

Status Description

200 OK

Response body contains the subscription information.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List subscribers

List the subscribers for the specified vendor.

Request

To list subscribers, you make a GET request to the developmentEvents/subscribers resource.

Request path and header example

Copied to clipboard.

GET /v0/developmentEvents/subscribers?vendorId={vendorId}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

vendorId

Query

Identifies the vendor to which the SNS topic belongs.
For details about how to get your vendor ID, see Locate your customer ID and vendor ID.

String

Yes

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–250. Default: 10.

Integer

No

nextToken

Query

Token from the previous response. If not included, the Alexa service returns the first page of results.
Include if iterating over a paginated response.

String

No

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of subscribers for the specified vendor. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "subscribers": [{
            "subscriberId": "amzn1.ask-subscriber.1",
            "name": "subscriber.name.1",
            "clientId": "your.client.id.1",
            "status": "ACTIVE",
            "endpoint": {
                "uri": "https://sns.amazonaws.com/example.topic",
                "authorization": {
                    "type": "AWS_IAM",
                    "arn": "arn:aws:iam::us-east-1:1"
                }
            }
        },
        {
            "subscriberId": "amzn1.ask-subscriber.2",
            "name": "subscriber.name.2",
            "clientId": "your.client.id.1",
            "status": "ACTIVE",
            "endpoint": {
                "uri": "https://sns.amazonaws.com/example.topic",
                "authorization": {
                    "type": "AWS_IAM",
                    "arn": "arn:aws:iam::us-east-1:1"
                }
            }
        }
    ],
    "nextToken": "string",
    "_links": {
        "self": {
            "href": "string"
        },
        "next": {
            "href": "string"
        }
    }
}

Response body properties

Property Description Type

subscribers

List of subscribers for the specified vendor.

Array of objects

subscribers[].subscriberId

Identifies the subscriber to an SNS topic.
Formatted in the ACI format, amzn1.alexa.subscriber.{id}.
Valid values: 1 – 255 characters.

String

subscribers[].name

Name for the subscriber.

String

subscribers[].status

Indicates the current status of the subscriber.
Valid values: ACTIVE, INACTIVE.

String

subscribers[].clientId

Unique identifier for the subscriber.

String

subscribers[].endpoint

Defines the SNS endpoint to receive the notifications, as well as the authorization required to publish to that endpoint.

Object

subscribers[].endpoint.uri

URI of the endpoint that receives the notifications.

String

subscribers[].endpoint.authorization

Describes the authorization required to publish a notification to the endpoint.

Object

subscribers[].endpoint.authorization.type

Specifies the type of authorization.
Valid values: AWS_IAM

String

subscribers[].endpoint.authorization.arn

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

String

nextToken

(Optional) Included when there are more results to return. Use this value in a subsequent request.

String

_links

Links for item navigation.
Defined in JSON Hypertext Application Language specification.

_links object

HTTP status codes

Status Description

200 OK

Response body contains a list of subscribers defined for the specified vendor.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List subscriptions

List the subscriptions for the specified vendor, specified subscriber or both.

Request

To list subscriptions, you make a GET request to the developmentEvents/subscriptions resource.

Request path and header example

Copied to clipboard.

GET /v0/developmentEvents/subscriptions?vendorId={vendorId}&subscriberId={subscriberId}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

vendorId

Query

Identifies the vendor to which the subscription belongs.
For details about how to get your vendor ID, see Locate your customer ID and vendor ID.
Include at least one of vendorId or subscriberId or both.

String

No

subscriberId

Path

Identifies the subscriber to an SNS topic.
Include at least one of vendorId or subscriberId or both.
Formatted in the ACI format, amzn1.alexa.subscriber.{id}.
Valid values: 1 – 255 characters.

String

No

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–250. Default: 10.

Integer

No

nextToken

Query

Token from the previous response. If not included, the Alexa service returns the first page of results.
Include if iterating over a paginated response.

String

No

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of subscriptions. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "subscriptions": [{
            "subscriptionId": "amzn1.ask-subscription.1",
            "name": "subscription.name.1",
            "subscriberId": "amzn1.ask-subscriber.1",
            "vendorId": "your.vendor.id.1",
            "events": [
                "AlexaDevelopmentEvent.SkillPublish",
                "AlexaDevelopmentEvent.SkillCertification"
            ]
        },
        {
            "subscriptionId": "amzn1.ask-subscription.2",
            "name": "subscription.name.2",
            "subscriberId": "amzn1.ask-subscriber.1",
            "vendorId": "your.vendor.id.1",
            "events": [
                "AlexaDevelopmentEvent.ManifestUpdate"
            ]
        }
    ],
    "nextToken": "string",
    "_links": {
        "self": {
            "href": "string"
        },
        "next": {
            "href": "string"
        }
    }
}

Response body properties

Property Description Type

subscriptions

List of subscribers for the specified vendor.

Array of objects

subscriptions[]subscriptionId

Identifies the subscription.
Formatted in the Amazon Common Identifier (ACI) format, amzn1.alexa.subscriptionId.{id}.
Valid values: 1 – 255 characters.

String

subscriptions[].name

Name of the subscription.

String

subscriptions[].subscriberId

Identifies the subscriber to an SNS topic.
Formatted in the ACI format, amzn1.alexa.subscriber.{id}.
Valid values: 1 – 255 characters.

String

subscriptions[].events

List of skill development events that trigger notifications to the subscriber endpoint. For more details about events, see Alexa Skill Development Event Schemas.

Valid values: AlexaDevelopmentEvent.ManifestUpdate, AlexaDevelopmentEvent.SkillPublish, AlexaDevelopmentEvent.SkillCertification, AlexaDevelopmentEvent.InteractionModelUpdate, AlexaDevelopmentEvent.All, AlexaCustomerFeedbackEvent.SkillReviewPublish.

Array of strings

nextToken

(Optional) Included when there are more results to return. Use this value in a subsequent request.

String

_links

Links for item navigation.
Defined in JSON Hypertext Application Language specification.

_links object

HTTP status codes

Status Description

200 OK

Response body contains a list of subscriptions for the specified filter.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update subscriber

Update the properties of the specified subscriber. You can update the subscriber if your developer account is part of the same vendor ID as the subscriber. This operation overwrites the existing subscriber values. You can't update the subscriberId.

Request

To update a subscriber, you make a PUT request to the developmentEvents/subscribers resource.

Request path and header example

Copied to clipboard.

PUT /v0/developmentEvents/subscriptions/{subscriptionId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

subscriberId

Path

Identifies the subscriber to an SNS topic.
Formatted in the ACI format, amzn1.alexa.subscriber.{id}.
Valid values: 1 – 255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "name": "subscriber.name.1",
    "endpoint": {
        "uri": "https://sns.amazonaws.com/example.topic",
        "authorization": {
            "type": "AWS_IAM",
            "arn": "arn:aws:iam::us-east-1:1"
        }
    }
}

Request body properties

Property Description Type Required

name

Name for the subscriber.

String

Yes

endpoint

Defines the SNS endpoint to receive the notifications, as well as the authorization required to publish to that endpoint.

Object

Yes

endpoint.uri

URI of the endpoint that receives the notifications.

String

Yes

endpoint.authorization

Describes the authorization required to publish a notification to the endpoint.

Object

Yes

endpoint.authorization.type

Specifies the type of authorization.
Valid values: AWS_IAM

String

Yes

endpoint.authorization.arn

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

String

Yes

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Subscriber updated successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update subscription

Update the subscription name or list of events. This operation overwrites the existing subscription values. You can't update the subscriberId or subscriptionId.

Request

To update a subscription, you make a PUT request to the developmentEvents/subscriptions resource.

Request path and header example

Copied to clipboard.

PUT /v0/developmentEvents/subscriptions/{subscriptionId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

subscriptionId

Path

Identifies the subscription.
Formatted in the ACI format, amzn1.alexa.subscription.{id}.
Valid values: 1 – 255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "name": "subscriber.name.1",
    "endpoint": {
        "uri": "https://sns.amazonaws.com/example.topic",
        "authorization": {
            "type": "AWS_IAM",
            "arn": "arn:aws:iam::us-east-1:1"
        }
    }
}

Request body properties

Property Description Type Required

name

Name for the subscription.

String

Yes

events

List of skill development events that trigger notifications to the subscriber endpoint. For more details about events, see Alexa Skill Development Event Schemas.

Valid values: AlexaDevelopmentEvent.ManifestUpdate, AlexaDevelopmentEvent.SkillPublish, AlexaDevelopmentEvent.SkillCertification, AlexaDevelopmentEvent.InteractionModelUpdate, AlexaDevelopmentEvent.All, AlexaCustomerFeedbackEvent.SkillReviewPublish.

Array of strings

Response

A successful response returns 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Subscription updated successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.


Was this page helpful?

Last updated: Nov 29, 2023