Folder HTTP API
Note
Available in Grafana 12.0 and later.
This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.
This document may not contain the latest version of the API. For the most up-to-date list of available endpoints, refer to folder.grafana.app/v1 in Swagger.
Requirements
If you’re running Grafana Enterprise or Grafana Cloud, some endpoints require specific permissions. For more information, refer to Role-based access control permissions.
Endpoints
Base path: /apis/folder.grafana.app/v1/namespaces/{namespace}/
Replace {namespace} with your namespace. To learn which namespace to use, refer to the
API overview.
Get all folders
GET /apis/folder.grafana.app/v1/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.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Query parameters:
limit(optional): Maximum number of folders to returncontinue(optional): Continue token from a previous response to fetch the next page
Required permissions:
See note in the introduction for an explanation.
Example request
The following example shows a request to get all folders:
GET /apis/folder.grafana.app/v1/namespaces/default/folders?limit=1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "FolderList",
"apiVersion": "folder.grafana.app/v1",
"metadata": {
"continue": "eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ=="
},
"items": [
{
"kind": "Folder",
"apiVersion": "folder.grafana.app/v1",
"metadata": {
"name": "aef30vrzxs3y8d",
"namespace": "default",
"uid": "KCtv1FXDsJmTYQoTgcPnfuwZhDZge3uMpXOefaOHjb4X",
"resourceVersion": "1741343686000",
"creationTimestamp": "2025-03-07T10:34:46Z",
"annotations": {
"grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedTimestamp": "2025-03-07T10:34:46Z"
}
},
"spec": {
"title": "example"
}
}
]
}The metadata.continue field contains a token to fetch the next page.
Example subsequent request using continue token
The following example shows a request for the next page, using the continue token from the previous response:
GET /apis/folder.grafana.app/v1/namespaces/default/folders?limit=1&continue=eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ== HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example subsequent response
The following example shows the response for the next page:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "FolderList",
"apiVersion": "folder.grafana.app/v1",
"items": [
{
"kind": "Folder",
"apiVersion": "folder.grafana.app/v1",
"metadata": {
"name": "bef30vrzxs3y8e",
"namespace": "default",
"uid": "YCtv1FXDsJmTYQoTgcPnfuwZhDZge3uMpXOefaOHjb5Y",
"resourceVersion": "1741343687000",
"creationTimestamp": "2025-03-07T10:35:47Z",
"annotations": {
"grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedTimestamp": "2025-03-07T10:35:47Z"
}
},
"spec": {
"title": "another folder"
}
}
]
}Continue making requests with the updated continue token until you receive a response without a continue field in the metadata, indicating you’ve reached the last page.
Get folder by uid
GET /apis/folder.grafana.app/v1/namespaces/{namespace}/folders/{uid}
Will return the folder given the folder uid.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{uid}: The unique identifier of the folder. This is themetadata.namefield in the folder response.
Required permissions:
See note in the introduction for an explanation.
Example request
The following example shows a request to get a folder by UID:
GET /apis/folder.grafana.app/v1/namespaces/default/folders/aef30vrzxs3y8d HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "Folder",
"apiVersion": "folder.grafana.app/v1",
"metadata": {
"name": "aef30vrzxs3y8d",
"namespace": "default",
"uid": "KCtv1FXDsJmTYQoTgcPnfuwZhDZge3uMpXOefaOHjb4X",
"resourceVersion": "1741343686000",
"creationTimestamp": "2025-03-07T10:34:46Z",
"annotations": {
"grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedTimestamp": "2025-03-07T10:34:46Z",
"grafana.app/folder": "fef30w4jaxla8b"
}
},
"spec": {
"title": "test"
}
}Note the annotation grafana.app/folder which contains the uid of the parent folder.
Create folder
POST /apis/folder.grafana.app/v1/namespaces/{namespace}/folders
Creates a new folder.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Required permissions:
See note in the introduction 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.
Example request
The following example shows a request to create a folder:
POST /apis/folder.grafana.app/v1/namespaces/default/folders HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"metadata": {
"name": "aef30vrzxs3y8d",
"annotations": {
"grafana.app/folder": "fef30w4jaxla8b"
}
},
"spec": {
"title": "child-folder"
}
}JSON body schema:
- metadata.name – The Grafana
unique identifier. 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.
Note
Custom labels and annotations in the metadata field are supported on some instances, with full support planned for all instances when these APIs reach general availability. If they are not yet supported on your instance, they will be ignored.
Example response
The following example shows the response:
HTTP/1.1 201
Content-Type: application/json
{
"kind": "Folder",
"apiVersion": "folder.grafana.app/v1",
"metadata": {
"name": "eef33r1fprd34d",
"namespace": "default",
"uid": "X8momvVZnsXdOqvLD9I4ngqLVif2CgRWXHy9xb2UgjQX",
"resourceVersion": "1741320415009",
"creationTimestamp": "2025-03-07T04:06:55Z",
"labels": {
"grafana.app/deprecatedInternalID": "1159"
},
"annotations": {
"grafana.app/folder": "fef30w4jaxla8b",
"grafana.app/createdBy": "service-account:cef2t2rfm73lsb"
}
},
"spec": {
"title": "child-folder"
}
}Update folder
PUT /apis/folder.grafana.app/v1/namespaces/{namespace}/folders/{uid}
Updates an existing folder identified by uid.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{uid}: The unique identifier of the folder. This is themetadata.namefield in the folder response.
Required permissions:
See note in the introduction for an explanation.
Example request
The following example shows a request to update a folder:
PUT /apis/folder.grafana.app/v1/namespaces/default/folders/fef30w4jaxla8b HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"metadata": {
"name": "fef30w4jaxla8b",
"annotations": {
"grafana.app/folder": "xkj92m5pqw3vn4"
}
},
"spec": {
"title": "updated title"
}
}JSON body schema:
- metadata.name – The unique identifier 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.
Note
Custom labels and annotations in the metadata field are supported on some instances, with full support planned for all instances when these APIs reach general availability. If they are not yet supported on your instance, they will be ignored.
Example response
The following example shows the response:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "Folder",
"apiVersion": "folder.grafana.app/v1",
"metadata": {
"name": "fef30w4jaxla8b",
"namespace": "default",
"uid": "YaWLsFrMwEaTlIQwX2iMnhHlJuZHtZugps50BQoyjXEX",
"resourceVersion": "1741345736000",
"creationTimestamp": "2025-03-07T11:08:56Z",
"annotations": {
"grafana.app/folder": "xkj92m5pqw3vn4",
"grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedTimestamp": "2025-03-07T11:08:56Z"
}
},
"spec": {
"title": "updated title"
}
}Delete folder
DELETE /apis/folder.grafana.app/v1/namespaces/{namespace}/folders/{uid}
Deletes an existing empty folder identified by UID. This operation can’t be reverted.
If the folder contains subfolders, dashboards, variables, library panels, alert rules, or recording rules, the request fails with 400 Bad Request. Move or delete the folder contents first.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{uid}: The unique identifier of the folder. This is themetadata.namefield in the folder response.
Required permissions:
See note in the introduction for an explanation.
Example request
The following example shows a request to delete a folder:
DELETE /apis/folder.grafana.app/v1/namespaces/default/folders/fef30w4jaxla8b HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "Folder",
"apiVersion": "folder.grafana.app/v1",
"metadata": {
"name": "fef30w4jaxla8b",
"namespace": "default",
"uid": "YaWLsFrMwEaTlIQwX2iMnhHlJuZHtZugps50BQoyjXEX",
"resourceVersion": "1741345736000",
"creationTimestamp": "2025-03-07T11:08:56Z",
"annotations": {
"grafana.app/folder": "xkj92m5pqw3vn4",
"grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
"grafana.app/updatedTimestamp": "2025-03-07T11:08:56Z"
}
},
"spec": {
"title": "updated title"
}
}Status codes
The endpoints on this page return the following status codes:


