Folder API

Identifier (id) vs unique identifier (uid)

The identifier (id) of a folder is an auto-incrementing numeric value and is only unique per Grafana install.

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.

Get all folders

GET /api/folders

Returns all folders that the authenticated user has permission to view.

Example Request:

  1. GET /api/folders?limit=10 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.   {
  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

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 – Found
  • 401 – Unauthorized
  • 403 – Access Denied
  • 404 – Folder not found

Create folder

POST /api/folders

Creates a new folder.

Example Request:

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

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

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. HTTP/1.1 200
  2. Content-Type: application/json
  4. {
  5.   "id":1,
  6.   "uid": "nErXDvCkzz",
  7.   "title": "Departmenet DEF",
  8.   "url": "/dashboards/f/nErXDvCkzz/department-def",
  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 – 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:

  1. HTTP/1.1 412 Precondition Failed
  2. Content-Type: application/json; charset=UTF-8
  3. Content-Length: 97
  5. {
  6.   "message": "The folder has been changed by someone else",
  7.   "status": "version-mismatch"
  8. }

Delete folder

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
  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": "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 – Found
  • 401 – Unauthorized
  • 403 – Access Denied
  • 404 – Folder not found