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.


_cid string
The primary key
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.)
A string containing a user cid
_acknowledged_on number
When the alert was acknowledged
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.
Either true or false
_last_modified number
The point in time when this object was last updated.
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.
A string containing a user cid
acknowledged_until number or string
The time this acknowledgement expires
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.
A string containing an alert cid
notes string
User notes on the acknowledgement
"Dave is dealing with this."
A string containing freeform text


Fetching Acknowledgements

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

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

From this we can see:

  • That this was an acknowledgement for the alert /alert/1098869
  • That the acknowledgement started when it was _acknowledged_on at 1382104711 (2013-10-18T13:58:31Z) and ended five minutes later since it was _acknowledged_until 1382105011 (2013-10-18T14:03:31Z.)
  • It was _acknowledged_by /user/2345 (which therefore is presumably the user responsible for dealing with whatever the problem was for that duration)

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

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

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

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

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