API Documentation | Acknowledgement

An acknowledgement represents a single acknowledgement of an alert. Each acknowledgement has a defined start and end point during which the alert is considered acknowledged.

Fields

_cid string
The primary key
"/acknowledgement/1234"
A string containing a acknowledgement cid
_acknowledged_by string
The user that is acknowledging the alert. This is the user that created the acknowledgement (or, in the case of acknowledgements that have been deactivated, the user who deactivated this acknowledgement.)
"/user/2345"
A string containing a user cid
_acknowledged_on number
When the alert was acknowledged
1382104711
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
_active boolean
If this acknowledgement is still in effect or not.
true
Either true or false
_last_modified number
The point in time when this object was last updated.
1382104711
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
_last_modified_by string
The object id of the last user to modify this object.
"/user/2345"
A string containing a user cid
acknowledged_until number or string
The time this acknowledgement expires
1382105011
A positive integer that represents the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom.) Attempting to set this to a time that is in the past will result in the time being set to the current time (with the exception of passing in the current value, which will leave the value unchanged.) Instead of setting the time in epoch seconds you may also pass in the number of days, hours, minutes or seconds from the current time you want the acknowledgement to expire on by passing in a string containing an integer followed by "d", "h", "m" or "s" respectivly (For example, a call made at epoch time 100000000 setting this to the string "5m" would have set the value internally to 100000300.)
alert string
The alert that this acknowledgement acknowledges.
"/alert/1098869"
A string containing an alert cid
notes string
User notes on the acknowledgement
"Dave is dealing with this."
A string containing freeform text

Example

Fetching Acknowledgements

Fetching details for an acknowledgement is as simple as performing a GET on the acknowledgement cid:

GET /acknowledgement/1234
{"acknowledged_until":1382105011,"_cid":"/acknowledgement/1234","_active":true,"_last_modified":1382104711,"_last_modified_by":"/user/2345","alert":"/alert/1098869","notes":"Dave is dealing with this","_acknowledged_by":"/user/2345","_acknowledged_on":1382104711}

From this we can see:

Creating Acknowledgements

You can can acknowledge an alert by creating a new acknowledgement. In this example we acknowledge an alert until Christmas 2020:

POST /acknowledgement
{"acknowledged_until":1356393600,"alert":"/alert/1098843"}

You'll note that you can't set the time the alert was acknowledged on - it's automatically set to the current time.

You can also acknowledge an alert for a duration using the special relative time string format. Here we acknowledge an alert for five minutes using the "5m" string:

POST /acknowledgement
{"alert":"/alert/1098843","acknowledged_until":"5m"}

Modifying an acknowledgement

You can update an existing acknowledgement by PUTing data to the cid. For example, to extend the acknowledgement window by another hour from the current time you simply PUT a new acknowledged_until value.

PUT /acknowledgement/1234
{"acknowledged_until":"1h"}

Or to change the notes:

PUT /acknowledgement/1234
{"notes":"Support ticket raised with the ISP"}

As is normal with Circonus the PUT method returns the full JSON of the updated acknowledgement in response.

Listing acknowledgements

Alerts can be filtered on any of their fields. For example, here we search for all acknowledgements to alert /alert/1234 that expired on or before 1356393600:

GET /acknowledgement?f_alert=/alert/1234&f_acknowledged_until_le=1356393600
["\u2026"]

Deleting acknowledgements

Acknowledgements cannot be deleted because they represent a historic record of something that has happened. To cancel an acknowledgement simply set an acknowledgement to be acknowledged_until the current time (or any time in the past, which will have the same effect)

PUT /acknowledgement/1234
{"acknowledged_until":0}