# Annotations and Events API

Contents

* [Annotations and Events API](https://docs.hostedgraphite.com/api-guides/annotations-and-events-api)
  * [Creating an annotation](#creating-an-annotation-for-the-impatient)
  * [Delete a single event](#delete-a-single-event)
  * [Graphite Events](#graphite-events)
    * [Graphite Composer](#graphite-composer)
  * [Dashboard Annotations](#dashboard-annotations)

Hosted Graphite supports Annotations and Graphite Events. The Annotations feature is designed as a simpler interface to create events with tags. An annotation relates your metrics to intermittent events for example when you deploy code, run some tests (hopefully successfully), or a long-running job completes.

### [Creating an Annotation](#creating-an-annotation-for-the-impatient)

<mark style="color:green;">`POST`</mark> `/api/v1/annotations/events/`

Create an annotation with titles, tags, and descriptions that will be time-stamped as it is received.

#### Path Parameters

| Name                                    | Type   | Description                                                                                                                                                                                                                                    |
| --------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| title<mark style="color:red;">\*</mark> | String | A short summary of the annotation.                                                                                                                                                                                                             |
| description                             | String | A more in-depth description of the annotation.                                                                                                                                                                                                 |
| tags                                    | String | A single word or multiple short strings (all case-insensitive) to organize different types of events. *e.g.* ‘deployments’, ‘feature’, ‘test’ etc.                                                                                             |
| start\_time                             | String | Unix timestamp describing when the event occurred. If this is not specified, the time of event creation is used.                                                                                                                               |
| end\_time                               | String | Optional timestamp describing when the event completed. **Note:** We currently don’t support [region events](http://docs.grafana.org/reference/annotations/#adding-regions-events). As a result, *end\_time* has no actual use in annotations. |

{% tabs %}
{% tab title="201 " %}
Created
{% endtab %}

{% tab title="400 " %}
Bad Request
{% endtab %}
{% endtabs %}

This snippet of code will create an annotation with the tags “deployment” and “feature”, titled “New Super-duper Feature”:

```
curl -X POST https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/annotations/events/ -d \
"&title=New Super-duper Feature\
&tag=deployment\
&tag=feature"
```

There’s no restriction on having annotations with the same time stamps, but the combination of start time and title must be unique.

**Authentication**:

The API uses basic HTTP authorization. An example using curl:

```bash
curl -X POST https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/annotations/events/
```

or

```bash
curl -u 'YOUR-API-KEY:' -X POST https://api.hostedgraphite.com/api/v1/annotations/events/
```

***

### [Delete a single event](#delete-a-single-event)

## Delete an annotation

<mark style="color:red;">`DELETE`</mark> `/api/v1/annotations/events/`

#### Path Parameters

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| title<mark style="color:red;">\*</mark>     | String |             |
| timestamp<mark style="color:red;">\*</mark> | String |             |

{% tabs %}
{% tab title="200 " %}
OK
{% endtab %}

{% tab title="400 " %}
Bad Request
{% endtab %}
{% endtabs %}

**Curl example**:

```bash
curl -X DELETE https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/annotations/events/ \
     -d '{"title": "New Super-duper Feature", "timestamp": 1431607046}'
```

***

### [Graphite Events](#graphite-events)

Events as per the Graphite project are fully supported. Insertion and rendering of [Graphite Events](https://graphite.readthedocs.io/en/latest/events.html#graphite-events) work the same as the annotations endpoint, though the Graphite events API takes a JSON formatted data structure. Here's an example of creating a single Graphite event:

```bash
curl -X POST https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/graphite/events/ \
     -d '{"what": "New Super-duper Feature", "when":1431607046, "tags":"deployment feature"}'
```

#### [Graphite Composer](#graphite-composer)

**Annotations**:

To support the display of Annotations, there is a function **annotations()** available in graphite to query and display the events. There are two options:

```bash
annotations("*")
```

This first option with a wildcard queries all available annotations for the time period selected

```bash
annotations("restart", "deployment")
```

This version queries all annotations with the tags “restart” and “deployment” for the time period selected

**Events**:

The graphite events function **events()** is also available:

```bash
drawAsInfinite(events("*")
drawAsInfinite(events("restart", "deployment")
```

***

### [Dashboard Annotations](#dashboard-annotations)

The dashboard annotations feature works exactly as specified in the [annotation documentation](https://grafana.com/docs/grafana/latest/dashboards/annotations/). It can be used to query by tags (not graphite targets).

* To open the annotations panel, click the settings icon in the top bar and select *Annotations:*

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2FRf4EPGBh48A7Bbao8nHG%2Fannotations-example.png?alt=media&#x26;token=34c2bd55-2f75-4914-bdaa-9e54592945e8" alt=""><figcaption><p>Locate annotations in dashboard settings</p></figcaption></figure>

* Set the datasource to ‘hostedgraphite’ and use the ‘Graphite event tags’ input box to filter by tags (Individual wildcards also work to display all events):

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2F66IEsuiY8jDA0KuHVPU3%2Fcreate-new-annotation.png?alt=media&#x26;token=b288bb08-d8d3-454e-94d6-d038424cf6d1" alt=""><figcaption><p>Configure the annotation query with tags</p></figcaption></figure>

* You can now see annotations rendered on your graph, and can hover over the base to see the tags and description:

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2FQlQibCErTm5bVCNN97J5%2Fannotation-example.png?alt=media&#x26;token=40e9f4e7-c1c4-40d2-8172-fec09d8ea77e" alt=""><figcaption><p>Visualize annotations</p></figcaption></figure>