mirror of
https://github.com/grafana/grafana.git
synced 2025-07-29 13:22:28 +08:00
b391e43472
* Revert "solve comments and retrigger the test" This reverts commit f08d2d9eca1912f89a535d7231e653ff26987a5c. * Revert "update api doc" This reverts commit cc09ceb8535fe54f654355d393d1c7f6809518e1. * Revert "remove post trim" This reverts commit 46fe8ed596ada5a047a337088278a4195b05fead. * Revert "fix typo" This reverts commit 3b3ceee16ed56d982035016d7a1c795972af6de9. * Revert "Apply suggestions from code review" This reverts commit 3b7f3b8e15c9d3f8ed1abb14a4f4013ffdc16d27. * Revert "update comments" This reverts commit b9c6260876b02b821ea91f4f2d080efe359d1787. * Revert "update doc" This reverts commit 8e4c4d7c93e9a1c58322e4cfca447c3b4dee148b. * Revert "remove feature toggle + add libraryPaneldefinition" This reverts commit d01cfcc2edd2cfcd675f658e85ad580ac995eb47. * fix some typos * Update public/app/features/dashboard/components/ShareModal/ShareExport.tsx Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com> * Update docs/sources/dashboards/export-import.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> * fix comments Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com> Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com>
544 lines
14 KiB
Markdown
544 lines
14 KiB
Markdown
+++
|
||
title = "Dashboard HTTP API "
|
||
description = "Grafana Dashboard HTTP API"
|
||
keywords = ["grafana", "http", "documentation", "api", "dashboard"]
|
||
aliases = ["/docs/grafana/latest/http_api/dashboard/"]
|
||
+++
|
||
|
||
# Dashboard API
|
||
|
||
## 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 "../administration/provisioning.md#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.
|
||
|
||
**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, id = null to create a new dashboard.
|
||
- **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.
|
||
- **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.
|
||
- **refresh** - Set the dashboard refresh interval. If this is lower than [the minimum refresh interval]({{< relref "../administration/configuration.md#min_refresh_interval">}}), then Grafana will ignore it and will enforce the minimum refresh interval.
|
||
|
||
For adding or updating an alert rule for a dashboard panel the user should declare a
|
||
`dashboard.panels.alert` block.
|
||
|
||
**Example Request for updating dashboard alert rule**:
|
||
|
||
```http
|
||
HTTP/1.1 200 OK
|
||
Content-Type: application/json; charset=UTF-8
|
||
Content-Length: 78
|
||
|
||
```
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
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).
|
||
|
||
**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
|
||
|
||
```
|
||
|
||
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
|
||
|
||
```
|
||
|
||
## 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
|
||
|
||
```
|
||
|
||
## Dashboard Search
|
||
See [Folder/Dashboard Search API]({{< relref "folder_dashboard_search.md" >}}).
|
||
|
||
## Deprecated resources
|
||
Please note that these resource have been deprecated and will be removed in a future release.
|
||
|
||
### Get dashboard by slug
|
||
**Deprecated starting from Grafana v5.0. Please update to use the new *Get dashboard by uid* resource instead**
|
||
|
||
`GET /api/dashboards/db/:slug`
|
||
|
||
Will return the dashboard given the dashboard slug. Slug is the URL friendly version of the dashboard title.
|
||
If there exists multiple dashboards with the same slug, one of them will be returned in the response.
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
GET /api/dashboards/db/production-overview HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
```
|
||
|
||
**Example Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
Status Codes:
|
||
|
||
- **200** – Found
|
||
- **401** – Unauthorized
|
||
- **403** – Access denied
|
||
- **404** – Not found
|
||
|
||
### Delete dashboard by slug
|
||
**Deprecated starting from Grafana v5.0. Please update to use the *Delete dashboard by uid* resource instead.**
|
||
|
||
`DELETE /api/dashboards/db/:slug`
|
||
|
||
Will delete the dashboard given the specified slug. Slug is the URL friendly version of the dashboard title.
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
DELETE /api/dashboards/db/test HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
```
|
||
|
||
**Example Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
Status Codes:
|
||
|
||
- **200** – Deleted
|
||
- **401** – Unauthorized
|
||
- **403** – Access denied
|
||
- **404** – Not found
|
||
- **412** – Precondition failed
|
||
|
||
The **412** status code is used when there exists multiple dashboards with the same slug.
|
||
The response body will look like this:
|
||
|
||
```http
|
||
HTTP/1.1 412 Precondition Failed
|
||
Content-Type: application/json; charset=UTF-8
|
||
Content-Length: 97
|
||
|
||
```
|