# 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hostedgraphite.com/api-guides/annotations-and-events-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.