update docs, simplify actions and scopes (#47067)

docs/sources/http_api/annotations.md

@@ -5,14 +5,25 @@ keywords = ["grafana", "http", "documentation", "api", "annotation", "annotation
 aliases = ["/docs/grafana/latest/http_api/annotations/"]
 +++
 
-# Annotations resources / actions
+# Annotations API
 
-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.
+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 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.
+
+> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, access to endpoints will be controlled by Fine-grained access control permissions.
+> Refer to specific endpoints to understand what permissions are required.
 
 ## Find Annotations
 
 `GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100`
 
+#### Required permissions
+
+See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
+
+| Action           | Scope          |
+| ---------------- | -------------- |
+| annotations:read | annotations:\* |
+
 **Example Request**:
 
 ```http
@@ -32,7 +43,7 @@ Query Parameters:
 - `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`.
+- `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**:
 
@@ -85,13 +96,21 @@ Content-Type: application/json
 
 ## Create Annotation in Graphite format
 
-POST /api/annotations/graphite HTTP/1.1
+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]({{< ref "#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
@@ -132,6 +151,14 @@ format (string with multiple tags being separated by a space).
 ```
 
 **Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+```
+
+## Patch Annotation
 
 > This is available in Grafana 6.0.0-beta2 and above.
 
@@ -165,6 +192,14 @@ Content-Type: application/json
 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]({{< ref "#annotations-api" >}}) for an explanation.
@@ -202,6 +237,14 @@ Updates one or more properties of an annotation that matches the specified id.
 
 | 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=
 ```
 
@@ -233,6 +276,14 @@ Content-Type: application/json
 
 Deletes the annotation that matches the specified id.
 
+#### Required permissions
+
+See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
+
+| Action             | Scope                   |
+| ------------------ | ----------------------- |
+| annotations:delete | annotations:type:<type> |
+
 **Example Request**:
 
 ```http
@@ -259,6 +310,14 @@ Content-Type: application/json
 
 Find all the event tags created in the annotations.
 
+#### Required permissions
+
+See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
+
+| Action           | Scope |
+| ---------------- | ----- |
+| annotations:read | N/A   |
+
 **Example Request**:
 
 ```http