mirror of https://github.com/grafana/grafana
prometheushacktoberfestmetricsmonitoringalertinggrafanagoinfluxdbmysqlpostgresanalyticsdata-visualizationdashboardbusiness-intelligenceelasticsearch
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
440 lines
11 KiB
440 lines
11 KiB
---
|
|
aliases:
|
|
- ../../http_api/dashboard/
|
|
canonical: /docs/grafana/latest/developers/http_api/dashboard/
|
|
description: Grafana Dashboard HTTP API
|
|
keywords:
|
|
- grafana
|
|
- http
|
|
- documentation
|
|
- api
|
|
- dashboard
|
|
labels:
|
|
products:
|
|
- enterprise
|
|
- oss
|
|
title: Dashboard HTTP API
|
|
---
|
|
|
|
# Dashboard API
|
|
|
|
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for more information.
|
|
|
|
## Identifier (id) vs unique identifier (uid)
|
|
|
|
The identifier (id) of a dashboard is an auto-incrementing numeric value and is only unique per Grafana install.
|
|
|
|
The unique identifier (uid) of a dashboard can be used for uniquely identify a dashboard between multiple Grafana installs.
|
|
It's automatically generated if not provided when creating a dashboard. The uid allows having consistent URLs for accessing
|
|
dashboards and when syncing dashboards between multiple Grafana installs, see [dashboard provisioning]({{< relref "/docs/grafana/latest/administration/provisioning#dashboards" >}})
|
|
for more information. This means that changing the title of a dashboard will not break any bookmarked links to that dashboard.
|
|
|
|
The uid can have a maximum length of 40 characters.
|
|
|
|
## Create / Update dashboard
|
|
|
|
`POST /api/dashboards/db`
|
|
|
|
Creates a new dashboard or updates an existing dashboard. When updating existing dashboards, if you do not define the `folderId` or the `folderUid` property, then the dashboard(s) are moved to the root level. (You need to define only one property, not both).
|
|
|
|
> **Note:** This endpoint is not intended for creating folders, use `POST /api/folders` for that.
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ------------------- | ----------- |
|
|
| `dashboards:create` | `folders:*` |
|
|
|
|
**Example Request for new dashboard**:
|
|
|
|
```http
|
|
POST /api/dashboards/db HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
|
|
```
|
|
|
|
JSON Body schema:
|
|
|
|
- **dashboard** – The complete dashboard model.
|
|
- **dashboard.id** – id = null to create a new dashboard.
|
|
- **dashboard.uid** – Optional unique identifier when creating a dashboard. uid = null will generate a new uid.
|
|
- **dashboard.refresh** - Set the dashboard refresh interval. If this is lower than [the minimum refresh interval]({{< relref "/docs/grafana/latest/setup-grafana/configure-grafana#min_refresh_interval" >}}), then Grafana will ignore it and will enforce the minimum refresh interval.
|
|
- **folderId** – The id of the folder to save the dashboard in.
|
|
- **folderUid** – The UID of the folder to save the dashboard in. Overrides the `folderId`.
|
|
- **overwrite** – Set to true if you want to overwrite existing dashboard with newer version, same dashboard title in folder or same dashboard uid.
|
|
- **message** - Set a commit message for the version history.
|
|
|
|
**Example Request for updating a dashboard**:
|
|
|
|
```http
|
|
POST /api/dashboards/db 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: 78
|
|
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** – Created
|
|
- **400** – Errors (invalid json, missing or invalid fields, etc)
|
|
- **401** – Unauthorized
|
|
- **403** – Access denied
|
|
- **412** – Precondition failed
|
|
|
|
The **412** status code is used for explaining that you cannot create the dashboard and why.
|
|
There can be different reasons for this:
|
|
|
|
- The dashboard has been changed by someone else, `status=version-mismatch`
|
|
- A dashboard with the same name in the folder already exists, `status=name-exists`
|
|
- A dashboard with the same uid already exists, `status=name-exists`
|
|
- The dashboard belongs to plugin `<plugin title>`, `status=plugin-dashboard`
|
|
|
|
The response body will have the following properties:
|
|
|
|
```http
|
|
HTTP/1.1 412 Precondition Failed
|
|
Content-Type: application/json; charset=UTF-8
|
|
Content-Length: 97
|
|
|
|
```
|
|
|
|
In case of title already exists the `status` property will be `name-exists`.
|
|
|
|
## Get dashboard by uid
|
|
|
|
`GET /api/dashboards/uid/:uid`
|
|
|
|
Will return the dashboard given the dashboard unique identifier (uid). Information about the unique identifier of a folder containing the requested dashboard might be found in the metadata.
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ----------------- | -------------- |
|
|
| `dashboards:read` | `dashboards:*` |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/dashboards/uid/cIBgcSjkk HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"dashboard": {
|
|
"id": 1,
|
|
"uid": "cIBgcSjkk",
|
|
"title": "Production Overview",
|
|
"tags": [ "templated" ],
|
|
"timezone": "browser",
|
|
"schemaVersion": 16,
|
|
"version": 0
|
|
},
|
|
"meta": {
|
|
"isStarred": false,
|
|
"url": "/d/cIBgcSjkk/production-overview",
|
|
"folderId": 2,
|
|
"folderUid": "l3KqBxCMz",
|
|
"slug": "production-overview" //deprecated in Grafana v5.0
|
|
}
|
|
}
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** – Found
|
|
- **401** – Unauthorized
|
|
- **403** – Access denied
|
|
- **404** – Not found
|
|
|
|
## Delete dashboard by uid
|
|
|
|
`DELETE /api/dashboards/uid/:uid`
|
|
|
|
Will delete the dashboard given the specified unique identifier (uid).
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ------------------- | ----------------------------- |
|
|
| `dashboards:delete` | `dashboards:*`<br>`folders:*` |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
DELETE /api/dashboards/uid/cIBgcSjkk HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"title": "Production Overview",
|
|
"message": "Dashboard Production Overview deleted",
|
|
"id": 2
|
|
}
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** – Deleted
|
|
- **401** – Unauthorized
|
|
- **403** – Access denied
|
|
- **404** – Not found
|
|
|
|
## Hard delete dashboard by uid
|
|
|
|
{{% admonition type="note" %}}
|
|
This feature is currently in private preview and behind the `dashboardRestore` feature toggle.
|
|
{{% /admonition %}}
|
|
|
|
`DELETE /api/dashboards/uid/:uid/trash`
|
|
|
|
Will delete permanently the dashboard given the specified unique identifier (uid).
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ------------------- | ----------------------------- |
|
|
| `dashboards:delete` | `dashboards:*`<br>`folders:*` |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
DELETE /api/dashboards/uid/cIBgcSjkk/trash HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"title": "Production Overview",
|
|
"message": "Dashboard Production Overview deleted",
|
|
"uid": "cIBgcSjkk"
|
|
}
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** – Deleted
|
|
- **401** – Unauthorized
|
|
- **403** – Access denied
|
|
- **404** – Not found
|
|
|
|
## Restore deleted dashboard by uid
|
|
|
|
{{% admonition type="note" %}}
|
|
This feature is currently in private preview and behind the `dashboardRestore` feature toggle.
|
|
{{% /admonition %}}
|
|
|
|
`PATCH /api/dashboards/uid/:uid/trash`
|
|
|
|
Will restore a deleted dashboard given the specified unique identifier (uid).
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ------------------- | ----------------------------- |
|
|
| `dashboards:create` | `dashboards:*`<br>`folders:*` |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
PATCH /api/dashboards/uid/cIBgcSjkk/trash HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"title": "Production Overview",
|
|
"message": "Dashboard Production Overview restored",
|
|
"uid": "cIBgcSjkk"
|
|
}
|
|
```
|
|
|
|
Status Codes:
|
|
|
|
- **200** – Deleted
|
|
- **401** – Unauthorized
|
|
- **403** – Access denied
|
|
- **404** – Not found
|
|
-
|
|
|
|
## Gets the home dashboard
|
|
|
|
`GET /api/dashboards/home`
|
|
|
|
Will return the home dashboard.
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/dashboards/home HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"dashboard": {
|
|
"editable":false,
|
|
"nav":[
|
|
{
|
|
"enable":false,
|
|
"type":"timepicker"
|
|
}
|
|
],
|
|
"style":"dark",
|
|
"tags":[],
|
|
"templating":{
|
|
"list":[
|
|
]
|
|
},
|
|
"time":{
|
|
},
|
|
"timezone":"browser",
|
|
"title":"Home",
|
|
"version":5
|
|
},
|
|
"meta": {
|
|
"isHome":true,
|
|
"canSave":false,
|
|
"canEdit":false,
|
|
"canStar":false,
|
|
"url":"",
|
|
"expires":"0001-01-01T00:00:00Z",
|
|
"created":"0001-01-01T00:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Tags for Dashboard
|
|
|
|
`GET /api/dashboards/tags`
|
|
|
|
Get all tags of dashboards
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/dashboards/tags HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
[
|
|
{
|
|
"term":"tag1",
|
|
"count":1
|
|
},
|
|
{
|
|
"term":"tag2",
|
|
"count":4
|
|
}
|
|
]
|
|
```
|
|
|
|
## Dashboard Search
|
|
|
|
See [Folder/Dashboard Search API]({{< relref "folder_dashboard_search/" >}}).
|
|
|