Annotations resources / actions

    Example Request:

    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:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    3. [
    4.     {
    5.         "id": 1124,
    6.         "alertId": 0,
    7.         "dashboardId": 468,
    8.         "panelId": 2,
    9.         "userId": 1,
    10.         "userName": "",
    11.         "newState": "",
    12.         "prevState": "",
    13.         "time": 1507266395000,
    14.         "timeEnd": 1507266395000,
    15.         "text": "test",
    16.         "metric": "",
    17.         "tags": [
    18.             "tag1",
    19.             "tag2"
    20.         ],
    21.         "data": {}
    22.     },
    23.     {
    24.         "id": 1123,
    25.         "alertId": 0,
    26.         "dashboardId": 468,
    27.         "panelId": 2,
    28.         "userName": "",
    29.         "newState": "",
    30.         "prevState": "",
    31.         "time": 1507265111000,
    32.         "text": "test",
    33.         "metric": "",
    34.         "tags": [
    35.             "tag1",
    37.         ],
    38.         "data": {}
    39.     }
    40. ]

    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.

    The format for time and timeEnd should be epoch numbers in millisecond resolution.

    POST /api/annotations

    Example Request:

    1. POST /api/annotations HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    5. {
    6.   "dashboardId":468,
    7.   "panelId":1,
    8.   "time":1507037197339,
    9.   "timeEnd":1507180805056,
    10.   "tags":["tag1","tag2"],
    11.   "text":"Annotation Description"
    12. }

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "message":"Annotation added",
    6.     "id": 1,
    7. }

    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:

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "message":"Graphite annotation added",
    6.     "id": 1
    7. }

    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 operation.

    Example Request:

    1. PUT /api/annotations/1141 HTTP/1.1
    2. Accept: application/json
    3. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
    4. Content-Type: application/json
    5. {
    7.   "timeEnd":1507180805056,
    8.   "text":"Annotation Description",
    9.   "tags":["tag3","tag4","tag5"]
    10. }

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "message":"Annotation updated"
    6. }

    PATCH /api/annotations/:id

    This operation currently supports updating of the text, tags, time and timeEnd properties.

    Example Request:

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "message":"Annotation patched"
    6. }

    Delete Annotation By Id

    DELETE /api/annotations/:id

    Deletes the annotation that matches the specified id.

    Example Request:

    1. DELETE /api/annotations/1 HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "message":"Annotation deleted"
    6. }

    GET /api/annotations/tags

    Find all the event tags created in the annotations.

    Example Request:

    • 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:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "result": {
    6.         "tags": [
    7.             {
    8.                 "tag": "outage",
    9.                 "count": 1
    10.             }
    11.         ]
    12.     }
    13. }