菜单

文件夹 HTTP API

企业版开源

新的文件夹 API

如果您正在运行 Grafana Enterprise，对于某些端点，您需要拥有特定权限。请参阅基于角色的访问控制权限获取更多信息。

要了解更多关于新的 API 结构的信息，请参阅API 概述。

获取所有文件夹

GET /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders

返回经过认证的用户在给定组织中拥有查看权限的所有文件夹。使用 limit 查询参数来控制返回的仪表盘最大数量。要检索更多仪表盘，请利用响应中提供的 continue 令牌来获取下一页数据。

namespace: 要了解更多关于使用的 namespace，请参阅API 概述。

所需权限

请参阅简介中的注释获取解释。

操作	作用域
`folders:read`	`folders:*`

请求示例:

GET /apis/folder.grafana.app/v1beta1/namespaces/default/folders?limit=1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "FolderList",
  "apiVersion": "folder.grafana.app/v1beta1",
  "metadata": {
    "continue": "org:1/start:1158/folder:"
  },
  "items": [
    {
      "kind": "Folder",
      "apiVersion": "folder.grafana.app/v1beta1",
      "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"
      }
    }
  ]
}

状态码

200 – 成功
401 – 未授权
403 – 访问被拒绝

按 uid 获取文件夹

GET /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders/:uid

根据文件夹 uid 返回文件夹。

namespace: 要了解更多关于使用的 namespace，请参阅API 概述。
uid: 要更新的文件夹的唯一标识符。这将是文件夹响应中的名称

所需权限

请参阅简介中的注释获取解释。

操作	作用域
`folders:read`	`folders:*`

请求示例:

GET /apis/folder.grafana.app/v1beta1/namespaces/default/folders/aef30vrzxs3y8d HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1beta1",
  "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"
  }
}

请注意标注 grafana.app/folder，它包含父文件夹的 uid。

状态码

200 – 找到
401 – 未授权
403 – 访问被拒绝
404 – 文件夹未找到

创建文件夹

POST /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders

创建一个新文件夹。

namespace: 要了解更多关于使用的 namespace，请参阅API 概述。

所需权限

请参阅简介中的注释获取解释。

folders:create 允许创建文件夹和子文件夹。如果授权范围为 folders:uid:general，则允许创建根目录下的文件夹。否则，只允许在指定文件夹下创建子文件夹。

操作	作用域
`folders:create`	`folders:*`
`folders:write`	`folders:*`

请求示例:

POST /apis/folder.grafana.app/v1beta1/namespaces/default/folders HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "metadata": {
    "name": "aef30vrzxs3y8d",
    "annotations": {
      "grafana.app/folder": "fef30w4jaxla8b"
    }
  }
  "spec": {
    "title": "child-folder"
  },
}

JSON 请求体 schema

metadata.name – Grafana 唯一标识符。如果您不想提供此项，可以将 metadata.generateName 设置为您希望用于 uid 的前缀。
metadata.annotations.grafana.app/folder - 可选字段，父文件夹的唯一标识符，新文件夹将在此父文件夹下创建。需要启用嵌套文件夹功能。
spec.title – 文件夹的标题。

响应示例:

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1beta1",
  "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"
  }
}

状态码

201 – 已创建
400 – 错误（JSON 无效、字段缺失或无效等）
401 – 未授权
403 – 访问被拒绝
409 – 冲突（同名 uid 的文件夹已存在）

更新文件夹

PUT /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders/:uid

更新由 uid 标识的现有文件夹。

namespace: 要了解更多关于使用的 namespace，请参阅API 概述。
uid: 要更新的文件夹的唯一标识符。这将是文件夹响应中的名称

所需权限

请参阅简介中的注释获取解释。

操作	作用域
`folders:write`	`folders:*`

请求示例:

PUT /apis/folder.grafana.app/v1beta1/namespaces/default/folders/fef30w4jaxla8b HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

"metadata": {
    "name": "aef30vrzxs3y8d",
    "annotations": {
      "grafana.app/folder": "xkj92m5pqw3vn4"
    }
  }
  "spec": {
    "title": "updated title"
  },

JSON 请求体 schema

metadata.name – 文件夹的唯一标识符。
metadata.annotations.grafana.app/folder - 可选字段，父文件夹的唯一标识符。更新此字段可将文件夹移动到不同的父文件夹下。需要启用嵌套文件夹功能。
spec.title – 文件夹的标题。

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1beta1",
  "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"
  }
}

状态码

