mirror of
https://github.com/grafana/grafana.git
synced 2026-06-15 11:29:43 -04:00
25f64d6695
* docs: fix relative aliases in api docs * change <GRAFANA_VERSION> to next in alias comments
385 lines
12 KiB
Markdown
385 lines
12 KiB
Markdown
---
|
|
aliases:
|
|
- ../../../../http_api/annotations/ # /docs/grafana/next/http_api/annotations/
|
|
- ../../../../developers/http_api/annotations/ # /docs/grafana/next/developers/http_api/annotations/
|
|
- ../../../../developer-resources/api-reference/http-api/api-legacy/annotations/ #legacy folder
|
|
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/annotations/
|
|
description: Grafana Annotations HTTP API
|
|
keywords:
|
|
- grafana
|
|
- http
|
|
- documentation
|
|
- api
|
|
- annotation
|
|
- annotations
|
|
- comment
|
|
labels:
|
|
products:
|
|
- enterprise
|
|
- oss
|
|
- cloud
|
|
title: Annotations HTTP API
|
|
---
|
|
|
|
# Annotations API
|
|
|
|
{{< docs/shared lookup="developers/deprecated-apis.md" source="grafana" version="<GRAFANA_VERSION>" >}}
|
|
|
|
Annotations are saved in the Grafana database (sqlite, mysql or postgres). Annotations can be organization 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.
|
|
|
|
## Requirements
|
|
|
|
If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
|
|
|
## Find Annotations
|
|
|
|
`GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#annotations-api) for an explanation.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
| Action | Scope |
|
|
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `annotations:read` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
|
{ .no-spacing-list }
|
|
<!-- prettier-ignore-end -->
|
|
|
|
**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`: Deprecated. Use dashboardUID instead.
|
|
- `dashboardUID`: string. Optional. Find annotations that are scoped to a specific dashboard, when dashboardUID presents, dashboardId would be ignored.
|
|
- `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 organization annotations. Organization 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 `dashboardUid` and `panelId` fields are optional.
|
|
If they are not specified then an organization 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.
|
|
|
|
The format for `time` and `timeEnd` should be epoch numbers in millisecond resolution.
|
|
|
|
`POST /api/annotations`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#annotations-api) for an explanation.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
| Action | Scope |
|
|
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `annotations:create` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
|
{ .no-spacing-list }
|
|
<!-- prettier-ignore-end -->
|
|
|
|
**Required JSON Body Fields**
|
|
|
|
- `text`: description of the annotation.
|
|
|
|
**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`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#annotations-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| -------------------- | ------------------------------- |
|
|
| `annotations:create` | `annotations:type:organization` |
|
|
|
|
**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.
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#annotations-api) for an explanation.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
| Action | Scope |
|
|
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `annotations:write` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
|
{ .no-spacing-list }
|
|
<!-- prettier-ignore-end -->
|
|
|
|
**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
|
|
|
|
`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.
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#annotations-api) for an explanation.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
| Action | Scope |
|
|
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `annotations:write` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
|
{ .no-spacing-list }
|
|
<!-- prettier-ignore-end -->
|
|
|
|
**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.
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#annotations-api) for an explanation.
|
|
|
|
<!-- prettier-ignore-start -->
|
|
| Action | Scope |
|
|
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `annotations:delete` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
|
{ .no-spacing-list }
|
|
<!-- prettier-ignore-end -->
|
|
|
|
**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
|
|
|
|
```
|
|
|
|
## Find Annotations Tags
|
|
|
|
`GET /api/annotations/tags`
|
|
|
|
Find all the event tags created in the annotations.
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#annotations-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ------------------ | ----- |
|
|
| `annotations:read` | N/A |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/annotations/tags?tag=out HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
Query Parameters:
|
|
|
|
- `tag`: Optional. A string that you can use to filter tags.
|
|
- `limit`: Optional. A number, where the default is 100. Max limit for results returned.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|