Alarms REST API
The Alarms REST API enables a user to perform CRUD (create, read, update, and delete) operations and control alarms on AVS endpoints through non-AVS devices, such as webpages or apps. One example could be a single webpage or app that controls alarms on multiple AVS devices.
The Alerts interface for AVS devices allows a user to use their voice to control alarms for that device, whereas this Alarms REST API allows users to control the alarms set on potentially numerous other AVS devices through non-voice interactions.
Differences
• Alarms REST API doesn't allow control of timers and reminders, whereas the Alerts interface does.
• AVS devices can implement the Alarms REST API in addition to the Alerts interface. The primary reason to implement both is to control alarms on other AVS devices and to use features not available through the Alerts interface, such as snoozing alarms.
- Authentication
- Base URLs
- Supported alarm types
- Unsupported features
- Supported CRUD operations
- Supported alarm statuses
- Create alarm
- Read alarm details
- Read all alarms
- Update alarm configuration
- Cancel an alarm
- Activate an alarm
- Snooze an alarm
- Cancel next occurrence of an alarm
- Activate next occurrence of an alarm
- Delete all alarms
- Delete a specific alarm
- HTTP error codes and descriptions
Authentication
You must use a Login with Amazon (LWA) access token to authenticate your device and the REST API calls. See Authorize from an AVS Product for instructions. You pass the LWA token in the authorization header for every request to the API.
Base URLs
The Alarms REST API uses an HTTP/1.1 connection.
All URLs referenced in the documentation have the following base URL, specific to the following country or region.
Region | Supported Countries/Regions | URL |
---|---|---|
Asia | Australia, Japan, New Zealand | api.fe.amazonalexa.com |
Europe | Austria, France, Germany, India, Italy, Spain, United Kingdom | api.eu.amazonalexa.com |
North America | Canada, Mexico, United States | api.amazonalexa.com |
Supported alarm types
Make sure you design your user experiences for alarms using the AVS UX guidelines for Alerts.
The following alarm types are supported:
- Standard alarms
- Custom or celebrity alarms
- Music alarms
Alarms have one of two behaviors:
scheduledTime
- Ring at a scheduled time.recurrence
- Ring and repeat on a determined schedule, for example daily or weekly.
Unsupported features
The Alarms REST API doesn't support the following features:
- Creating music alarms: Not supported. Reading, updating, and deleting music alarms is supported.
- Custom notification sounds: Only existing sounds provided by Amazon can be used.
- Device offline mode: Not supported.
- Updating alarms: Limited operations available, see Update alarm configuration for more details.
Supported CRUD operations
The Alarms REST API supports these CRUD operations.
Operation | Description | Method | URI |
---|---|---|---|
Create | Create a new alarm. | POST |
/v1/alerts/alarms |
Read | Fetch details of an alarm. | GET |
/v1/alerts/alarms/{alarmToken} |
Read | Fetch all alarms for a specific device. | GET |
/v1/alerts/alarms?endpointId=@self |
Update | Change the alarm scheduled time, recurrence pattern, device ID, and ringtone. | PUT |
/v1/alerts/alarms |
Update | Cancel - turn off. | PUT |
/v1/alerts/alarms/{alarmToken}/cancel |
Update | Activate - turn on. | PUT |
/v1/alerts/alarms/{alarmToken}/activate |
Update | Snooze. | PUT |
/v1/alerts/alarms/{alarmToken}/snooze |
Update | Cancel the next instance of an alarm. | PUT |
/v1/alerts/alarms/{alarmToken}/nextOccurrence/cancel
|
Update | Activate the next instance of an alarm, if previously canceled. | PUT |
/v1/alerts/alarms/{alarmToken}/nextOccurrence/activate
|
Delete | Delete an alarm. | DELETE |
/v1/alerts/alarms/{alarmToken} |
Delete | Delete all alarms on a specific product. | DELETE |
/v1/alerts/alarms?endpointId=@self |
Supported alarm statuses
The possible statuses of an alarm are ON
, OFF
, or SNOOZED
. The following table outlines the supported operations and corresponding alarm statuses.
Operation | Description | New Alarm Status |
---|---|---|
Create | Initiate the alarm. | ON |
Snooze | Delay the alarm from ringing. | SNOOZED |
Cancel | Turn off an upcoming alarm. | OFF |
Activate | Turn on an upcoming alarm that was previously turned off. | ON |
Update | Change the scheduled time of a specific alarm. Note: Updating an alarm activates the alarm. |
ON |
Delete | Remove the alarm from the database. | N/A |
Create alarm
Create a new alarm. This operation is only available for single and repeating standard alarms.
Method | URI |
---|---|
POST | /v1/alerts/alarms |
Request
Creates an alarm on the device that initiated the request.
Single, standard alarm
This is an example request for a single, standard alarm.
POST: /v1/alerts/alarms
Authorization: << LWA_ACCESS_TOKEN >>
Content-Type: application/json
{
"endpointId": "@self",
"trigger": {
"scheduledTime": "2018-02-25T07:30:00"
},
"assets":[
{
"type": "TONE",
"assetId": "123ABC"
}
]
}
Parameters
Parameter | Description | Type |
---|---|---|
endpointId |
Unique identifier of the endpoint or device. Accepted value: @self |
string |
trigger |
Specifies date and time the alarm rings. | object |
trigger.scheduledTime |
Required. Scheduled time of the alarm in ISO 8601 format. | long |
assets |
An array containing objects representing the alarm tones to be played. If this object is not defined, then the default tone of the device is used. | array |
assets[i].type |
Required. Asset type. Accepted value: TONE |
string |
assets[i].assetId |
Required. The assetId of the tone that will play. |
string |
Repeating alarm
POST: /v1/alerts/alarms
Authorization: << LWA_ACCESS_TOKEN >>
Content-Type: application/json
{
"endpointId": "@self",
"trigger": {
"scheduledTime": "2018-02-25T07:30:00",
"recurrence" : {
"freq" : "WEEKLY",
"byDay": ["MO"],
"interval": 1
}
},
"assets": [
{
"type": "TONE",
"assetId" : "123ABC"
}
]
}
Parameters
Parameter | Description | Type |
---|---|---|
endpointId |
Unique identifier of the endpoint or device. Accepted value: @self |
string |
trigger |
Specifies date and time in ISO 8601 format. | object |
trigger.scheduledTime |
Required. Scheduled time of the alarm in ISO 8601 format. | long |
trigger.recurrence |
An object representing an RRULE recurrence pattern for a repeating alarm. Use this value to set a repeating alarm. If this value is missing, the alarm functions as a single alarm. | object |
trigger.recurrence.freq |
Required. The frequency of the recurrence pattern. Accepted values: DAILY , WEEKLY . |
string |
trigger.recurrence.byDay |
Required. An array containing the day of week values of the recurrence. Day of week values are strings. Accepted values: MO , TU , WE , TH , FR , SA , SU |
array |
trigger.recurrence.interval |
Required. The interval of the recurrence. Enum: 1 . |
string |
assets |
An array containing objects representing the alarm tones to be played. If this object is not defined then the default tone for the product is used. | array |
assets[i].type |
Required. Asset type. Accepted value: TONE |
string |
assets[i].assetId |
Required. The assetId of the tone that will play. |
string |
Supported recurrence values
Recurrence | Frequencyfreq |
Day of the weekbyDay |
Intervalinterval |
---|---|---|---|
Daily | DAILY |
N/A | 1 |
Mondays | WEEKLY |
MO |
1 |
Tuesdays | WEEKLY |
TU |
1 |
Wednesdays | WEEKLY |
WE |
1 |
Thursdays | WEEKLY |
TH |
1 |
Fridays | WEEKLY |
FR |
1 |
Saturdays | WEEKLY |
SA |
1 |
Sundays | WEEKLY |
SU |
1 |
Weekdays | WEEKLY |
MO,TU,WE,TH,FR |
1 |
Weekends | WEEKLY |
SA,SU |
1 |
Response
Single, standard alarm
HTTP/1.1 201 Created
Date: Thu, 22 Feb 2018 12:22:40 GMT
Location: https://api.amazonalexa.com/v1/alerts/alarms/{alarmToken}
Content-Type: application/json
{
"alarmToken": "{alarmToken}",
"status": "ON",
"endpointIds": ["<ENDPOINT_ID>"],
"createdTime": "2018-02-25T07:30:00.000Z",
"updatedTime": "2018-02-25T07:30:00.000Z"
"trigger": {
"scheduledTime" : "2018-02-25T07:30:00",
"timeZoneId": "America/Los_Angeles"
}
"assets":[
{
"type": "TONE",
"assetId": "123ABC",
"displayName": "Glimmer",
"sampleUrl": "https://s3.amazonaws.com/deeappservice.prod.notificationtones/system_alerts_melodic_06.mp3"
},
{
...
},
...
]
}
assetPlayOrder
, backgroundAlertAsset
, loopCount
, loopPauseInMilliSeconds
, which are taken from the device-level settings for alarms. These parameters are not exposed on a per-alarm basis. This is why they are not included in the response payload above.Parameters
Parameter | Description | Type |
---|---|---|
alarmToken |
Unique token for the alert. | string |
status |
The alarm status. Accepted values: ON , OFF , SNOOZE . |
string |
endpointIds |
An array that contains the endpointIDs. | array |
createdTime |
A timestamp representing when the alarm was created. | string |
updatedTime |
A timestamp representing when the alarm was last updated. | string |
trigger |
Specifies date and time in ISO 8601 format. | object |
trigger.scheduledTime |
Required. Scheduled time of the alarm in ISO 8601 format. | long |
trigger.timeZoneId |
Required. A time zone id found in the IANA tz database. Note: Specifying this value on create and update is not allowed and ignored since the scheduledTime time is always interpreted using the default time zone of the device. |
string |
assets |
An array of objects containing the alarm tones. If this object is not defined then the default tone of the device is used. | array |
assets[i].type |
Required. Asset type. Accepted Value: TONE |
array |
assets[i].assetId |
The ID of the asset tone. | string |
assets[i].displayName |
The display name of the asset. Can use to display the asset in the GUI. | string |
assets[i].sampleUrl |
The download URL of the asset file. | string |
Read alarm details
Returns the details of an alarm, using an alarmToken
.
Method | URI |
---|---|
GET | /v1/alerts/alarms/{alarmToken} |
Request
GET: /v1/alerts/alarms/{alarmToken}
Authorization: << LWA_ACCESS_TOKEN >>
Content-Type: application/json
Response
A successful request returns an HTTP 200 OK
status response.
Single standard alarm
HTTP/1.1 200 OK
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json
{
"alarmToken": "{alarmToken}",
"status": "ON",
"endpointIds": ["<ENDPOINT_ID>"],
"createdTime": "2018-02-25T07:30:00.000Z",
"updatedTime": "2018-02-25T07:30:00.000Z"
"trigger": {
"scheduledTime" : "2018-02-25T07:30:00",
"timeZoneId": "America/Los_Angeles"
}
"assets":[
{
"type": "TONE",
"assetId": "123ABC",
"displayName": "Glimmer",
"sampleUrl": "https://s3.amazonaws.com/deeappservice.prod.notificationtones/system_alerts_melodic_06.mp3"
},
{
...
},
...
]
}
Repeating standard alarm
HTTP/1.1 200 OK
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json
{
"alarmToken": "{alarmToken}",
"status": "ON",
"endpointIds": ["<ENDPOINT_ID>"],
"createdTime": "2018-02-25T07:30:00.000Z",
"updatedTime": "2018-02-25T07:30:00.000Z"
"trigger": {
"scheduledTime": "2018-02-25T07:30:00",
"timeZoneId": "America/Los_Angeles",
"recurrence" : {
"freq" : "WEEKLY",
"byDay": ["MO"],
"interval": 1
}
},
"nextOccurrence": {
"status": "ON"
},
"assets":[
{
"type": "TONE",
"assetId": "123ABC",
"displayName": "Glimmer",
"sampleUrl": "https://s3.amazonaws.com/deeappservice.prod.notificationtones/system_alerts_melodic_06.mp3"
}
]
}
Single custom or music alarm
The response for a music alarm includes the response parameters for a single or repeating standard alarm.
HTTP/1.1 200 OK
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json
{
"alarmToken": "{alarmToken}",
"status": "ON",
"endpointIds": ["<ENDPOINT_ID>"],
"createdTime": "2018-02-25T07:30:00.000Z",
"updatedTime": "2018-02-25T07:30:00.000Z"
"trigger": {
"scheduledTime" : "2018-02-25T07:30:00",
"timeZoneId": "America/Los_Angeles"
}
"assets":[
{
"type": "MUSIC",
"service": "Spotify",
"assetInfo": {
"type": "STATION"
"name": "Pop 90's",
"artist": "Michael Jackson"
}
},
{
...
},
...
]
}
Parameters
Parameter | Description | Type |
---|---|---|
alarmToken |
Unique token for the alert. | string |
status |
The alarm status. Accepted values: ON , OFF , SNOOZE . |
string |
endpointIds |
An array that contains the endpointIDs. | array |
createdTime |
A timestamp representing when the alarm was created. | string |
updatedTime |
A timestamp representing when the alarm was last updated. | string |
trigger |
Specifies date and time in ISO 8601 format. | object |
trigger.scheduledTime |
Required. Scheduled time of the alarm in ISO 8601 format. | long |
trigger.timeZoneId |
Required. A time zone id as found in the IANA tz database. Specifying this value on create and update is not allowed and ignored since the scheduledTime time is always interpreted using the default time zone of the device. |
string |
assets |
An array of objects containing the alarm tones. If this object is not defined then the default tone of the device is used. | array |
assets[i].type |
Asset type. Accepted value: "MUSIC" |
string |
assets[i].service |
The service name. For example: Spotify, Amazon Music, etc. | string |
assets[i].assetInfo.type |
Description of music asset: TRACK, STATION, PLAYLIST. | string |
assets[i].assetInfo.name |
The music entity. It can be the name of a song, playlist, radio station, etc. | string |
assets[i].assetInfo.artist |
The artist name, if present. | string |
Read all alarms
Returns a list of all alarms for a specific endpoint, designated by the endpointID
.
Method | URI |
---|---|
GET | /v1/alerts/alarms?endpointId=@self |
Limit value
The results for this response are paginated, and have a default upper threshold limit of 50
. If you want, you can explicitly set the maxResults
parameter to a limit number of your choosing.
GET next page of results
To get the next page of results, set the nextToken
parameter equal to the value of the links.next
parameter returned in the response. Continue to make requests until the value of nextToken
comes back as null
.
Method | URI |
---|---|
GET | /v1/alerts/alarms?endpointId=<ENDPOINT_ID> |
Request
GET: /v1/alerts/alarms?endpointId=@self
Authorization: << LWA_ACCESS_TOKEN >>
Content-Type: application/json
Query string parameters
Parameter | Description | Type |
---|---|---|
endpointId |
Unique identifier of the endpoint or device. Accepted value: @self . |
string |
status |
Filter by status of the alarm. Possible values: ON , OFF , SNOOZED . |
string |
maxResults |
Maximum number of results returned by the API in a single call. If not provided, the default maximum number of results is 50 . |
integer |
nextToken |
The link to the next set of results for the paginated response. Use the link token from the previous response to get this value. Should be an opaque string. | string |
Response
HTTP/1.1 200 OK
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json
{
"totalCount": 7,
"links": {
"next": "null",
},
"alarms": [
{
alarm 1
},
...
{
alarm 7
}
]
}
Parameter | Description | Type |
---|---|---|
totalCount |
Total number of alarms. | number |
links |
Links to the next page of results. | object |
alarms |
An object that contains all the alarms for the specified endpoint. | object |
Update alarm configuration
Changes the alarm configuration, such as scheduled time or recurrence.
Method | URI |
---|---|
PUT | /v1/alerts/alarms/{alarmToken} |
Supported features:
- Change the alarm configuration, such as scheduled time or recurrence.
- Change the alarm tone.
Limitations:
- The
endpointId
can't be updated. - Updating the recurrence pattern deletes any instances tracked by the old recurrence pattern.
- If non-editable fields such as
status
are changed, the request is rejected. - If editable fields such as
assets
are updated to unsupported use cases for that customer or product, the request is rejected.
Example request
PUT: /v1/alerts/alarms/{alarmToken}
Authorization: << LWA_ACCESS_TOKEN >>
Content-Type: application/json
{
"trigger": {
"scheduledTime": "2018-02-25T08:30:00"
},
"assets": [
{
"type": "TONE",
"assetId": "123ABC"
}
]
}
Parameters
Parameter | Description | Type |
---|---|---|
trigger |
Specifies date and time the alarm rings. | object |
trigger.scheduledTime |
Required. Scheduled time of the alarm in ISO 8601 format. | long |
assets |
An array of objects containing the alarm tones. If this object is not defined then the default tone of the device is used. | array |
assets[i].type |
Required. Asset type: Accepted value: TONE |
string |
assets[i].assetId |
Required. The assetId of the tone that will play. |
string |
Response
Standard alarm
HTTP/1.1 200 OK
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json
{
"alarmToken": "{alarmToken}",
"status": "ON",
"endpointIds": ["<ENDPOINT_ID>"],
"createdTime": "",
"updatedTime": ""
"trigger": {
"scheduledTime" : "2018-02-25T07:30:00",
"timeZoneId": "America/Los_Angeles"
},
"assets":[
{
"type": "TONE",
"assetId": "123ABC",
"displayName": "Glimmer",
"sampleUrl": "https://s3.amazonaws.com/deeappservice.prod.notificationtones/system_alerts_melodic_06.mp3"
},
{
...
},
...
]
}
Cancel an alarm
Cancels a single or repeating alarm.
- For single alarms, the individual alarm is canceled.
- For repeating alarms, all scheduled occurrences are canceled. See update alarm configuration for more details.
- To cancel the next occurrence of a recurring alarm, see cancel next occurrence of an alarm
OFF
has no effect.Method | URI |
---|---|
PUT | /v1/alerts/alarms/{alarmToken}/cancel |
Effect on alarm status
This table outlines how the operation effects the alarm status.
Initial alarm status | New alarm status |
---|---|
ON , OFF , SNOOZED |
OFF |
Request
PUT /v1/alerts/alarms/{alarmToken}/cancel
Authorization: << LWA_ACCESS_TOKEN >>
Content-Type: application/json
Response
Standard alarm
HTTP/1.1 200 OK
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json
{
"alarmToken": "{alarmToken}",
"status": "ON",
"endpointIds": ["<ENDPOINT_ID>"],
"createdTime": "",
"updatedTime": ""
"trigger": {
"scheduledTime" : "2018-02-25T07:30:00",
"timeZoneId": "America/Los_Angeles"
},
"assets":[
{
"type": "TONE",
"assetId": "123ABC",
"displayName": "Glimmer",
"sampleUrl": "https://s3.amazonaws.com/deeappservice.prod.notificationtones/system_alerts_melodic_06.mp3"
}
],
"nextOccurrence": {
"status": "ON"
}
}
Parameters
Parameter | Description | Type |
---|---|---|
alarmToken |
Unique token for the alert. | string |
status |
The alarm status. Accepted values: ON , OFF , SNOOZE . |
string |
endpointIds |
An array that contains the endpointIDs . |
array |
createdTime |
A timestamp representing when the alarm was created. | string |
updatedTime |
A timestamp representing when the alarm was last updated. | string |
trigger |
Specifies date and time in ISO 8601 format. | object |
trigger.scheduledTime |
Required. Scheduled time of the alarm in ISO 8601 format. | long |
trigger.timeZoneId |
Required. A time zone id as found in the IANA tz database. Specifying this value on create and update is not allowed and ignored since the scheduledTime time is always interpreted using the default time zone of the device. |
string |
assets |
An array of objects containing the alarm tones. If this object is not defined then the default tone of the device is used. | array |
assets[i].type |
Required. Asset type. Accepted Value: TONE |
array |
assets[i].assetId |
The ID of the asset tone. | string |
assets[i].displayName |
The display name of the asset. Can use to display the asset in the GUI. | string |
assets[i].sampleUrl |
The download URL of the asset file. | string |
nextOccurrence |
For repeating alarms this object contains the status of the next occurrence of the alarm. | object |
nextOccurrence.status |
The alarm status. Accepted values: ON , OFF , SNOOZED . |
string |
Activate an alarm
Turns on an alarm. If successful, the server returns an HTTP 200 OK
status response, and then the body contains the updated alarm payload.
See update alarm configuration for more details on update limitations.
Method | URI |
---|---|
PUT | /v1/alerts/alarms/{alarmToken}/activate |
Effect on alarm status
This table outlines how the operation effects the alarm status.
Initial alarm status | New alarm status |
---|---|
OFF , ON |
ON |
Request
All alarm types
PUT /v1/alerts/alarms/{alarmToken}/activate
Authorization: << apiAccessId token / LWA / MAP >>
Content-Type: application/json
Response
Example response for a standard repeating alarm.
HTTP/1.1 200 OK
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json
{
"alarmToken": "{alarmToken}",
"status": "ON",
"endpointIds": ["<ENDPOINT_ID>"],
"createdTime": "",
"updatedTime": ""
"trigger": {
"scheduledTime" : "2018-02-25T07:30:00",
"timeZoneId": "America/Los_Angeles"
},
"assets":[
{
"type": "TONE",
"assetId": "123ABC",
"displayName": "Glimmer",
"sampleUrl": "https://s3.amazonaws.com/deeappservice.prod.notificationtones/system_alerts_melodic_06.mp3"
}
],
"nextOccurrence": {
"status": "ON"
}
}
Snooze an alarm
Snoozes a sounding alarm.
See update alarm configuration for more details on update limitations.
Method | URI |
---|---|
PUT | /v1/alerts/alarms/{alarmToken}/snooze |
Effect on alarm status
This table outlines how the operation effects the alarm status.
Initial alarm status | New alarm status |
---|---|
ON |
SNOOZED |
Request
PUT: /v1/alerts/alarms/{alarmToken}/snooze
Authorization: << apiAccessId token/LWA/MAP >>
Content-Type: application/json
{
"trigger": {
"scheduledTime": "2018-02-25T08:30:00"
},
"assets": [
{
"type": "TONE",
"assetId": "123ABC"
}
]
}
Response
HTTP/1.1 200 OK
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json
{
"alarmToken": "{alarmToken}",
"status": "ON",
"endpointIds": ["<ENDPOINT_ID>"],
"createdTime": "",
"updatedTime": ""
"trigger": {
"scheduledTime" : "2018-02-25T07:30:00",
"timeZoneId": "America/Los_Angeles"
},
"assets":[
{
"type": "TONE",
"assetId": "123ABC",
"displayName": "Glimmer",
"sampleUrl": "https://s3.amazonaws.com/deeappservice.prod.notificationtones/system_alerts_melodic_06.mp3"
}
],
"nextOccurrence": {
"status": "ON"
}
}
Cancel next occurrence of an alarm
Cancels the next occurrence of an alarm.
See update alarm configuration for more details on update limitations.
Method | URI |
---|---|
PUT | /v1/alerts/alarms/{alarmToken}/nextOccurrence/cancel |
Effect on alarm status
This table outlines how this operation affects the alarm status.
Initial alarm status | New alarm status |
---|---|
ON , OFF , or SNOOZED |
OFF |
Request
PUT: /v1/alerts/alarms/{alarmToken}/nextOccurrence/cancel
Authorization: << apiAccessId token/LWA/MAP >>
Content-Type: application/json
{
"trigger": {
"scheduledTime": "2018-02-25T08:30:00"
},
"assets": [
{
"type": "TONE",
"assetId": "123ABC"
}
]
}
Response
HTTP/1.1 200 OK
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json
{
"alarmToken": "{alarmToken}",
"status": "ON",
"endpointIds": ["<ENDPOINT_ID>"],
"createdTime": "",
"updatedTime": ""
"trigger": {
"scheduledTime" : "2018-02-25T07:30:00",
"timeZoneId": "America/Los_Angeles"
},
"assets":[
{
"type": "TONE",
"assetId": "123ABC",
"displayName": "Glimmer",
"sampleUrl": "https://s3.amazonaws.com/deeappservice.prod.notificationtones/system_alerts_melodic_06.mp3"
}
],
"nextOccurrence": {
"status": "OFF"
}
}
Activate next occurrence of an alarm
Activates an alarm so sounds at the next scheduled time. This action works on both single and repeating alarms. See update alarm configuration for more details on update limitations.
Method | URI |
---|---|
PUT | /v1/alerts/alarms/{alarmToken}/nextOccurrence/activate |
Effect on alarm status
This table outlines how this operation effects the alarm status.
Initial alarm status | New alarm status |
---|---|
OFF |
ON |
nextOccurrence
to ON
. If there is no scheduled nextOccurrence
, this operation has no effect.Request
PUT /v1/alerts/alarms/{alarmToken}/nextOccurrence/activate
Authorization: << LWA_ACCESS_TOKEN >>
Content-Type: application/json
Response
Standard alarm
Upon successful update to the alarm, the server returns an HTTP 200 OK
status response. A successful response contains the updated nextOccurrence
in the payload.
HTTP/1.1 200 OK
Date: Thu, 22 Feb 2018 12:22:40 GMT
Location: https://api.amazonalexa.com/v1/alerts/alarms/{alarmToken}/nextOccurrence/activate
Content-Type: application/json
{
"alarmToken": "{alarmToken}",
"status": "ON",
"endpointIds": ["<ENDPOINT_ID>"],
"createdTime": "",
"updatedTime": ""
"trigger": {
"scheduledTime" : "2018-02-25T07:30:00",
"timeZoneId": "America/Los_Angeles"
},
"assets":[
{
"type": "TONE",
"assetId": "123ABC",
"displayName": "Glimmer",
"sampleUrl": "https://s3.amazonaws.com/deeappservice.prod.notificationtones/system_alerts_melodic_06.mp3"
}
],
"nextOccurrence": {
"status": "ON"
}
}
Delete all alarms
Deletes all alarms on an endpoint.
Method | URI |
---|---|
DELETE | /v1/alerts/alarms?endpointId=@self |
Request
DELETE: /v1/alerts/alarms?endpointId=@self
Authorization: << apiAccessId token/LWA/MAP >>
Content-Type: application/json
Response
Upon successful deletion, the server returns an HTTP 204
No Content
status response. A successful response does not contain a body.
HTTP/1.1 204 No Content
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json
Delete a specific alarm
Delete a specific alarm, designated by the alarmToken
.
Method | URI |
---|---|
DELETE | /v1/alerts/alarms/{alarmToken} |
Request
DELETE: /v1/alerts/alarms/{alarmToken}
Authorization: << LWA_ACCESS_TOKEN >>
Content-Type: application/json
Response
Upon successful deletion, the server returns an HTTP 204 No Content
status response. A successful payload does not contain a body.
HTTP/1.1 204 No Content
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json
HTTP error codes and descriptions
Response
Here's an example of an error response.
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"errors": [
{
"code": "<CODE>",
"description": "<MESSAGE>"
}
]
}
Error codes
The following table lists the possible error codes for the Alarms REST API.
HTTP Code | Description | Explanation |
---|---|---|
400 |
TRIGGER_SCHEDULED_TIME_IN_PAST |
Scheduled time cannot be in past. |
400 |
TRIGGER_SCHEDULED_TIME_OUT_OF_RANGE |
Scheduled time is beyond one year. |
400 |
INVALID_TRIGGER_SCHEDULED_TIME_FORMAT |
The date format is not supported. |
400 |
INVALID_TRIGGER_RECURRENCE |
Recurrence pattern is invalid. |
400 |
INVALID_ENDPOINT_ID_FORMAT |
Invalid endpointId format. |
400 |
INVALID_ASSET_TYPE |
AssetType not supported. |
400 |
INVALID_ASSET_ID |
AssetId is invalid. |
400 |
UNSUPPORTED_TRIGGER_RECURRENCE |
Recurrence pattern is valid, but not supported. |
400 |
TRIGGER_SCHEDULED_TIME_CONFLICT |
An alarm already exists at the scheduled time. |
400 |
INVALID_ALARM_STATUS |
Alarm status not valid for the attempted operation. |
401 |
UNAUTHORIZED |
Token is valid but does not have appropriate permissions. |
403 |
MAX_ALERTS_EXCEEDED |
Max limit of alerts on the device reached (eg: 200). |
404 |
ALERT_NOT_FOUND |
Alert does not exist for customer. |
409 |
MISSING_TIME_ZONE |
Device has no time zone set |
500 |
INTERNAL_SERVER_ERROR |
Unexpected error. |
504 |
DEVICE_NOT_REACHABLE |
Device is offline or unreachable. |
Last updated: Feb 08, 2023