200 – 已更新
400 – 错误（JSON 无效、字段缺失或无效等）
401 – 未授权
403 – 访问被拒绝
404 – 文件夹未找到
412 – 前置条件失败（文件夹已被其他人修改）。在此状态码下，响应体将包含以下属性

HTTP/1.1 412 Precondition Failed
Content-Type: application/json; charset=UTF-8
Content-Length: 97

{
  "message": "The folder has been changed by someone else",
  "status": "version-mismatch"
}

删除文件夹

DELETE /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders/:uid

删除由 UID 标识的现有文件夹及其包含的所有仪表盘（和告警）。此操作无法撤销。如果Grafana 告警已启用，您可以设置一个可选的查询参数 forceDeleteRules=false，这样如果文件夹包含任何 Grafana 告警，请求将返回 400（错误请求）错误。但是，如果此参数设置为 true，则将删除此文件夹下的所有 Grafana 告警。

uid: 要删除的文件夹的唯一标识符。这将是文件夹响应中的名称

namespace: 要了解更多关于使用的 namespace，请参阅API 概述。
folders:delete

所需权限

请参阅简介中的注释获取解释。

操作	作用域
`200 – 已删除`	`folders:*`

请求示例:

DELETE /apis/folder.grafana.app/v1beta1/namespaces/default/folders/fef30w4jaxla8b HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1beta1",
  "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"
  }
}

状态码

400 – 错误请求
401 – 未授权
API
403 – 访问被拒绝
404 – 文件夹未找到

标识符 (id) 与唯一标识符 (uid)

文件夹的唯一标识符 (uid) 可用于在组织中唯一标识文件夹。如果在创建文件夹时未提供，则会自动生成。uid 允许使用一致的 URL 访问文件夹，并在多个 Grafana 安装之间同步文件夹。这意味着更改文件夹的标题不会影响指向该文件夹的任何书签链接。

uid 最大长度为 40 个字符。

文件夹标识符 (id) 已弃用，推荐使用唯一标识符 (uid)。

GET /api/folders

获取所有文件夹

返回经认证的用户拥有查看权限的所有文件夹。您可以通过 limit 查询参数控制返回的文件夹最大数量，默认为 1000。您也可以传递 page 查询参数来获取非第一页的文件夹数据。

如果启用了嵌套文件夹，该操作需要一个额外的可选查询参数 parentUid（包含父文件夹 UID），并返回经认证用户拥有查看权限的直接子文件夹。如果未提供此参数，则该操作返回经认证用户拥有查看权限的根目录下的直接子文件夹。

GET /api/folders/:uid

所需权限

请参阅简介中的注释获取解释。

操作	作用域
`folders:read`	`folders:*`

请求示例:

GET /api/folders?limit=10 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id":1,
    "uid": "nErXDvCkzz",
    "title": "Department ABC"
  },
  {
    "id":2,
    "uid": "k3S1cklGk",
    "title": "Department RND"
  }
]

按 uid 获取文件夹

如果启用了嵌套文件夹，并且文件夹是嵌套的（位于另一个文件夹下），则响应中还会包含

根据文件夹 uid 返回文件夹。

所需权限

请参阅简介中的注释获取解释。

操作	作用域
`folders:read`	`folders:*`

请求示例:

GET /api/folders/nErXDvCkzzh HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "url": "/dashboards/f/nErXDvCkzz/department-abc",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}

parentUid - 父文件夹的 UID。

parents - 一个包含整个树状结构的数组，从根节点开始向下直到父文件夹。
POST /api/folders

状态码

200 – 找到
401 – 未授权
403 – 访问被拒绝
404 – 文件夹未找到

创建文件夹

uid – 可选的唯一标识符。

创建一个新文件夹。

所需权限

请参阅简介中的注释获取解释。

操作	作用域
`folders:create`	`folders:*`
`folders:write`	`folders:*`

请求示例:

POST /api/folders HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "parentUid": "fgnj5e52gel76g"
}

JSON 请求体 schema

title – 文件夹的标题。
parentUid - 可选字段，父文件夹的唯一标识符，新文件夹将在此父文件夹下创建。需要启用嵌套文件夹功能。
如果启用了嵌套文件夹，并且文件夹是嵌套的（位于另一个文件夹下），则响应中还会包含

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department ABC",
  "url": "/dashboards/f/nErXDvCkzz/department-abc",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}

parentUid - 父文件夹的 UID。

parents - 一个包含整个树状结构的数组，从根节点开始向下直到父文件夹。
200 – 已创建

