opensource/grafana
1
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-09-19 15:12:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Add dashboard and folder apis docs (#101754)

Browse Source
This commit is contained in:
Stephanie Hingtgen
2025-04-25 05:06:12 -06:00
committed by GitHub
parent 3b036f0e78
commit 40799d1f57
4 changed files with 1339 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
docs/sources/developers/http_api/apis.md Normal file
View File

@ -0,0 +1,99 @@
---
aliases:
- ../../http_api/new_api_structure/
- ../../http_api/new_api_structure/
canonical: /docs/grafana/latest/developers/http_api/new_api_structure/
description: ''
keywords:
- grafana
- http
- documentation
- api
labels:
products:
- enterprise
- oss
title: New API Structure
---
# Grafana's New API Structure
## Overview
Going forward, Grafana's HTTP API will follow a standardized API structure alongside consistent API versioning.
## API Path Structure
All Grafana APIs follow this standardized format:
```
/apis/<group>/<version>/namespaces/<namespace>/<resource>[/<name>]
```
Where the final `/<name>` segment is used for operations on individual resources (like Get, Update, Delete) and omitted for collection operations (like List, Create).
## Understanding the Components
### Group (`<group>`)
Groups organize related functionality into logical collections. For example `dashboard.grafana.app` will be used for all dashboard-related operations.
### Version (`<version>`)
These APIs will also uses semantic versioning with three stability levels:
| Level | Format | Description | Use Case |
| ----- | ---------- | --------------------------------------------------------------------------- | ------------------------ |
| Alpha | `v1alpha1` | Early development stage. Unstable, may contain bugs, and subject to removal | For testing new features |
| Beta | `v1beta1` | More stable than alpha, but may still have some changes | For early production use |
| GA | `v1` | Generally Available. Stable with backward compatibility guarantees | For production use |
### Namespace (`<namespace>`)
Namespaces isolate resources within your Grafana instance. The format varies by deployment type:
#### OSS & On-Premise Grafana
- Default organization (org 1): `default`
- Additional organizations: `org-<org_id>`
#### Grafana Cloud
- Format: `stacks-<stack_id>`
- Your instance ID is the `stack_id`. You can find this value by either:
- Going to grafana.com, clicking on your stack, and selecting "Details" on your Grafana instance
- Accessing the /swagger page in your cloud instance, where the namespace will be automatically populated on the relevant endpoints
### Resource (`<resource>`)
Represents the core resource you want to interact with, such as:
- `dashboards`
- `playlists`
- `folders`
### Name (<name>)
The `<name>` is the unique identifier for a specific instance of a resource within its namespace and resource type. `<name>` is distinct from the metadata.uid field. The URL path will always use the metadata.name.
For example, to get a dashboard defined as:
```
{
"kind": "Dashboard",
"apiVersion": "dashboard.grafana.app/v1beta1",
"metadata": {
"name": "production-overview", // This value IS used in the URL path
"namespace": "default",
"uid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8" // This value is NOT used in the URL path
// ... other metadata
},
"spec": {
// ... dashboard spec
}
}
```
You would use the following API call:
`GET /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards/production-overview`

851
docs/sources/developers/http_api/dashboard.md
View File

@ -16,22 +16,859 @@ labels:
title: Dashboard HTTP API
---
# Dashboard API
# New Dashboard APIs
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
## Identifier (id) vs unique identifier (uid)
> To view more about the new api structure, refer to [API overview]({{< ref "apis" >}}).
The identifier (id) of a dashboard is an auto-incrementing numeric value and is only unique per Grafana install.
## Create Dashboard
The unique identifier (uid) of a dashboard can be used for uniquely identify a dashboard between multiple Grafana installs.
`POST /apis/dashboard.grafana.app/v1beta1/namespaces/:namespace/dashboards`
Creates a new dashboard.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
<!-- prettier-ignore-start -->
| Action | Scope |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| `dashboards:create` | <ul><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
| `dashboards:write` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
{ .no-spacing-list }
<!-- prettier-ignore-end -->
**Example Create Request**:
```http
POST /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
JSON Body schema:
- **metadata.name** – The Grafana [unique identifier]({{< ref "#identifier-id-vs-unique-identifier-uid" >}}). If you do not want to provide this, set metadata.generateName instead to the prefix you would like for the randomly generated uid (cannot be an empty string).
- **metadata.annotations.grafana.app/folder** - Optional field, the unique identifier of the folder under which the dashboard should be created.
- **spec** – The dashboard json.
**Example Response**:
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 485
```
Status Codes:
- **201** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Access denied
- **409** – Conflict (dashboard with the same uid already exists)
## Update Dashboard
`PUT /apis/dashboard.grafana.app/v1beta1/namespaces/:namespace/dashboards/:uid`
Updates an existing dashboard via the dashboard uid.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
- uid: the unique identifier of the dashboard to update. this will be the _name_ in the dashboard response
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
<!-- prettier-ignore-start -->
| Action | Scope |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| `dashboards:write` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
{ .no-spacing-list }
<!-- prettier-ignore-end -->
**Example Update Request**:
```http
POST /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards/gdxccn HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
JSON Body schema:
- **metadata.name** – The [unique identifier]({{< ref "#identifier-id-vs-unique-identifier-uid" >}}).
- **metadata.annotations.grafana.app/folder** - Optional field, the unique identifier of the folder under which the dashboard should be created.
- **metadata.annotations.grafana.app/message** - Optional field, to set a commit message for the version history.
- **spec** – The dashboard json.
**Example Response**:
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 485
```
Status Codes:
- **200** – OK
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Access denied
- **409** – Conflict (dashboard with the same version already exists)
## Get Dashboard
`GET /apis/dashboard.grafana.app/v1beta1/namespaces/:namespace/dashboards/:uid`
Gets a dashboard via the dashboard uid.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
- uid: the unique identifier of the dashboard to update. this will be the _name_ in the dashboard response
Note: For large dashboards, add `/dto` to the end of the URL to get the full dashboard body.
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
<!-- prettier-ignore-start -->
| Action | Scope |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| `dashboards:read` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
{ .no-spacing-list }
<!-- prettier-ignore-end -->
**Example Get Request**:
```http
GET /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards/gdxccn 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: 485
```
Status Codes:
- **200** – OK
- **401** – Unauthorized
- **403** – Access denied
- **404** – Not Found
## List Dashboards
`GET /apis/dashboard.grafana.app/v1beta1/namespaces/:namespace/dashboards`
Lists all dashboards in the given organization. You can control the maximum number of dashboards returned through the `limit` query parameter. You can then use the `continue` token returned to fetch the next page of dashboards.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
Note: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
<!-- prettier-ignore-start -->
| Action | Scope |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| `dashboards:read` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
{ .no-spacing-list }
<!-- prettier-ignore-end -->
**Example Get Request**:
```http
GET /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards?limit=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: 644
```
Status Codes:
- **200** – OK
- **401** – Unauthorized
- **403** – Access denied
## Delete Dashboard
`DELETE /apis/dashboard.grafana.app/v1beta1/namespaces/:namespace/dashboards/:uid`
Deletes a dashboard via the dashboard uid.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
- uid: the unique identifier of the dashboard to update. this will be the _name_ in the dashboard response
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
<!-- prettier-ignore-start -->
| Action | Scope |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| `dashboards:delete` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
{ .no-spacing-list }
<!-- prettier-ignore-end -->
**Example Delete Request**:
```http
DELETE /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards/gdxccn 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** – OK
- **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/" >}}).
## APIs
### Unique identifier (uid) vs identifier (id)
The unique identifier (uid) of a dashboard can be used to uniquely identify a dashboard within a given org.
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](/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.
The identifier (id) of a dashboard is deprecated in favor of the unique identifier (uid).
### 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](#dashboard-api) for an explanation.
<!-- prettier-ignore-start -->
| Action | Scope |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| `dashboards:create` | <ul><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
| `dashboards:write` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
{ .no-spacing-list }
<!-- prettier-ignore-end -->
**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](/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 an existing dashboard with a given 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 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
```
### 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](#dashboard-api) for an explanation.
<!-- prettier-ignore-start -->
| Action | Scope |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| `dashboards:read` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
{ .no-spacing-list }
<!-- prettier-ignore-end -->
**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).
**Required permissions**
See note in the [introduction](#dashboard-api) for an explanation.
<!-- prettier-ignore-start -->
| Action | Scope |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| `dashboards:delete` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
{ .no-spacing-list }
<!-- prettier-ignore-end -->
**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](../folder_dashboard_search/).
"schemaVersion": 41,
"title": "New dashboard - updated",
...
}
}
```
Status Codes:
- **200** – OK
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Access denied
- **409** – Conflict (dashboard with the same version already exists)
## Get Dashboard
`GET /apis/dashboard.grafana.app/v1beta1/namespaces/:namespace/dashboards/:uid`
Gets a dashboard via the dashboard uid.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
- uid: the unique identifier of the dashboard to update. this will be the _name_ in the dashboard response
Note: For large dashboards, add `/dto` to the end of the URL to get the full dashboard body.
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
<!-- prettier-ignore-start -->
| Action | Scope |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| `dashboards:read` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
{ .no-spacing-list }
<!-- prettier-ignore-end -->
**Example Get Request**:
```http
GET /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards/gdxccn 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: 485
{
"kind": "Dashboard",
"apiVersion": "dashboard.grafana.app/v1beta1",
"metadata": {
"name": "gdxccn",
"namespace": "default",
"uid": "Cc7fA5ffHY94NnHZyMxXvFlpFtOmkK3qkBcVZPKSPXcX",
"resourceVersion": "2",
"generation": 2,
"creationTimestamp": "2025-03-06T19:57:18Z",
"annotations": {
"grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedTimestamp": "2025-03-07T02:58:36Z"
}
},
"spec": {
"schemaVersion": 41,
"title": "New dashboard - updated",
...
}
}
```
Status Codes:
- **200** – OK
- **401** – Unauthorized
- **403** – Access denied
- **404** – Not Found
## List Dashboards
`GET /apis/dashboard.grafana.app/v1beta1/namespaces/:namespace/dashboards`
Lists all dashboards in the given organization. You can control the maximum number of dashboards returned through the `limit` query parameter. You can then use the `continue` token returned to fetch the next page of dashboards.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
Note: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
<!-- prettier-ignore-start -->
| Action | Scope |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| `dashboards:read` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
{ .no-spacing-list }
<!-- prettier-ignore-end -->
**Example Get Request**:
```http
GET /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards?limit=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: 644
{
"kind": "DashboardList",
"apiVersion": "dashboard.grafana.app/v1alpha1",
"metadata": {
"resourceVersion": "1741315830000",
"continue": "org:1/start:1158/folder:"
},
"items": [
{
"kind": "Dashboard",
"apiVersion": "dashboard.grafana.app/v1alpha1",
"metadata": {
"name": "gpqcmf",
"namespace": "default",
"uid": "VQyL7pNTpfGPNlPM6HRJSePrBg5dXmxr4iPQL7txLtwX",
"resourceVersion": "1",
"generation": 1,
"creationTimestamp": "2025-03-06T19:50:30Z",
"annotations": {
"grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedTimestamp": "2025-03-06T19:50:30Z"
}
},
"spec": {
"schemaVersion": 41,
"title": "New dashboard",
"uid": "gpqcmf",
"version": 1,
...
}
}
]
}
```
Status Codes:
- **200** – OK
- **401** – Unauthorized
- **403** – Access denied
## Delete Dashboard
`DELETE /apis/dashboard.grafana.app/v1beta1/namespaces/:namespace/dashboards/:uid`
Deletes a dashboard via the dashboard uid.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
- uid: the unique identifier of the dashboard to update. this will be the _name_ in the dashboard response
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
<!-- prettier-ignore-start -->
| Action | Scope |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| `dashboards:delete` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
{ .no-spacing-list }
<!-- prettier-ignore-end -->
**Example Delete Request**:
```http
DELETE /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards/gdxccn 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
{
"kind": "Status",
"apiVersion": "v1",
"metadata": {},
"status": "Success",
"details": {
"name": "gdxccn",
"group": "dashboard.grafana.app",
"kind": "dashboards",
"uid": "Cc7fA5ffHY94NnHZyMxXvFlpFtOmkK3qkBcVZPKSPXcX"
}
}
```
Status Codes:
- **200** – OK
- **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/" >}}).
## APIs
### Unique identifier (uid) vs identifier (id)
The unique identifier (uid) of a dashboard can be used to uniquely identify a dashboard within a given org.
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](/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
The identifier (id) of a dashboard is deprecated in favor of the unique identifier (uid).
### Create / Update dashboard
`POST /api/dashboards/db`
@ -155,7 +992,7 @@ Content-Length: 97
}
```
### Get dashboard by uid
`GET /api/dashboards/uid/:uid`
@ -214,7 +1051,7 @@ Status Codes:
- **403** – Access denied
- **404** – Not found
```http
### Delete dashboard by uid
`DELETE /api/dashboards/uid/:uid`

389
docs/sources/developers/http_api/folder.md
View File

@ -16,19 +16,388 @@ labels:
title: Folder HTTP API
---
# Folder API
# New Folders APIs
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
> To view more about the new api structure, refer to [API overview]({{< ref "apis" >}}).
### Get all folders
`GET /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders`
Returns all folders that the authenticated user has permission to view within the given organization. Use the `limit` query parameter to control the maximum number of dashboards returned. To retrieve additional dashboards, utilize the `continue` token provided in the response to fetch the next page.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
**Required permissions**
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
| Action | Scope |
| -------------- | ----------- |
| `folders:read` | `folders:*` |
**Example Request**:
```http
GET /apis/folder.grafana.app/v1beta1/namespaces/default/folders?limit=1 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** – OK
- **401** – Unauthorized
- **403** – Access Denied
### Get folder by uid
`GET /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders/:uid`
Will return the folder given the folder uid.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
- uid: the unique identifier of the folder to update. this will be the _name_ in the folder response
**Required permissions**
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
| Action | Scope |
| -------------- | ----------- |
| `folders:read` | `folders:*` |
**Example Request**:
```http
GET /apis/folder.grafana.app/v1beta1/namespaces/default/folders/aef30vrzxs3y8d HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
```
Note the annotation `grafana.app/folder` which contains the uid of the parent folder.
Status Codes:
- **200** – Found
- **401** – Unauthorized
- **403** – Access Denied
- **404** – Folder not found
### Create folder
`POST /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders`
Creates a new folder.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
**Required permissions**
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
`folders:create` allows creating folders and subfolders. If granted with scope `folders:uid:general`, allows creating root level folders. Otherwise, allows creating subfolders under the specified folders.
| Action | Scope |
| ---------------- | ----------- |
| `folders:create` | `folders:*` |
| `folders:write` | `folders:*` |
**Example Request**:
```http
POST /apis/folder.grafana.app/v1beta1/namespaces/default/folders HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
JSON Body schema:
- **metadata.name** – The Grafana [unique identifier]({{< ref "#identifier-id-vs-unique-identifier-uid" >}}). If you do not want to provide this, set metadata.generateName to the prefix you would like for the uid.
- **metadata.annotations.grafana.app/folder** - Optional field, the unique identifier of the parent folder under which the folder should be created. Requires nested folders to be enabled.
- **spec.title** – The title of the folder.
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
```
Status Codes:
- **201** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Access denied
- **409** – Conflict (folder with the same uid already exists)
### Update folder
`PUT /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders/:uid`
Updates an existing folder identified by uid.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
- uid: the unique identifier of the folder to update. this will be the _name_ in the folder response
**Required permissions**
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
| Action | Scope |
| --------------- | ----------- |
| `folders:write` | `folders:*` |
**Example Request**:
```http
PUT /apis/folder.grafana.app/v1beta1/namespaces/default/folders/fef30w4jaxla8b HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
JSON Body schema:
- **metadata.name** – The [unique identifier]({{< ref "#identifier-id-vs-unique-identifier-uid" >}}) of the folder.
- **metadata.annotations.grafana.app/folder** - Optional field, the unique identifier of the parent folder under which the folder should be - update this to move the folder under a different parent folder. Requires nested folders to be enabled.
- **spec.title** – The title of the folder.
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
Status Codes:
- **200** – Updated
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Access Denied
- **404** – Folder not found
- **412** – Precondition failed (the folder has been changed by someone else). With this status code, 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
```
### Delete folder
`DELETE /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders/:uid`
Deletes an existing folder identified by UID along with all dashboards (and their alerts) stored in the folder. This operation cannot be reverted.
If [Grafana Alerting]({{< relref "/docs/grafana/latest/alerting" >}}) is enabled, you can set an optional query parameter `forceDeleteRules=false` so that requests will fail with 400 (Bad Request) error if the folder contains any Grafana alerts. However, if this parameter is set to `true` then it will delete any Grafana alerts under this folder.
- namespace: to read more about the namespace to use, see the [API overview]({{< ref "apis" >}}).
- uid: the unique identifier of the folder to delete. this will be the _name_ in the folder response
**Required permissions**
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
| Action | Scope |
| ---------------- | ----------- |
| `folders:delete` | `folders:*` |
**Example Request**:
```http
DELETE /apis/folder.grafana.app/v1beta1/namespaces/default/folders/fef30w4jaxla8b 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
- **400** – Bad Request
- **403** – Access Denied
- **404** – Folder not found
## APIs
## Identifier (id) vs unique identifier (uid)
The unique identifier (uid) of a folder can be used for uniquely identify folders within an org. It's automatically generated if not provided when creating a folder. The uid allows having consistent URLs for accessing folders and when syncing folders between multiple Grafana installs. This means that changing the title of a folder will not break any bookmarked links to that folder.
The uid can have a maximum length of 40 characters.
The identifier (id) of a folder is deprecated in favor of the unique identifier (uid).
### Get all folders
`GET /api/folders`
Returns all folders that the authenticated user has permission to view. You can control the maximum number of folders returned through the `limit` query parameter, the default is 1000. You can also pass the `page` query parameter for fetching folders from a page other than the first one.
If nested folders are enabled, the operation expects an additional optional query parameter `parentUid` with the parent folder UID, and returns the immediate subfolders that the authenticated user has permission to view.
If the parameter is not supplied, then the operation returns immediate subfolders under the root
that the authenticated user has permission to view.
**Required permissions**
See note in the [introduction](#folder-api) for an explanation.
| Action | Scope |
| -------------- | ----------- |
| `folders:read` | `folders:*` |
**Example Request**:
```http
GET /api/folders?limit=10 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
### Get folder by uid
`GET /api/folders/:uid`
Will return the folder given the folder uid.
**Required permissions**
See note in the [introduction](#folder-api) for an explanation.
| Action | Scope |
| -------------- | ----------- |
| `folders:read` | `folders:*` |
**Example Request**:
```http
GET /api/folders/nErXDvCkzzh HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
If nested folders are enabled, and the folder is nested (lives under another folder), then the response additionally contains:
- **parentUid** - The parent folder UID.
- **parents** - An array with the whole tree hierarchy, starting from the root going down up to the parent folder.
Status Codes:
- **200** – Found
- **401** – Unauthorized
- **403** – Access Denied
- **404** – Folder not found
### Create folder
`POST /api/folders`
Creates a new folder.
**Required permissions**
See note in the [introduction](#folder-api) for an explanation.
`folders:create` allows creating folders and subfolders. If granted with scope `folders:uid:general`, allows creating root level folders. Otherwise, allows creating subfolders under the specified folders.
| Action | Scope |
| ---------------- | ----------- |
| `folders:create` | `folders:*` |
| `folders:write` | `folders:*` |
**Example Request**:
```http
POST /api/folders HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
JSON Body schema:
- **uid** – Optional [unique identifier](#identifier-id-vs-unique-identifier-uid).
- **title** – The title of the folder.
- **parentUid** - Optional field, the unique identifier of the parent folder under which the folder should be created. Requires nested folders to be enabled.
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
If nested folders are enabled, and the folder is nested (lives under another folder) then the response additionally contains:
- **parentUid** - the parent folder UID.
- **parents** - an array with the whole tree hierarchy starting from the root going down up to the parent folder.
The identifier (id) of a folder is an auto-incrementing numeric value and is only unique per Grafana install.
The unique identifier (uid) of a folder can be used for uniquely identify folders between multiple Grafana installs. It's automatically generated if not provided when creating a folder. The uid allows having consistent URLs for accessing folders and when syncing folders between multiple Grafana installs. This means that changing the title of a folder will not break any bookmarked links to that folder.
Status Codes:
- **200** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
## Get all folders
- **401** – Unauthorized
- **403** – Access Denied
- **412** - Folder already exists
### Update folder
@ -75,7 +444,7 @@ Content-Type: application/json
Status Codes:
| `folders:read` | `folders:*` |
- **200** – Updated
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Access Denied
@ -133,7 +502,7 @@ Status Codes:
Status Codes:
- **200** – Deleted
JSON Body schema:
- **401** – Unauthorized
- **400** – Bad Request
- **403** – Access Denied
- **404** – Folder not found
@ -207,7 +576,7 @@ Status Codes:
- **403** – Access Denied
- **412** - Folder already exists
- **401** – Unauthorized
### Update folder
`PUT /api/folders/:uid`
@ -296,7 +665,7 @@ Content-Length: 97
}
```
### Delete folder
`DELETE /api/folders/:uid`
@ -342,7 +711,7 @@ Status Codes:
- **403** – Access Denied
- **404** – Folder not found
## Move folder
### Move folder
`POST /api/folders/:uid/move`