Grafana Folders API

openapi: 3.2.0
info:
  title: Grafana Folders API
  version: '1.0'
  description: 'Operations tagged Folders across 2 of this provider''s published API definitions: grafana-api.yml, grafana-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{instance}.grafana.net/api
  description: Grafana Cloud
  variables:
    instance:
      default: your-instance
- url: http://localhost:3000/api
  description: Local Grafana instance
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: www.example.com/api
- url: https://{defaultHost}
  variables:
    defaultHost:
      default: www.example.com/api
tags:
- name: Folders
  description: Dashboard folder management
paths:
  /folders:
    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'
      security:
      - BearerAuth: []
      - BasicAuth: []
      - ApiKeyAuth: []
    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'
      security:
      - BearerAuth: []
      - BasicAuth: []
      - ApiKeyAuth: []
    parameters: []
    servers:
    - url: https://{instance}.grafana.net/api
      description: Grafana Cloud
      variables:
        instance:
          default: your-instance
    - url: http://localhost:3000/api
      description: Local Grafana instance
  /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'
      security:
      - BearerAuth: []
      - BasicAuth: []
      - ApiKeyAuth: []
    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
      security:
      - BearerAuth: []
      - BasicAuth: []
      - ApiKeyAuth: []
    delete:
      tags:
      - Folders
      operationId: deleteFolder
      summary: Delete folder
      parameters:
      - name: uid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Folder deleted
      security:
      - BearerAuth: []
      - BasicAuth: []
      - ApiKeyAuth: []
    servers:
    - url: https://{instance}.grafana.net/api
      description: Grafana Cloud
      variables:
        instance:
          default: your-instance
    - url: http://localhost:3000/api
      description: Local Grafana instance
  /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
      security:
      - basic: []
      - api_key: []
    servers:
    - url: http://{defaultHost}
      variables:
        defaultHost:
          default: www.example.com/api
    - url: https://{defaultHost}
      variables:
        defaultHost:
          default: www.example.com/api
  /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
      security:
      - basic: []
      - api_key: []
    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
      security:
      - basic: []
      - api_key: []
    servers:
    - url: http://{defaultHost}
      variables:
        defaultHost:
          default: www.example.com/api
    - url: https://{defaultHost}
      variables:
        defaultHost:
          default: www.example.com/api
  /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
      security:
      - basic: []
      - api_key: []
    servers:
    - url: http://{defaultHost}
      variables:
        defaultHost:
          default: www.example.com/api
    - url: https://{defaultHost}
      variables:
        defaultHost:
          default: www.example.com/api
  /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
      security:
      - basic: []
      - api_key: []
    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
      security:
      - basic: []
      - api_key: []
    servers:
    - url: http://{defaultHost}
      variables:
        defaultHost:
          default: www.example.com/api
    - url: https://{defaultHost}
      variables:
        defaultHost:
          default: www.example.com/api
components:
  schemas:
    UpdateFolderCommand:
      type: object
      required:
      - title
      properties:
        title:
          type: string
        version:
          type: integer
    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
    CreateFolderCommand:
      type: object
      required:
      - title
      properties:
        uid:
          type: string
        title:
          type: string
        parentUid:
          type: string
    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
    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
    UpdateDashboardACLCommand:
      title: UpdateDashboardACLCommand
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DashboardACLUpdateItem'
          description: ''
    MoveFolderCommand:
      title: MoveFolderCommand
      type: object
      properties:
        parentUid:
          type: string
      description: 'MoveFolderCommand captures the information required by the folder service

        to move a folder.'
    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.'
    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.'
    FolderSearchHit:
      title: FolderSearchHit
      type: object
      properties:
        id:
          type: integer
          contentEncoding: int64
        managedBy:
          type: string
          description: 'It can be a user or a tool or a generic API client.

            +enum'
        parentUid:
          type: string
        title:
          type: string
        uid:
          type: string
    permission1:
      title: permission1
      enum:
      - Edit
      - View
      type: string
    SuccessResponseBody:
      title: SuccessResponseBody
      type: object
      properties:
        message:
          type: string
    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
  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 <api-key>'
    api_key:
      type: apiKey
      name: Authorization
      in: header
    basic:
      type: http
      scheme: basic
x-refined-from:
- grafana-api.yml
- grafana-openapi.yml