mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
259 lines
6.5 KiB
Markdown
259 lines
6.5 KiB
Markdown
+++
|
|
title = "Annotations HTTP API "
|
|
description = "Grafana Annotations HTTP API"
|
|
keywords = ["grafana", "http", "documentation", "api", "annotation", "annotations", "comment"]
|
|
aliases = ["/docs/grafana/latest/http_api/annotations/"]
|
|
type = "docs"
|
|
[menu.docs]
|
|
name = "Annotations"
|
|
identifier = "annotationshttp"
|
|
parent = "http_api"
|
|
+++
|
|
|
|
# Annotations resources / actions
|
|
|
|
This is the API documentation for the new Grafana Annotations feature released in Grafana 4.6. Annotations are saved in the Grafana database (sqlite, mysql or postgres). Annotations can be global annotations that can be shown on any dashboard by configuring an annotation data source - they are filtered by tags. Or they can be tied to a panel on a dashboard and are then only shown on that panel.
|
|
|
|
## Find Annotations
|
|
|
|
`GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
Query Parameters:
|
|
|
|
- `from`: epoch datetime in milliseconds. Optional.
|
|
- `to`: epoch datetime in milliseconds. Optional.
|
|
- `limit`: number. Optional - default is 100. Max limit for results returned.
|
|
- `alertId`: number. Optional. Find annotations for a specified alert.
|
|
- `dashboardId`: number. Optional. Find annotations that are scoped to a specific dashboard
|
|
- `panelId`: number. Optional. Find annotations that are scoped to a specific panel
|
|
- `userId`: number. Optional. Find annotations created by a specific user
|
|
- `type`: string. Optional. `alert`|`annotation` Return alerts or user created annotations
|
|
- `tags`: string. Optional. Use this to filter global annotations. Global annotations are annotations from an annotation data source that are not connected specifically to a dashboard or panel. To do an "AND" filtering with multiple tags, specify the tags parameter multiple times e.g. `tags=tag1&tags=tag2`.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
[
|
|
```
|
|
|
|
> Starting in Grafana v6.4 regions annotations are now returned in one entity that now includes the timeEnd property.
|
|
|
|
## Create Annotation
|
|
|
|
Creates an annotation in the Grafana database. The `dashboardId` and `panelId` fields are optional.
|
|
If they are not specified then a global annotation is created and can be queried in any dashboard that adds
|
|
the Grafana annotations data source. When creating a region annotation include the timeEnd property.
|
|
|
|
`POST /api/annotations`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/annotations HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
> The response for this HTTP request is slightly different in versions prior to v6.4. In prior versions you would
|
|
also get an endId if you where creating a region. But in 6.4 regions are represented using a single event with time and
|
|
timeEnd properties.
|
|
|
|
## Create Annotation in Graphite format
|
|
|
|
Creates an annotation by using Graphite-compatible event format. The `when` and `data` fields are optional. If `when` is not specified then the current time will be used as annotation's timestamp. The `tags` field can also be in prior to Graphite `0.10.0`
|
|
format (string with multiple tags being separated by a space).
|
|
|
|
`POST /api/annotations/graphite`
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/annotations/graphite HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Update Annotation
|
|
|
|
`PUT /api/annotations/:id`
|
|
|
|
Updates all properties of an annotation that matches the specified id. To only update certain property, consider using the [Patch Annotation](#patch-annotation) operation.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
PUT /api/annotations/1141 HTTP/1.1
|
|
Accept: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Patch Annotation
|
|
> This is available in Grafana 6.0.0-beta2 and above.
|
|
|
|
`PATCH /api/annotations/:id`
|
|
|
|
Updates one or more properties of an annotation that matches the specified id.
|
|
|
|
This operation currently supports updating of the `text`, `tags`, `time` and `timeEnd` properties.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
PATCH /api/annotations/1145 HTTP/1.1
|
|
Accept: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Delete Annotation By Id
|
|
|
|
`DELETE /api/annotations/:id`
|
|
|
|
Deletes the annotation that matches the specified id.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
DELETE /api/annotations/1 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|