This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Enterprise Open source Grafana Cloud

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.

MethodSummaryPath
GETGet all foldersfolders
GETGet folder by uidfolders/{uid}
POSTCreate folderfolders
PUTUpdate folderfolders/{uid}
DELETEDelete folderfolders/{uid}

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 return
  • continue (optional): Continue token from a previous response to fetch the next page

Required permissions:

See note in the introduction for an explanation.

ActionScope
folders:readfolders:*

Example request

The following example shows a request to get all folders:

http
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
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:

http
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
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 the metadata.name field in the folder response.

Required permissions:

See note in the introduction for an explanation.

ActionScope
folders:readfolders:*

Example request

The following example shows a request to get a folder by UID:

http
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
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.

ActionScope
folders:createfolders:*
folders:writefolders:*

Example request

The following example shows a request to create a folder:

http
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
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 the metadata.name field in the folder response.

Required permissions:

See note in the introduction for an explanation.

ActionScope
folders:writefolders:*

Example request

The following example shows a request to update a folder:

http
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
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 the metadata.name field in the folder response.

Required permissions:

See note in the introduction for an explanation.

ActionScope
folders:deletefolders:*

Example request

The following example shows a request to delete a folder:

http
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
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:

CodeMeaningReturned by
200OK.Get all folders, Get folder by uid, Update, Delete
201Created.Create
201Created, if the folder doesn’t exist.Update
400Bad request (invalid JSON, missing or invalid fields, or the parent folder doesn’t exist).Create
400Bad request (invalid JSON, missing or invalid fields).Update
400Bad request (the folder isn’t empty, for example it contains subfolders, dashboards, variables, library panels, alert rules, or recording rules).Delete
401Unauthorized.All endpoints
403Access denied.All endpoints
404Folder not found.Get folder by uid, Delete
404The parent folder doesn’t exist.Update
409Conflict (a folder with the same uid already exists).Create
409Conflict (the folder changed since you read it).Update