From 3fb80ac4745d52cbcd14e61bd78758d26edfa166 Mon Sep 17 00:00:00 2001
From: Maria Alexandra <239999+axelavargas@users.noreply.github.com>
Date: Wed, 21 Jul 2021 10:23:15 +0200
Subject: [PATCH] Docs: update annotations docs to include typeahead support
 for tags (#36718)

* Docs: update annotations docs to include typeahead support for tags

* Docs: Update Http API annotations including new endpoint to query by tags


Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>
Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com>
---
 docs/sources/dashboards/annotations.md | 12 ++++++--
 docs/sources/http_api/annotations.md   | 38 ++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/docs/sources/dashboards/annotations.md b/docs/sources/dashboards/annotations.md
index 340fb0097c4..262c29f04a5 100644
--- a/docs/sources/dashboards/annotations.md
+++ b/docs/sources/dashboards/annotations.md
@@ -41,12 +41,18 @@ can still show them if you add a new **Annotation Query** and filter by tags. Bu
 
 ### Query by tag
 
-You can create new annotation queries that fetch annotations from the native annotation store via the `-- Grafana --` data source and by setting *Filter by* to `Tags`. Specify at least
-one tag. For example create an annotation query name `outages` and specify a tag named `outage`. This query will show all annotations you create (from any dashboard or via API) that have the `outage` tag. By default, if you add multiple tags in the annotation query, Grafana will only show annotations that have all the tags you supplied. You can invert the behavior by enabling `Match any` which means that Grafana will show annotations that contains at least one of the tags you supplied.
+
+You can create new queries to fetch annotations from the native annotation store via the `-- Grafana --` data source by setting *Filter by* to `Tags`. 
+
+Grafana v8.1 and later versions also support typeahead of existing tags, provide at least one tag.
+
+For example, create an annotation query name `outages` and specify a tag `outage`. This query will show all annotations (from any dashboard or via API) with the `outage` tag. If multiple tags are defined in an annotation query, then Grafana will only show annotations matching all the tags. To modify the behavior, enable `Match any`, and Grafana will show annotations that contain any one of the tags you provided.
+
+{{< figure src="/static/img/docs/annotations/annotations_typeahead_support-8-1-0.png" max-width="600px" >}}
 
 In Grafana v5.3+ it's possible to use template variables in the tag query. So if you have a dashboard showing stats for different services and a template variable that dictates which services to show, you can now use the same template variable in your annotation query to only show annotations for those services.
 
-{{< figure src="/static/img/docs/v53/annotation_tag_filter_variable.png" max-width="600px" >}}
+{{< figure src="/static/img/docs/annotations/annotation_tag_filter_variable-8-1-0.png" max-width="600px" >}}
 
 ## Querying other data sources
 
diff --git a/docs/sources/http_api/annotations.md b/docs/sources/http_api/annotations.md
index 190807dc095..6adbd29bd50 100644
--- a/docs/sources/http_api/annotations.md
+++ b/docs/sources/http_api/annotations.md
@@ -251,3 +251,41 @@ Content-Type: application/json
     "message":"Annotation deleted"
 }
 ```
+
+## Find Annotations Tags
+
+`GET /api/annotations/tags`
+
+Find all the event tags created in the annotations.
+
+**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
+
+{
+    "result": {
+        "tags": [
+            {
+                "tag": "outage",
+                "count": 1
+            }
+        ]
+    }
+}
+```