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

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 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"
        },
        {
          ...
        },
        ...
    ]
 }

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.

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

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.

Was this page helpful?

Last updated: Nov 27, 2023