mirror of
https://github.com/grafana/grafana.git
synced 2025-07-28 12:22:25 +08:00

* Use relative aliases for all non-current Grafana aliases Prevents non-latest documentation "stealing" the page away from latest and through permanent redirects for latest pages that no longer exist. The redirected pages are indexed by search engines but our robots.txt forbids them crawling the non-latest page. Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Remove aliases from shared pages Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Rewrite all current latest aliases to be next Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix typo in latest alias Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Remove all current page aliases find docs/sources -type f -name '*.md' -exec sed -z -i 's#\n *- /docs/grafana/next/[^\n]*\n#\n#' {} \; find docs/sources -type f -name '*.md' -exec sed -Ez -i 's#\n((aliases:\n *-)|aliases:\n)#\n\2#' {} \; Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Prettier Signed-off-by: Jack Baldry <jack.baldry@grafana.com> Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
374 lines
8.7 KiB
Markdown
374 lines
8.7 KiB
Markdown
---
|
||
aliases:
|
||
- ../../http_api/folder/
|
||
description: Grafana Folder HTTP API
|
||
keywords:
|
||
- grafana
|
||
- http
|
||
- documentation
|
||
- api
|
||
- folder
|
||
title: Folder HTTP API
|
||
---
|
||
|
||
# Folder 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 "../../administration/roles-and-permissions/access-control/custom-role-actions-scopes/" >}}) for more information.
|
||
|
||
## Identifier (id) vs unique identifier (uid)
|
||
|
||
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.
|
||
|
||
The uid can have a maximum length of 40 characters.
|
||
|
||
## A note about the General folder
|
||
|
||
The General folder (id=0) is special and is not part of the Folder API which means
|
||
that you cannot use this API for retrieving information about the General folder.
|
||
|
||
## 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.
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#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]({{< ref "#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
|
||
|
||
```
|
||
|
||
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]({{< ref "#folder-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ---------------- | ----- |
|
||
| `folders:create` | n/a |
|
||
|
||
**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](/http_api/folder/#identifier-id-vs-unique-identifier-uid).
|
||
- **title** – The title of the folder.
|
||
|
||
**Example Response**:
|
||
|
||
```http
|
||
HTTP/1.1 200
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
Status Codes:
|
||
|
||
- **200** – Created
|
||
- **400** – Errors (invalid json, missing or invalid fields, etc)
|
||
- **401** – Unauthorized
|
||
- **403** – Access Denied
|
||
- **409** - Folder already exists
|
||
|
||
## Update folder
|
||
|
||
`PUT /api/folders/:uid`
|
||
|
||
Updates an existing folder identified by uid.
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| --------------- | ----------- |
|
||
| `folders:write` | `folders:*` |
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
PUT /api/folders/nErXDvCkzz HTTP/1.1
|
||
Accept: application/json
|
||
Content-Type: application/json
|
||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||
|
||
```
|
||
|
||
JSON Body schema:
|
||
|
||
- **uid** – Provide another [unique identifier](/http_api/folder/#identifier-id-vs-unique-identifier-uid) than stored to change the unique identifier.
|
||
- **title** – The title of the folder.
|
||
- **version** – Provide the current version to be able to update the folder. Not needed if `overwrite=true`.
|
||
- **overwrite** – Set to true if you want to overwrite existing folder with newer version.
|
||
|
||
**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 **412** status code is used for explaining that you cannot update the folder and why.
|
||
There can be different reasons for this:
|
||
|
||
- The folder has been changed by someone else, `status=version-mismatch`
|
||
|
||
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 /api/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 "../../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.
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| ---------------- | ----------- |
|
||
| `folders:delete` | `folders:*` |
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
DELETE /api/folders/nErXDvCkzz 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
|
||
|
||
## Get folder by id
|
||
|
||
`GET /api/folders/id/:id`
|
||
|
||
Will return the folder identified by id.
|
||
|
||
**Required permissions**
|
||
|
||
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
|
||
|
||
| Action | Scope |
|
||
| -------------- | ----------- |
|
||
| `folders:read` | `folders:*` |
|
||
|
||
**Example Request**:
|
||
|
||
```http
|
||
GET /api/folders/id/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** – Found
|
||
- **401** – Unauthorized
|
||
- **403** – Access Denied
|
||
- **404** – Folder not found
|