Folder API

    The unique identifier (uid) of a folder can be used for uniquely identify folders between multiple Grafana installs. It’s automatically generated if not provided when creating a folder. The uid allows having consistent URLs for accessing folders and when syncing folders between multiple Grafana installs. This means that changing the title of a folder will not break any bookmarked links to that folder.

    The uid can have a maximum length of 40 characters.

    A note about the General folder

    The General folder (id=0) is special and is not part of the Folder API which means that you cannot use this API for retrieving information about the General folder.

    Returns all folders that the authenticated user has permission to view. You can control the maximum number of folders returned through the limit query parameter, the default is 1000. You can also pass the page query parameter for fetching folders from a page other than the first one.

    Example Request:

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. [
    5.   {
    6.     "id":1,
    7.     "uid": "nErXDvCkzz",
    8.     "title": "Department ABC"
    9.   },
    10.   {
    11.     "id":2,
    12.     "uid": "k3S1cklGk",
    13.     "title": "Department RND"
    14.   }
    15. ]

    Get folder by uid

    GET /api/folders/:uid

    Will return the folder given the folder uid.

    Example Request:

    1. GET /api/folders/nErXDvCkzzh HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.   "id":1,
    6.   "uid": "nErXDvCkzz",
    7.   "title": "Department ABC",
    8.   "url": "/dashboards/f/nErXDvCkzz/department-abc",
    9.   "hasAcl": false,
    10.   "canSave": true,
    11.   "canEdit": true,
    12.   "canAdmin": true,
    13.   "createdBy": "admin",
    15.   "updatedBy": "admin",
    16.   "updated": "2018-01-31T17:43:12+01:00",
    17.   "version": 1
    • 200 – Found
    • 401 – Unauthorized
    • 403 – Access Denied
    • 404 – Folder not found

    POST /api/folders

    Creates a new folder.

    Example Request:

    JSON Body schema:

    • uid – Optional .
    • title – The title of the folder.

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.   "id":1,
    6.   "uid": "nErXDvCkzz",
    7.   "title": "Department ABC",
    8.   "url": "/dashboards/f/nErXDvCkzz/department-abc",
    9.   "hasAcl": false,
    10.   "canSave": true,
    11.   "canEdit": true,
    12.   "canAdmin": true,
    13.   "createdBy": "admin",
    14.   "created": "2018-01-31T17:43:12+01:00",
    15.   "updatedBy": "admin",
    16.   "updated": "2018-01-31T17:43:12+01:00",
    17.   "version": 1
    18. }

    Status Codes:

    • 200 – Created
    • 400 – Errors (invalid json, missing or invalid fields, etc)
    • 401 – Unauthorized
    • 403 – Access Denied
    • 409 - Folder already exists

    Update folder

    PUT /api/folders/:uid

    Updates an existing folder identified by uid.

    Example Request:

    1. PUT /api/folders/nErXDvCkzz HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
    6. {
    7.   "title":"Department DEF",
    8.   "version": 1
    9. }

    JSON Body schema:

    • uid – Provide another than stored to change the unique identifier.
    • title – The title of the folder.
    • version – Provide the current version to be able to update the folder. Not needed if overwrite=true.
    • overwrite – Set to true if you want to overwrite existing folder with newer version.

    Example Response:

    1. HTTP/1.1 200
    3. {
    4.   "id":1,
    5.   "uid": "nErXDvCkzz",
    6.   "title": "Department DEF",
    7.   "url": "/dashboards/f/nErXDvCkzz/department-def",
    8.   "hasAcl": false,
    9.   "canSave": true,
    10.   "canEdit": true,
    11.   "canAdmin": true,
    12.   "createdBy": "admin",
    13.   "created": "2018-01-31T17:43:12+01:00",
    14.   "updatedBy": "admin",
    15.   "updated": "2018-01-31T17:43:12+01:00",
    16.   "version": 1
    17. }
    • 200 – Updated
    • 400 – Errors (invalid json, missing or invalid fields, etc)
    • 401 – Unauthorized
    • 403 – Access Denied
    • 404 – Folder not found
    • 412 – Precondition failed

    The 412 status code is used for explaining that you cannot update the folder and why. There can be different reasons for this:

    • The folder has been changed by someone else, status=version-mismatch

    The response body will have the following properties:

    DELETE /api/folders/:uid

    Deletes an existing folder identified by UID along with all dashboards (and their alerts) stored in the folder. This operation cannot be reverted.

    If are enabled, you can set an optional query parameter forceDeleteRules=false so that requests will fail with 400 (Bad Request) error if the folder contains any Grafana 8 Alerts. However, if this parameter is set to true then it will delete any Grafana 8 Alerts under this folder.

    Example Request:

    1. DELETE /api/folders/nErXDvCkzz HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.   "message":"Folder deleted",
    6.   "id": 2
    7. }

    Status Codes:

    • 200 – Deleted
    • 401 – Unauthorized
    • 400 – Bad Request
    • 403 – Access Denied
    • 404 – Folder not found

    Get folder by id

    GET /api/folders/id/:id

    Will return the folder identified by id.

    Example Request:

    1. GET /api/folders/id/1 HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json

    Status Codes:

    • 200 – Found
    • 401 – Unauthorized
    • 404 – Folder not found