API Documentation | Annotation

Annotations allow you to mark important events on your account. They are displayed above graphs in the annotations bar, where you can choose which categories of annotations you want shown, and help in correlation of events across the systems / business.

Fields

_cid string
The primary key
"/annotation/12345"
A string containing a annotation cid
_created number
The point in time when this object was created
1578146580
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
_last_modified number
The point in time when this object was last updated.
1578146580
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/923"
A string containing a user cid
category string
The annotation category that this annotation belongs to.
"upgrades"
A string containing freeform text
description string
A description of the annotation.
"Installed holographic storage to improve performance"
A string containing freeform text
rel_metrics array
Metrics that are associated with this annotation
["54321_kbps"]
An array
string (zero or more times)
A metric that is associated with this annotation
A string containing a fully qualified metric name in the format <digits>_<string>.
start number
The point in time that the period this annotation applies to began.
1577923232
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
stop number
The point in time that the period this annotation applies to ended.
15779268106
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
title string
The title of the annotation.
"Disk Upgrade"
A string containing freeform text

Example

Fetching Annotations

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

GET /annotation/12345
{"category":"upgrades","description":"Installed holographic storage to improve performance","_created":1578146580,"_cid":"/annotation/12345","rel_metrics":["54321_kbps"],"stop":15779268106,"title":"Disk Upgrade","start":1577923232,"_last_modified":1578146580,"_last_modified_by":"/user/923"}

From this we can see some important things:

Creating and Updating Annotations

Creating a new annotation is as simple as making a HTTP POST request to /annotation and passing JSON representing the new annotation:

POST /annotation
{"category":"support holidays","start":1383222600,"description":"Mark going trick or treating, unavailable for support","title":"Mark unavailable","stop":1383242400}

As is usual, the POST request returns the full JSON in the response (incuding the new annotation's cid, and any default and read only values)

Annotations can be updated simply by using the PUT HTTP method with new field values:

PUT /annotation/2552
{"stop":1380567600}

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

Listing and Filtering Annotations

Annotations can be listed simply by performing a HTTP GET request on /annotation. You can apply filters in the usual way, for example to list all support holidays in Q4 2013:

Note on filtering, you should not use a filter without a search parameter as well, using just a filter may become unsupported in the future. Please see the section on API searching.

GET /annotation?search=(category%3Asupport%20holidays)&f_start_ge=1380567600&f_start_lt=1388516400
[{"_last_modified":1382973501,"_last_modified_by":"/user/923","start":1383222600,"rel_metrics":[],"stop":1380567600,"title":"Mark unavaible","_created":1382973163,"description":"Mark going trick or treating, unavaible for support","_cid":"/annotation/2552","category":"support holidays"},{"category":"support holidays","_cid":"/annotation/2553","_created":1382973671,"description":"Mark eating turkey, unavailable for support","stop":1385665200,"title":"Mark unavailable","rel_metrics":[],"start":1385622000,"_last_modified_by":"/user/923","_last_modified":1382973903},{"_last_modified_by":"/user/923","_last_modified":1382973856,"start":1387911600,"_cid":"/annotation/2554","_created":1382973737,"description":"Mark opening presents, unavailable for support","title":"Mark unavailable","stop":1387998000,"rel_metrics":[],"category":"support holidays"},{"_last_modified":1382974012,"_last_modified_by":"/user/923","start":1388473200,"rel_metrics":[],"title":"Mark unavailable","stop":1388516400,"description":"Mark watching times square ball drop, unavailable for support","_created":1382974012,"_cid":"/annotation/2555","category":"support holidays"}]

Removing Annotations

Annotations can be simply removed by using the DELETE HTTP method on the cid:

DELETE /annotation/2552