状态码

412 - 文件夹已存在
400 – 错误（JSON 无效、字段缺失或无效等）
401 – 未授权
403 – 访问被拒绝
PUT /api/folders/:uid

更新文件夹

version – 提供当前版本以更新文件夹。如果 overwrite=true 则不需要。

更新由 uid 标识的现有文件夹。

所需权限

请参阅简介中的注释获取解释。

操作	作用域
`folders:write`	`folders:*`

请求示例:

PUT /api/folders/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "title":"Department DEF",
  "version": 1
}

JSON 请求体 schema

parentUid - 可选字段，父文件夹的唯一标识符，新文件夹将在此父文件夹下创建。需要启用嵌套文件夹功能。
overwrite – 如果要用较新的版本覆盖现有文件夹，请设置为 true。
412 – 前置条件失败

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1,
  "uid": "nErXDvCkzz",
  "title": "Department DEF",
  "url": "/dashboards/f/nErXDvCkzz/department-def",
  "hasAcl": false,
  "canSave": true,
  "canEdit": true,
  "canAdmin": true,
  "createdBy": "admin",
  "created": "2018-01-31T17:43:12+01:00",
  "updatedBy": "admin",
  "updated": "2018-01-31T17:43:12+01:00",
  "version": 1
}

parentUid - 父文件夹的 UID。

parents - 一个包含整个树状结构的数组，从根节点开始向下直到父文件夹。
200 – 已创建

状态码

200 – 已更新
400 – 错误（JSON 无效、字段缺失或无效等）
401 – 未授权
403 – 访问被拒绝
404 – 文件夹未找到
412 状态码用于解释为什么无法更新文件夹及其原因。可能有不同的原因：

文件夹已被其他人修改，status=version-mismatch

响应体将包含以下属性

DELETE /api/folders/:uid

HTTP/1.1 412 Precondition Failed
Content-Type: application/json; charset=UTF-8
Content-Length: 97

{
  "message": "The folder has been changed by someone else",
  "status": "version-mismatch"
}

删除文件夹

移动文件夹

uid: 要删除的文件夹的唯一标识符。这将是文件夹响应中的名称

所需权限

请参阅简介中的注释获取解释。

操作	作用域
`200 – 已删除`	`folders:*`

请求示例:

DELETE /api/folders/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
  "message":"Folder deleted",
  "id": 2
}

状态码

400 – 错误请求
401 – 未授权
API
403 – 访问被拒绝
404 – 文件夹未找到

POST /api/folders/:uid/move

移动文件夹。

这仅在启用嵌套文件夹时相关。

如果将文件夹移动到另一个文件夹下

所需权限

请参阅简介中的注释获取解释。

folders:uid:<目标文件夹 UID>

操作	作用域
`folders:create`	`如果将文件夹移动到根目录` `folders:*`

folders:uid:general

操作	作用域
`folders:create`	`JSON 请求体 schema` `folders:*`

parentUid – 可选的唯一标识符的新父文件夹。如果此字段为空，则文件夹移动到根目录下。

200 – 已移动

请求示例:

POST /api/folders/a5393ec3-5568-4e88-8809-b866968ae8a6/move HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "parentUid": "d80b18c0-266a-4aa4-ad5d-5537a00cb8e8",
}

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
	"id": 4,
	"uid": "a5393ec3-5568-4e88-8809-b866968ae8a6",
	"title": "just-testing",
	"url": "/dashboards/f/a5393ec3-5568-4e88-8809-b866968ae8a6/just-testing",
	"hasAcl": false,
	"canSave": true,
	"canEdit": true,
	"canAdmin": true,
	"canDelete": true,
	"createdBy": "Anonymous",
	"created": "2023-04-27T21:55:01.593741+03:00",
	"updatedBy": "Anonymous",
	"updated": "2023-04-27T21:55:15.747444+03:00",
	"parentUid": "d80b18c0-266a-4aa4-ad5d-5537a00cb8e8",
	"parents": [
		{
			"id": 2,
			"uid": "d80b18c0-266a-4aa4-ad5d-5537a00cb8e8",
			"title": "f0",
			"url": "",
			"hasAcl": false,
			"canSave": true,
			"canEdit": true,
			"canAdmin": true,
			"canDelete": true,
			"createdBy": "Anonymous",
			"created": "2023-04-27T21:53:46.070672+03:00",
			"updatedBy": "Anonymous",
			"updated": "2023-04-27T21:53:46.070673+03:00"
		}
	]
}

状态码