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.

Differences between Alarms REST API and Alerts Interface

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

Note: The smallest unit of time that can trigger an alarm is a minute – you can not use seconds. If seconds are specified, the alarm rounds down to the previous whole minute. For example, 07:15:55 rounds down to 07:15:00.

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	Frequency `freq`	Day of the week `byDay`	Interval `interval`
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"
        },
        {
          ...
        },
        ...
    ]
 }

Note: The Alerts Interface SetAlert directive defines additional fields such as 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>`

Note: A token is valid for 30 minutes before it expires.

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.

Note: Performing this operation on an alarm always sets the status to ON.

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

Note: Performing this operation on an alarm that is 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`

Note: This sets the 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