---
title: "Folder HTTP API | Grafana Cloud documentation"
description: "Grafana Folder HTTP API"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# 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](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/apis/).
> 
> **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](https://play.grafana.org/swagger?api=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](https://grafana.com/docs/grafana-cloud/platform/security-and-account-management/security-and-access/authentication-and-permissions/access-control/custom-role-actions-scopes/).

## 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](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/apis/).

Expand table

| Method | Summary                                                                                                                                            | Path            |
|--------|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
| GET    | [Get all folders](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#get-all-folders)       | `folders`       |
| GET    | [Get folder by `uid`](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#get-folder-by-uid) | `folders/{uid}` |
| POST   | [Create folder](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#create-folder)           | `folders`       |
| PUT    | [Update folder](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#update-folder)           | `folders/{uid}` |
| DELETE | [Delete folder](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#delete-folder)           | `folders/{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](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/apis/).

**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](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#folder-http-api) for an explanation.

Expand table

| Action         | Scope       |
|----------------|-------------|
| `folders:read` | `folders:*` |

### Example request

The following example shows a request to get all folders:

http ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/apis/).
- `{uid}`: The unique identifier of the folder. This is the `metadata.name` field in the folder response.

**Required permissions**:

See note in the [introduction](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#folder-http-api) for an explanation.

Expand table

| Action         | Scope       |
|----------------|-------------|
| `folders:read` | `folders:*` |

### Example request

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

http ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/apis/).

**Required permissions**:

See note in the [introduction](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#folder-http-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.

Expand table

| Action           | Scope       |
|------------------|-------------|
| `folders:create` | `folders:*` |
| `folders:write`  | `folders:*` |

### Example request

The following example shows a request to create a folder:

http ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/apis/#name-name). 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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/apis/).
- `{uid}`: The unique identifier of the folder. This is the `metadata.name` field in the folder response.

**Required permissions**:

See note in the [introduction](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#folder-http-api) for an explanation.

Expand table

| Action          | Scope       |
|-----------------|-------------|
| `folders:write` | `folders:*` |

### Example request

The following example shows a request to update a folder:

http ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/apis/#name-name) 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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/apis/).
- `{uid}`: The unique identifier of the folder. This is the `metadata.name` field in the folder response.

**Required permissions**:

See note in the [introduction](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#folder-http-api) for an explanation.

Expand table

| Action           | Scope       |
|------------------|-------------|
| `folders:delete` | `folders:*` |

### Example request

The following example shows a request to delete a folder:

http ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

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

Expand table

| Code  | Meaning                                                                                                                                           | Returned by                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
|-------|---------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `200` | OK.                                                                                                                                               | [Get all folders](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#get-all-folders), [Get folder by `uid`](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#get-folder-by-uid), [Update](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#update-folder), [Delete](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#delete-folder) |
| `201` | Created.                                                                                                                                          | [Create](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#create-folder)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `201` | Created, if the folder doesn’t exist.                                                                                                             | [Update](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#update-folder)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `400` | Bad request (invalid JSON, missing or invalid fields, or the parent folder doesn’t exist).                                                        | [Create](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#create-folder)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `400` | Bad request (invalid JSON, missing or invalid fields).                                                                                            | [Update](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#update-folder)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `400` | Bad request (the folder isn’t empty, for example it contains subfolders, dashboards, variables, library panels, alert rules, or recording rules). | [Delete](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#delete-folder)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `401` | Unauthorized.                                                                                                                                     | All endpoints                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `403` | Access denied.                                                                                                                                    | All endpoints                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `404` | Folder not found.                                                                                                                                 | [Get folder by `uid`](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#get-folder-by-uid), [Delete](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#delete-folder)                                                                                                                                                                                                                                                                                  |
| `404` | The parent folder doesn’t exist.                                                                                                                  | [Update](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#update-folder)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `409` | Conflict (a folder with the same `uid` already exists).                                                                                           | [Create](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#create-folder)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `409` | Conflict (the folder changed since you read it).                                                                                                  | [Update](https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/folder/#update-folder)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
