openapi: 3.0.3
info:
title: Grafana HTTP Access Folders API
description: The Grafana HTTP API provides programmatic access to Grafana's core functionality including dashboards, data sources, alerts, users, organizations, folders, annotations, and teams. Authentication is handled via API keys, basic auth, or OAuth tokens passed in the Authorization header.
version: 11.0.0
contact:
name: Grafana Labs
url: https://grafana.com
license:
name: AGPL-3.0
url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: https://{instance}.grafana.net/api
description: Grafana Cloud
variables:
instance:
default: your-instance
- url: http://localhost:3000/api
description: Local Grafana instance
security:
- BearerAuth: []
- BasicAuth: []
- ApiKeyAuth: []
tags:
- name: Folders
description: Dashboard folder management
paths:
/folders:
parameters: []
get:
tags:
- Folders
operationId: getFolders
summary: List all folders
parameters:
- name: limit
in: query
schema:
type: integer
default: 1000
- name: page
in: query
schema:
type: integer
default: 1
responses:
'200':
description: Folders
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Folder'
post:
tags:
- Folders
operationId: createFolder
summary: Create a folder
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFolderCommand'
responses:
'200':
description: Folder created
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
/folders/{uid}:
get:
tags:
- Folders
operationId: getFolderByUid
summary: Get folder by UID
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: Folder
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
put:
tags:
- Folders
operationId: updateFolder
summary: Update folder
parameters:
- name: uid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFolderCommand'
responses:
'200':
description: Folder updated
delete:
tags:
- Folders
operationId: deleteFolder
summary: Delete folder
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: Folder deleted
/folders/id/{folder_id}:
parameters: []
get:
tags:
- Folders
summary: Grafana Get Folder By ID
description: The GET /folders/id/{folder_id} endpoint in Grafana retrieves detailed information about a specific folder using its unique identifier. This operation allows users to fetch folder metadata including its title, UID, permissions, and other configuration details by providing the numeric folder ID in the path parameter. It's particularly useful when you need to access folder information programmatically and have the folder's ID rather than its UID, returning a JSON response with the complete folder object if found or an error if the folder doesn't exist or the user lacks sufficient permissions to view it.
operationId: getFolderByID
parameters:
- name: folder_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/Folder_2'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: true
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/folders/{folder_uid}:
parameters: []
get:
tags:
- Folders
summary: Grafana Get Folder By UID
description: This API operation retrieves detailed information about a specific Grafana folder by providing its unique identifier (UID). By making a GET request to the endpoint with the folder's UID as a path parameter, users can fetch metadata about the folder including its title, UID, ID, URL, version, and other configuration details. This is useful for programmatically accessing folder properties, verifying folder existence, or gathering information needed for subsequent operations such as dashboard management or permission configuration within that specific folder.
operationId: getFolderByUID
parameters:
- name: folder_uid
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/Folder_2'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
put:
tags:
- Folders
summary: Grafana Update Folder
description: Updates an existing folder in Grafana identified by its unique folder UID. This PUT operation allows you to modify folder properties such as the folder's title, and optionally update the folder's version for optimistic concurrency control. The request requires authentication and appropriate permissions to modify the specified folder. Upon successful execution, it returns the updated folder object with its current metadata including the new title, UID, ID, URL, and updated version number. This operation is commonly used when reorganizing dashboards or renaming folder structures within Grafana's dashboard management system.
operationId: updateFolder
parameters:
- name: folder_uid
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: 'To change the unique identifier (uid), provide another one.
To overwrite an existing folder with newer version, set `overwrite` to `true`.
Provide the current version to safelly update the folder: if the provided version differs from the stored one the request will fail, unless `overwrite` is `true`.'
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/UpdateFolderCommand_2'
- description: 'To change the unique identifier (uid), provide another one.
To overwrite an existing folder with newer version, set `overwrite` to `true`.
Provide the current version to safelly update the folder: if the provided version differs from the stored one the request will fail, unless `overwrite` is `true`.'
contentMediaType: application/json
required: true
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/Folder_2'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'409':
description: ConflictError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
delete:
tags:
- Folders
summary: Grafana Delete Folder
description: This API operation deletes a specific folder in Grafana by providing its unique identifier (folder_uid) in the request path. When executed, it permanently removes the folder and potentially all its contents from the Grafana instance, which may include dashboards, alerts, and other resources stored within that folder. The operation requires appropriate permissions to delete folders and returns a confirmation response upon successful deletion, though the exact behavior regarding cascade deletion of folder contents depends on Grafana's configuration and the specific implementation version being used.
operationId: deleteFolder
parameters:
- name: folder_uid
in: path
description: ''
required: true
schema:
type: string
- name: forceDeleteRules
in: query
description: 'If `true` any Grafana 8 Alerts under this folder will be deleted.
Set to `false` so that the request will fail if the folder contains any Grafana 8 Alerts.'
style: form
explode: true
schema:
type: boolean
default: false
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/deleteFolderResponse'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/folders/{folder_uid}/counts:
parameters: []
get:
tags:
- Folders
summary: Grafana Get Folder Descendant Counts
description: Returns statistical information about the descendants of a specified folder in Grafana, identified by its unique folder UID. This endpoint retrieves count data for various types of resources that exist within the folder hierarchy, such as dashboards, alerts, and other nested folders, providing administrators and users with a quick overview of the folder's contents without needing to traverse the entire folder structure manually.
operationId: getFolderDescendantCounts
parameters:
- name: folder_uid
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: object
additionalProperties:
type: integer
format: int64
contentMediaType: application/json
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/folders/{folder_uid}/move:
parameters: []
post:
tags:
- Folders
summary: Grafana Move Folder
description: This API operation moves a Grafana folder identified by its unique identifier (folder_uid) to a new location within the folder hierarchy. It uses a POST request to the /folders/{folder_uid}/move endpoint and allows administrators to reorganize their Grafana folder structure by changing a folder's parent or position. The operation requires the folder_uid path parameter to specify which folder to move, and typically accepts a request body containing the destination folder information or new parent folder identifier. This is useful for maintaining an organized dashboard structure as teams grow and reorganization becomes necessary.
operationId: moveFolder
parameters:
- name: folder_uid
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MoveFolderCommand'
required: true
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/Folder_2'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/folders/{folder_uid}/permissions:
parameters: []
get:
tags:
- Folders
summary: Grafana Get Folder Permission List
description: This API operation retrieves the complete list of permissions associated with a specific folder in Grafana by providing the folder's unique identifier (UID) in the request path. It returns details about which users, teams, or roles have access to the folder and what level of permissions they possess, such as view, edit, or admin rights. This GET endpoint is useful for auditing folder access controls, understanding the current permission structure, and determining who has what level of access to dashboards and resources contained within the specified folder.
operationId: getFolderPermissionList
parameters:
- name: folder_uid
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DashboardACLInfoDTO'
description: ''
contentMediaType: application/json
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: 'ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource. '
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
post:
tags:
- Folders
summary: Grafana Update Folder Permissions
description: This API operation allows you to modify the access permissions for a specific folder in Grafana by making a POST request to the endpoint with the folder's unique identifier (UID). You can use it to grant or revoke permissions for users, teams, or roles, controlling who can view, edit, or administer the folder and its contents. The request body typically includes permission items specifying the permission level (viewer, editor, or admin) and the entity being granted access (user ID, team ID, or role). This is essential for managing collaborative access to dashboards and resources organized within folders, enabling fine-grained access control in multi-user Grafana environments.
operationId: updateFolderPermissions
parameters:
- name: folder_uid
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDashboardACLCommand'
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
components:
schemas:
DashboardACLInfoDTO:
title: DashboardACLInfoDTO
type: object
properties:
created:
type: string
contentEncoding: date-time
dashboardId:
type: integer
contentEncoding: int64
folderId:
type: integer
description: 'Deprecated: use FolderUID instead'
contentEncoding: int64
folderUid:
type: string
inherited:
type: boolean
isFolder:
type: boolean
permission:
type: integer
contentEncoding: int64
permissionName:
type: string
role:
$ref: '#/components/schemas/Role'
slug:
type: string
team:
type: string
teamAvatarUrl:
type: string
teamEmail:
type: string
teamId:
type: integer
contentEncoding: int64
teamUid:
type: string
title:
type: string
uid:
type: string
updated:
type: string
contentEncoding: date-time
url:
type: string
userAvatarUrl:
type: string
userEmail:
type: string
userId:
type: integer
contentEncoding: int64
userLogin:
type: string
userUid:
type: string
UpdateFolderCommand_2:
title: UpdateFolderCommand
type: object
properties:
description:
type: string
description: NewDescription it's an optional parameter used for overriding the existing folder description
overwrite:
type: boolean
description: Overwrite only used by the legacy folder implementation
title:
type: string
description: NewTitle it's an optional parameter used for overriding the existing folder title
version:
type: integer
description: Version only used by the legacy folder implementation
contentEncoding: int64
description: 'UpdateFolderCommand captures the information required by the folder service
to update a folder. Use Move to update a folder''s parent folder.'
Folder:
type: object
properties:
id:
type: integer
uid:
type: string
title:
type: string
url:
type: string
hasAcl:
type: boolean
canSave:
type: boolean
canEdit:
type: boolean
canAdmin:
type: boolean
canDelete:
type: boolean
createdBy:
type: string
created:
type: string
format: date-time
updatedBy:
type: string
updated:
type: string
format: date-time
version:
type: integer
parentUid:
type: string
description: UID of parent folder for nested folders
UpdateFolderCommand:
type: object
required:
- title
properties:
title:
type: string
version:
type: integer
deleteFolderResponse:
title: deleteFolderResponse
required:
- id
- message
- title
type: object
properties:
id:
type: integer
description: ID Identifier of the deleted folder.
contentEncoding: int64
examples:
- 65
message:
type: string
description: Message Message of the deleted folder.
examples:
- Folder My Folder deleted
title:
type: string
description: Title of the deleted folder.
examples:
- My Folder
Role:
title: Role
enum:
- None
- Viewer
- Editor
- Admin
type: string
DashboardACLUpdateItem:
title: DashboardACLUpdateItem
type: object
properties:
permission:
type: integer
contentEncoding: int64
role:
$ref: '#/components/schemas/Role'
teamId:
type: integer
contentEncoding: int64
userId:
type: integer
contentEncoding: int64
MoveFolderCommand:
title: MoveFolderCommand
type: object
properties:
parentUid:
type: string
description: 'MoveFolderCommand captures the information required by the folder service
to move a folder.'
Folder_2:
title: Folder
type: object
properties:
accessControl:
type: object
additionalProperties:
type: boolean
description: 'Metadata contains user accesses for a given resource
Ex: map[string]bool{"create":true, "delete": true}'
canAdmin:
type: boolean
canDelete:
type: boolean
canEdit:
type: boolean
canSave:
type: boolean
created:
type: string
contentEncoding: date-time
createdBy:
type: string
hasAcl:
type: boolean
id:
type: integer
description: 'Deprecated: use UID instead'
contentEncoding: int64
managedBy:
type: string
description: 'It can be a user or a tool or a generic API client.
+enum'
orgId:
type: integer
contentEncoding: int64
parentUid:
type: string
description: only used if nested folders are enabled
parents:
type: array
items:
$ref: '#/components/schemas/Folder_2'
description: the parent folders starting from the root going down
title:
type: string
uid:
type: string
updated:
type: string
contentEncoding: date-time
updatedBy:
type: string
url:
type: string
version:
type: integer
contentEncoding: int64
CreateFolderCommand:
type: object
required:
- title
properties:
uid:
type: string
title:
type: string
parentUid:
type: string
SuccessResponseBody:
title: SuccessResponseBody
type: object
properties:
message:
type: string
ErrorResponseBody:
title: ErrorResponseBody
required:
- message
type: object
properties:
error:
type: string
description: Error An optional detailed description of the actual error. Only included if running in developer mode.
message:
type: string
description: a human readable version of the error
status:
type: string
description: 'Status An optional status to denote the cause of the error.
For example, a 412 Precondition Failed error may include additional information of why that error happened.'
UpdateDashboardACLCommand:
title: UpdateDashboardACLCommand
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/DashboardACLUpdateItem'
description: ''
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Service account token or API key
BasicAuth:
t
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/grafana/refs/heads/main/openapi/grafana-folders-api-openapi.yml