Dashboard Versions

    Query parameters:

    • limit - Maximum number of results to return
    • start - Version to start from when returning queries

    Gets all existing dashboard versions for the dashboard with the given dashboardId.

    Example request for getting all dashboard versions:

    Example Response

    1. HTTP/1.1 200 OK
    2. Content-Type: application/json; charset=UTF-8
    3. Content-Length: 428
    5. [
    6.   {
    7.     "id": 2,
    8.     "dashboardId": 1,
    9.     "parentVersion": 1,
    10.     "restoredFrom": 0,
    11.     "version": 2,
    12.     "created": "2017-06-08T17:24:33-04:00",
    13.     "createdBy": "admin",
    14.     "message": "Updated panel title"
    15.   },
    16.   {
    17.     "id": 1,
    18.     "dashboardId": 1,
    19.     "parentVersion": 0,
    20.     "restoredFrom": 0,
    21.     "version": 1,
    22.     "created": "2017-06-08T17:23:33-04:00",
    23.     "createdBy": "admin",
    24.     "message": "Initial save"
    25.   }
    26. ]

    Status Codes:

    • 200 - Ok
    • 400 - Errors
    • 401 - Unauthorized
    • 404 - Dashboard version not found

    Get all dashboard versions by dashboard UID

    Query parameters:

    • limit - Maximum number of results to return
    • start - Version to start from when returning queries

    GET /api/dashboards/uid/:uid/versions

    Gets all existing dashboard versions for the dashboard with the given uid.

    Example request for getting all dashboard versions:

    1. GET /api/dashboards/uid/QA7wKklGz/versions?limit=2?start=0 HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

    Example Response

    1. HTTP/1.1 200 OK
    2. Content-Type: application/json; charset=UTF-8
    3. Content-Length: 428
    5. [
    6.   {
    7.     "id": 2,
    8.     "dashboardId": 1,
    9.     "uid": "QA7wKklGz",
    10.     "parentVersion": 1,
    11.     "restoredFrom": 0,
    12.     "version": 2,
    13.     "created": "2017-06-08T17:24:33-04:00",
    14.     "createdBy": "admin",
    15.     "message": "Updated panel title"
    16.   },
    17.   {
    18.     "id": 1,
    19.     "dashboardId": 1,
    20.     "uid": "QA7wKklGz",
    21.     "parentVersion": 0,
    22.     "restoredFrom": 0,
    23.     "version": 1,
    24.     "created": "2017-06-08T17:23:33-04:00",
    25.     "createdBy": "admin",
    26.     "message": "Initial save"
    27.   }
    28. ]

    Status Codes:

    • 200 - Ok
    • 400 - Errors
    • 401 - Unauthorized
    • 404 - Dashboard version not found

    GET /api/dashboards/id/:dashboardId/versions/:version

    Get the dashboard version with the given version, for the dashboard with the given id.

    Example request for getting a dashboard version:

    1. GET /api/dashboards/id/1/versions/1 HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

    Status Codes:

    • 200 - Ok
    • 401 - Unauthorized
    • 404 - Dashboard version not found

    Get dashboard version by dashboard UID

    GET /api/dashboards/uid/:uid/versions/:version

    Get the dashboard version with the given version, for the dashboard with the given UID.

    Example request for getting a dashboard version:

    1. GET /api/dashboards/id/1/versions/1 HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

    Example response:

    1. HTTP/1.1 200 OK
    2. Content-Type: application/json; charset=UTF-8
    5.   "id": 1,
    6.   "dashboardId": 1,
    7.   "uid": "QA7wKklGz",
    8.   "parentVersion": 0,
    9.   "restoredFrom": 0,
    10.   "version": 1,
    11.   "created": "2017-04-26T17:18:38-04:00",
    12.   "message": "Initial save",
    13.   "data": {
    14.     "annotations": {
    15.       "list": [
    17.       ]
    18.     },
    19.     "editable": true,
    20.     "gnetId": null,
    21.     "graphTooltip": 0,
    22.     "id": 1,
    23.     "links": [
    25.     ],
    26.     "rows": [
    27.       {
    28.         "collapse": false,
    29.         "height": "250px",
    30.         "panels": [
    32.         ],
    33.         "repeat": null,
    34.         "repeatIteration": null,
    35.         "repeatRowId": null,
    36.         "showTitle": false,
    37.         "title": "Dashboard Row",
    38.         "titleSize": "h6"
    39.       }
    40.     ],
    41.     "schemaVersion": 14,
    42.     "style": "dark",
    43.     "tags": [
    45.     ],
    46.     "templating": {
    47.       "list": [
    49.       ]
    50.     },
    51.     "time": {
    52.       "from": "now-6h",
    53.       "to": "now"
    54.     },
    55.     "timepicker": {
    56.       "refresh_intervals": [
    57.         "5s",
    58.         "10s",
    59.         "30s",
    60.         "1m",
    61.         "5m",
    62.         "15m",
    63.         "30m",
    64.         "1h",
    65.         "2h",
    66.         "1d"
    67.       ],
    68.       "time_options": [
    69.         "5m",
    70.         "15m",
    71.         "1h",
    72.         "6h",
    73.         "12h",
    74.         "24h",
    75.         "2d",
    76.         "7d",
    77.         "30d"
    78.       ]
    79.     },
    81.     "title": "test",
    82.     "version": 1
    83.   },
    84.   "createdBy": "admin"
    85. }

    Status Codes:

    • 200 - Ok
    • 401 - Unauthorized
    • 404 - Dashboard version not found

    POST /api/dashboards/id/:dashboardId/restore

    Restores a dashboard to a given dashboard version.

    Example request for restoring a dashboard version:

    1. POST /api/dashboards/id/1/restore
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
    5. {
    6.   "version": 1
    7. }

    JSON body schema:

    • version - The dashboard version to restore to

    Example response:

    1. HTTP/1.1 200 OK
    2. Content-Type: application/json; charset=UTF-8
    3. Content-Length: 67
    5. {
    6.   "slug": "my-dashboard",
    7.   "status": "success",
    8.   "version": 3
    9. }

    JSON response body schema:

    • slug - the URL friendly slug of the dashboard’s title
    • status - whether the restoration was successful or not
    • version - the new dashboard version, following the restoration

    Status codes:

    • 200 - OK
    • 401 - Unauthorized
    • 404 - Not found (dashboard not found or dashboard version not found)
    • 500 - Internal server error (indicates issue retrieving dashboard tags from database)

    Example error response

    JSON response body schema:

    • message - Message explaining the reason for the request failure.

    Restore dashboard by dashboard UID

    Restores a dashboard to a given dashboard version using uid.

    Example request for restoring a dashboard version:

    1. POST /api/dashboards/uid/QA7wKklGz/restore
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
    6. {
    7.   "version": 1
    8. }

    JSON body schema:

    • version - The dashboard version to restore to

    Example response:

    1. HTTP/1.1 200 OK
    2. Content-Type: application/json; charset=UTF-8
    3. Content-Length: 67
    5. {
    6.   "id": 70,
    7.   "slug": "my-dashboard",
    8.   "status": "success",
    9.   "uid": "QA7wKklGz",
    10.   "url": "/d/QA7wKklGz/my-dashboard",
    11.   "version": 3
    12. }

    JSON response body schema:

    • slug - the URL friendly slug of the dashboard’s title
    • status - whether the restoration was successful or not
    • version - the new dashboard version, following the restoration

    Status codes:

    • 200 - OK
    • 401 - Unauthorized
    • 404 - Not found (dashboard not found or dashboard version not found)
    • 500 - Internal server error (indicates issue retrieving dashboard tags from database)

    Example error response

    1. HTTP/1.1 404 Not Found
    2. Content-Type: application/json; charset=UTF-8
    3. Content-Length: 46
    5. {
    6.   "message": "Dashboard version not found"
    7. }

    JSON response body schema:

    • message - Message explaining the reason for the request failure.

    POST /api/dashboards/calculate-diff

    Compares two dashboard versions by calculating the JSON diff of them.

    Example request:

    1. POST /api/dashboards/calculate-diff HTTP/1.1
    2. Accept: text/html
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
    6. {
    7.   "base": {
    8.     "dashboardId": 1,
    9.     "version": 1
    10.   },
    11.   "new": {
    12.     "dashboardId": 1,
    13.     "version": 2
    14.   },
    15.   "diffType": "json"
    16. }

    JSON body schema:

    • base - an object representing the base dashboard version
    • new - an object representing the new dashboard version
    • diffType - the type of diff to return. Can be “json” or “basic”.

    Example response (JSON diff):

    The response is a textual representation of the diff, with the dashboard values being in JSON, similar to the diffs seen on sites like GitHub or GitLab.

    Status Codes:

    • 200 - Ok
    • 400 - Bad request (invalid JSON sent)
    • 401 - Unauthorized
    • 404 - Not found

    Example response (basic diff):

    1. HTTP/1.1 200 OK
    2. Content-Type: text/html; charset=UTF-8
    4. <div class="diff-group">
    5.   <!-- Diff omitted -->
    6. </div>

    Status Codes:

    • 200 - OK
    • 400 - Bad request (invalid JSON sent)
    • 401 - Unauthorized
    • 404 - Not found