grafana/docs/sources/developers/http_api/dashboard_versions.md

---
aliases:
  - ../../http_api/dashboard_versions/
  - ../../http_api/dashboardversions/
canonical: /docs/grafana/latest/developers/http_api/dashboard_versions/
description: Grafana Dashboard Versions HTTP API
keywords:
  - grafana
  - http
  - documentation
  - api
  - dashboard
  - versions
labels:
  products:
    - enterprise
    - oss
title: 'Dashboard Versions HTTP API '
---

# Dashboard Versions

## 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**:

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

**Example Response**

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 428

```

Status Codes:

- **200** - Ok
- **400** - Errors
- **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**:

```http
GET /api/dashboards/id/1/versions/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```

**Example response**:

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 1300

```

Status Codes:

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

## Restore dashboard by dashboard UID

`POST /api/dashboards/uid/:uid/restore`

Restores a dashboard to a given dashboard version using `uid`.

**Example request for restoring a dashboard version**:

```http
POST /api/dashboards/uid/QA7wKklGz/restore
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "version": 1
}
```

JSON body schema:

- **version** - The dashboard version to restore to

**Example response**:

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 67

```

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
- **400** - Bad request (specified version has the same content as the current dashboard)
- **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**

```http
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=UTF-8
Content-Length: 46

```

JSON response body schema:

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

## Compare dashboard versions

`POST /api/dashboards/calculate-diff`

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

**Example request**:

```http
POST /api/dashboards/calculate-diff HTTP/1.1
Accept: text/html
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

```

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)**:

```http
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

```

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)**:

```http
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

```

The response here is a summary of the changes, derived from the diff between the two JSON objects.

Status Codes:

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