Grafana Folders API

openapi: 3.2.0
info:
  description: 'The Grafana backend exposes an HTTP API, the same API is used by the frontend to do

    everything from saving dashboards, creating users and updating data sources.'
  title: Grafana HTTP API. Folders API
  contact:
    name: Grafana Labs
    url: https://grafana.com
    email: hello@grafana.com
  version: 0.0.1
servers:
- url: /api
security:
- basic: []
- api_key: []
tags:
- description: Folders are identified by the identifier (id) and the unique identifier (uid).
  name: Folders
paths:
  /folders:
    get:
      description: 'It returns all folders that the authenticated user has permission to view.

        If nested folders are enabled, it expects an additional query parameter with the parent folder UID

        and returns the immediate subfolders that the authenticated user has permission to view.

        If the parameter is not supplied then it returns immediate subfolders under the root

        that the authenticated user has permission to view.


        Use: /apis/folder.grafana.app/v1/namespaces/{ns}/folders'
      tags:
      - Folders
      summary: Get all folders
      operationId: getFolders
      deprecated: true
      parameters:
      - description: Limit the maximum number of folders to return
        name: limit
        in: query
        schema:
          type: integer
          format: int64
          default: 1000
      - description: Page index for starting fetching folders
        name: page
        in: query
        schema:
          type: integer
          format: int64
          default: 1
      - description: The parent folder UID
        name: parentUid
        in: query
        schema:
          type: string
      - description: Set to `Edit` to return folders that the user can edit
        name: permission
        in: query
        schema:
          type: string
          enum:
          - Edit
          - View
          default: View
      responses:
        '200':
          $ref: '#/components/responses/getFoldersResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '500':
          $ref: '#/components/responses/internalServerError'
    post:
      description: 'If nested folders are enabled then it additionally expects the parent folder UID.


        Use: /apis/folder.grafana.app/v1/namespaces/{ns}/folders/{folder_uid}'
      tags:
      - Folders
      summary: Create folder
      operationId: createFolder
      deprecated: true
      responses:
        '200':
          $ref: '#/components/responses/folderResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFolderCommand'
        required: true
  /folders/{folder_uid}:
    get:
      description: 'Use: /apis/folder.grafana.app/v1/namespaces/{ns}/folders/{folder_uid}'
      tags:
      - Folders
      summary: Get folder by uid
      operationId: getFolderByUID
      deprecated: true
      parameters:
      - name: folder_uid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/folderResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      description: 'Use: /apis/folder.grafana.app/v1/namespaces/{ns}/folders/{folder_uid}'
      tags:
      - Folders
      summary: Update folder
      operationId: updateFolder
      deprecated: true
      parameters:
      - name: folder_uid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/folderResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '409':
          $ref: '#/components/responses/conflictError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFolderCommand'
        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`.'
        required: true
    delete:
      description: 'Deletes an existing folder identified by UID along with all dashboards (and their alerts) stored in the folder. This operation cannot be reverted.

        If nested folders are enabled then it also deletes all the subfolders.


        Use: /apis/folder.grafana.app/v1/namespaces/{ns}/folders/{folder_uid}'
      tags:
      - Folders
      summary: Delete folder
      operationId: deleteFolder
      deprecated: true
      parameters:
      - name: folder_uid
        in: path
        required: true
        schema:
          type: string
      - 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.'
        name: forceDeleteRules
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          $ref: '#/components/responses/deleteFolderResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
  /folders/{folder_uid}/counts:
    get:
      description: 'Use: /apis/folder.grafana.app/v1/namespaces/{ns}/folders/{folder_uid}'
      tags:
      - Folders
      summary: Gets the count of each descendant of a folder by kind.
      operationId: getFolderDescendantCounts
      deprecated: true
      parameters:
      - name: folder_uid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/getFolderDescendantCountsResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
  /folders/{folder_uid}/move:
    post:
      description: 'Use: /apis/folder.grafana.app/v1/namespaces/{ns}/folders/{folder_uid},

        Changing the parent folder annotation'
      tags:
      - Folders
      summary: Move folder
      operationId: moveFolder
      deprecated: true
      parameters:
      - name: folder_uid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/folderResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveFolderCommand'
        required: true
  /folders/{folder_uid}/permissions:
    get:
      tags:
      - Folders
      summary: Gets all existing permissions for the folder with the given `uid`
      operationId: getFolderPermissionList
      deprecated: true
      parameters:
      - name: folder_uid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/getFolderPermissionListResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
    post:
      tags:
      - Folders
      summary: Updates permissions for a folder.
      operationId: updateFolderPermissions
      parameters:
      - name: folder_uid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/okResponse'
        '401':
          $ref: '#/components/responses/unauthorisedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDashboardACLCommand'
        required: true
components:
  schemas:
    DashboardACLInfoDTO:
      type: object
      properties:
        created:
          type: string
          format: date-time
        dashboardId:
          type: integer
          format: int64
        folderId:
          description: 'Deprecated: use FolderUID instead'
          type: integer
          format: int64
          x-deprecated: true
        folderUid:
          type: string
        inherited:
          type: boolean
        isFolder:
          type: boolean
        permission:
          $ref: '#/components/schemas/DashboardaccessPermissionType'
        permissionName:
          type: string
        role:
          type: string
          enum:
          - None
          - Viewer
          - Editor
          - Admin
        slug:
          type: string
        team:
          type: string
        teamAvatarUrl:
          type: string
        teamEmail:
          type: string
        teamId:
          type: integer
          format: int64
        teamUid:
          type: string
        title:
          type: string
        uid:
          type: string
        updated:
          type: string
          format: date-time
        url:
          type: string
        userAvatarUrl:
          type: string
        userEmail:
          type: string
        userId:
          type: integer
          format: int64
        userLogin:
          type: string
        userUid:
          type: string
    Folder:
      type: object
      properties:
        accessControl:
          $ref: '#/components/schemas/Metadata'
        canAdmin:
          type: boolean
        canDelete:
          type: boolean
        canEdit:
          type: boolean
        canSave:
          type: boolean
        created:
          type: string
          format: date-time
        createdBy:
          type: string
        hasAcl:
          type: boolean
        id:
          description: 'Deprecated: use UID instead'
          type: integer
          format: int64
          x-deprecated: true
        managedBy:
          $ref: '#/components/schemas/ManagerKind'
        orgId:
          type: integer
          format: int64
        parentUid:
          description: only used if nested folders are enabled
          type: string
        parents:
          description: the parent folders starting from the root going down
          type: array
          items:
            $ref: '#/components/schemas/Folder'
        title:
          type: string
        uid:
          type: string
        updated:
          type: string
          format: date-time
        updatedBy:
          type: string
        url:
          type: string
        version:
          type: integer
          format: int64
    ErrorResponseBody:
      type: object
      required:
      - message
      properties:
        error:
          description: Error An optional detailed description of the actual error. Only included if running in developer mode.
          type: string
        message:
          description: a human readable version of the error
          type: string
        status:
          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.'
          type: string
    DashboardACLUpdateItem:
      type: object
      properties:
        permission:
          $ref: '#/components/schemas/DashboardaccessPermissionType'
        role:
          type: string
          enum:
          - None
          - Viewer
          - Editor
          - Admin
        teamId:
          type: integer
          format: int64
        userId:
          type: integer
          format: int64
    FolderSearchHit:
      type: object
      properties:
        id:
          type: integer
          format: int64
        managedBy:
          $ref: '#/components/schemas/ManagerKind'
        parentUid:
          type: string
        title:
          type: string
        uid:
          type: string
    MoveFolderCommand:
      description: 'MoveFolderCommand captures the information required by the folder service

        to move a folder.'
      type: object
      properties:
        parentUid:
          type: string
    DescendantCounts:
      type: object
      additionalProperties:
        type: integer
        format: int64
    UpdateFolderCommand:
      description: 'UpdateFolderCommand captures the information required by the folder service

        to update a folder. Use Move to update a folder''s parent folder.'
      type: object
      properties:
        description:
          description: NewDescription it's an optional parameter used for overriding the existing folder description
          type: string
        overwrite:
          description: Overwrite only used by the legacy folder implementation
          type: boolean
        title:
          description: NewTitle it's an optional parameter used for overriding the existing folder title
          type: string
        version:
          description: Version only used by the legacy folder implementation
          type: integer
          format: int64
    ManagerKind:
      description: It can be a user or a tool or a generic API client.
      type: string
      title: ManagerKind is the type of manager, which is responsible for managing the resource.
    CreateFolderCommand:
      description: 'CreateFolderCommand captures the information required by the folder service

        to create a folder.'
      type: object
      properties:
        description:
          type: string
        parentUid:
          type: string
        title:
          type: string
        uid:
          type: string
    UpdateDashboardACLCommand:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DashboardACLUpdateItem'
    DashboardaccessPermissionType:
      type: integer
      format: int64
    SuccessResponseBody:
      type: object
      properties:
        message:
          type: string
    Metadata:
      description: 'Metadata contains user accesses for a given resource

        Ex: map[string]bool{"create":true, "delete": true}'
      type: object
      additionalProperties:
        type: boolean
  responses:
    unauthorisedError:
      description: UnauthorizedError is returned when the request is not authenticated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    getFolderPermissionListResponse:
      description: (empty)
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/DashboardACLInfoDTO'
    getFolderDescendantCountsResponse:
      description: (empty)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DescendantCounts'
    internalServerError:
      description: InternalServerError is a general error indicating something went wrong internally.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    conflictError:
      description: ConflictError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    deleteFolderResponse:
      description: (empty)
      content:
        application/json:
          schema:
            type: object
            required:
            - id
            - title
            - message
            properties:
              id:
                description: ID Identifier of the deleted folder.
                type: integer
                format: int64
                example: 65
              message:
                description: Message Message of the deleted folder.
                type: string
                example: Folder My Folder deleted
              title:
                description: Title of the deleted folder.
                type: string
                example: My Folder
    badRequestError:
      description: BadRequestError is returned when the request is invalid and it cannot be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    okResponse:
      description: An OKResponse is returned if the request was successful.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessResponseBody'
    forbiddenError:
      description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    getFoldersResponse:
      description: (empty)
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/FolderSearchHit'
    folderResponse:
      description: (empty)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Folder'
    notFoundError:
      description: NotFoundError is returned when the requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
    basic:
      type: http
      scheme: basic