Folders API Reference

Table of Contents

• Authentication
• Folders
  • List Folders
  • List All Folders with Hierarchy
  • Create a Folder
  • Rename a Folder
  • Delete a Folder
  • Get Folder Item Counts
• Folder Permissions
  • Get Folder Permissions
  • Update a Built-in Role Permission
  • Update a Team Permission
  • Update a User Permission
• Error Codes

Kloudfuse provides REST endpoints under /grafana/api/ and /grafana/apis/ for folder lifecycle management (create, rename, delete) and permission assignment.

All examples on this page use a Service Account token. Replace <your-instance> with your Kloudfuse hostname and <sa-token> with a valid Service Account token.

For the Favorite Facets GraphQL API, see Favorite Facets API Reference.

Authentication

Kloudfuse APIs accept Service Account tokens in the Authorization header:

Authorization: Bearer <sa-token>

Service Account tokens are created in the Kloudfuse UI under Admin > Service Accounts. The account must have at minimum Editor role for write operations, and must have Admin folder permission on any folder whose permissions it manages.

Folders

List Folders

Returns all top-level folders the caller can access.

curl -H "Authorization: Bearer <sa-token>" \
  https://<your-instance>/grafana/api/folders

Add ?permission=Edit to return only folders the caller can edit:

curl -H "Authorization: Bearer <sa-token>" \
  "https://<your-instance>/grafana/api/folders?permission=Edit"

Response

[\
  {\
    "id": 1,\
    "uid": "ffec62bbr7v28d",\
    "title": "kfuse-cp"\
  },\
  {\
    "id": 17,\
    "uid": "bfec62n4wfpq8e",\
    "title": "kfuse-asm"\
  }\
]

List All Folders with Hierarchy

Returns all folders (paginated, up to 2000 per request) including parent/child relationships and full path metadata.

curl -H "Authorization: Bearer <sa-token>" \
  "https://<your-instance>/grafana/apis/folder.grafana.app/v1beta1/namespaces/default/folders?limit=2000"

Use the continue token from metadata.continue to fetch the next page when the result set is large.

Response

{
  "kind": "FolderList",
  "apiVersion": "folder.grafana.app/v1beta1",
  "metadata": {},
  "items": [\
    {\
      "kind": "Folder",\
      "apiVersion": "folder.grafana.app/v1beta1",\
      "metadata": {\
        "name": "cfj9y7mmsra4gd",\
        "namespace": "default",\
        "creationTimestamp": "2026-04-16T15:40:29Z",\
        "annotations": {\
          "grafana.app/folder": "afj9y67x5gw74d",\
          "grafana.app/fullpath": "java-service/demo-java-service",\
          "grafana.app/fullpathUIDs": "afj9y67x5gw74d/cfj9y7mmsra4gd"\
        }\
      },\
      "spec": {\
        "title": "demo-java-service",\
        "description": ""\
      }\
    }\
  ]
}

Key annotations on each item:

Create a Folder

Creates a new folder. To create a sub-folder, include the parent folder UID in the annotations.

# Create a root-level folder
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST \
     "https://<your-instance>/grafana/apis/folder.grafana.app/v1beta1/namespaces/default/folders" \
     -d '{\
       "spec": { "title": "my-new-folder" },\
       "metadata": {}\
     }'

# Create a sub-folder inside parent UID "ffec62bbr7v28d"
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST \
     "https://<your-instance>/grafana/apis/folder.grafana.app/v1beta1/namespaces/default/folders" \
     -d '{\
       "spec": { "title": "my-sub-folder" },\
       "metadata": {\
         "annotations": { "grafana.app/folder": "ffec62bbr7v28d" }\
       }\
     }'

Response (201 Created)

{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1beta1",
  "metadata": {
    "name": "cfjsa58pgf5z4a",
    "namespace": "default",
    "uid": "9qqppS8H2TyW0jMehIkRjGng6Xgpkg4iJcbfplkVaBUX",
    "creationTimestamp": "2026-04-21T18:58:24Z",
    "annotations": {
      "grafana.app/createdBy": "user:3",
      "grafana.app/updatedTimestamp": "2026-04-21T18:58:24Z"
    }
  },
  "spec": {
    "title": "my-new-folder",
    "description": ""
  }
}

The metadata.name value is the folder UID to use in all subsequent API calls for this folder.

Rename a Folder

Updates the folder title. The metadata.name in the body must match the UID in the URL path.

curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X PUT \
     "https://<your-instance>/grafana/apis/folder.grafana.app/v1beta1/namespaces/default/folders/cfjsa58pgf5z4a" \
     -d '{\
       "spec": { "title": "my-renamed-folder" },\
       "metadata": { "name": "cfjsa58pgf5z4a" }\
     }'

Response

{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1beta1",
  "metadata": {
    "name": "cfjsa58pgf5z4a",
    "namespace": "default",
    "generation": 2,
    "creationTimestamp": "2026-04-21T18:58:24Z",
    "annotations": {
      "grafana.app/updatedTimestamp": "2026-04-21T18:58:34Z"
    }
  },
  "spec": {
    "title": "my-renamed-folder",
    "description": ""
  }
}

Delete a Folder

Deletes a folder. The folder must be empty (no dashboards, alerts, or sub-folders) unless the underlying Grafana instance allows forced deletion. Kloudfuse blocks deletion of folders containing Kloudfuse objects (favorite facets, scheduled views, etc.).

curl -H "Authorization: Bearer <sa-token>" \
     -X DELETE \
     "https://<your-instance>/grafana/api/folders/cfjsa58pgf5z4a?forceDeleteRules=false"

Response

{
  "message": "Folder deleted"
}

Get Folder Item Counts

Returns the number of items of each type contained in the folder.

curl -H "Authorization: Bearer <sa-token>" \
  "https://<your-instance>/grafana/api/folders/ffec62bbr7v28d/counts"

Response

{
  "alertrule": 0,
  "dashboard": 18,
  "folder": 0,
  "librarypanel": 0
}

Folder Permissions

Folder permissions control which users, teams, and roles can view, edit, or administer a folder. The caller must have Admin permission on the folder to read or modify its permissions.

Permission levels are:

Get Folder Permissions

Returns all permission assignments for a folder.

curl -H "Authorization: Bearer <sa-token>" \
  "https://<your-instance>/grafana/api/access-control/folders/ffec62bbr7v28d"

Response

[\
  {\
    "id": 887,\
    "roleName": "managed:users:3:permissions",\
    "isManaged": true,\
    "isInherited": false,\
    "isServiceAccount": true,\
    "userId": 3,\
    "userLogin": "sa-1-test",\
    "permission": "Admin"\
  },\
  {\
    "id": 820,\
    "roleName": "basic:admin",\
    "isManaged": false,\
    "isInherited": false,\
    "isServiceAccount": false,\
    "builtInRole": "Admin",\
    "permission": "Admin"\
  },\
  {\
    "id": 44,\
    "roleName": "managed:builtins:editor:permissions",\
    "isManaged": true,\
    "isInherited": false,\
    "isServiceAccount": false,\
    "builtInRole": "Editor",\
    "permission": "Edit"\
  }\
]

Each entry includes:

Update a Built-in Role Permission

Sets the permission for all users with a given built-in role (Admin, Editor, or Viewer).

# Grant Viewer role View access
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST \
     "https://<your-instance>/grafana/api/access-control/folders/ffec62bbr7v28d/builtInRoles/Viewer" \
     -d '{"permission": "View"}'

# Remove Editor role access (set to No Access)
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST \
     "https://<your-instance>/grafana/api/access-control/folders/ffec62bbr7v28d/builtInRoles/Editor" \
     -d '{"permission": ""}'

Response

{
  "message": "Permission updated"
}

Update a Team Permission

Sets the permission for all members of a team. The team ID is the local_grafana_id returned by the List Teams endpoint.

# Grant a team Edit access
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST \
     "https://<your-instance>/grafana/api/access-control/folders/ffec62bbr7v28d/teams/4" \
     -d '{"permission": "Edit"}'

# Remove a team's access (empty string)
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST \
     "https://<your-instance>/grafana/api/access-control/folders/ffec62bbr7v28d/teams/4" \
     -d '{"permission": ""}'

Response when setting a permission

{
  "message": "Permission updated"
}

Response when removing a permission

{
  "message": "Permission removed"
}

Update a User Permission

Sets the permission for a specific user. Use the numeric user ID from Admin > Users.

curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST \
     "https://<your-instance>/grafana/api/access-control/folders/ffec62bbr7v28d/users/12" \
     -d '{"permission": "View"}'

Response

{
  "message": "Permission updated"
}

Error Codes

GraphQL errors are returned with HTTP 200 in an errors array:

{
  "errors": [\
    {\
      "message": "facet group not found",\
      "path": ["removeFacetGroup"]\
    }\
  ]
}