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: type: http scheme: basic ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Format: Bearer '