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 URL’s 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.

    Example Request:

    Example Response:

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

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

    Status Codes:

    • 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 unique identifier.
    • 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": "Departmenet 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

    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

    JSON Body schema:

    • uid – Provide another unique identifier 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. Content-Type: application/json
    3. {
    4.   "id":1,
    5.   "uid": "nErXDvCkzz",
    6.   "title": "Departmenet 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 failedThe 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-mismatchThe response body will have the following properties:

    DELETE /api/folders/:uid

    Deletes an existing folder identified by uid together with all dashboards stored in the folder, if any. This operation cannot be reverted.

    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. }

    Status Codes:

    • 200 – Deleted
    • 401 – Unauthorized
    • 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
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

    Status Codes:

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