|
|
@@ -0,0 +1,337 @@
|
|
|
++++
|
|
|
+title = "Folder HTTP API "
|
|
|
+description = "Grafana Folder HTTP API"
|
|
|
+keywords = ["grafana", "http", "documentation", "api", "folder"]
|
|
|
+aliases = ["/http_api/folder/"]
|
|
|
+type = "docs"
|
|
|
+[menu.docs]
|
|
|
+name = "Folder"
|
|
|
+parent = "http_api"
|
|
|
++++
|
|
|
+
|
|
|
+# 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.
|
|
|
+
|
|
|
+
|
|
|
+## Get all folders
|
|
|
+
|
|
|
+`GET /api/folders`
|
|
|
+
|
|
|
+Returns all folders that the authenticated user has permission to view.
|
|
|
+
|
|
|
+**Example Request**:
|
|
|
+
|
|
|
+```http
|
|
|
+GET /api/folders?limit=10 HTTP/1.1
|
|
|
+Accept: application/json
|
|
|
+Content-Type: application/json
|
|
|
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
|
+```
|
|
|
+
|
|
|
+**Example Response**:
|
|
|
+
|
|
|
+```http
|
|
|
+HTTP/1.1 200
|
|
|
+Content-Type: application/json
|
|
|
+
|
|
|
+[
|
|
|
+ {
|
|
|
+ "id":1,
|
|
|
+ "uid": "nErXDvCkzz",
|
|
|
+ "title": "Departmenet ABC",
|
|
|
+ "url": "/dashboards/f/nErXDvCkzz/department-abc",
|
|
|
+ "hasAcl": false,
|
|
|
+ "canSave": true,
|
|
|
+ "canEdit": true,
|
|
|
+ "canAdmin": true,
|
|
|
+ "createdBy": "admin",
|
|
|
+ "created": "2018-01-31T17:43:12+01:00",
|
|
|
+ "updatedBy": "admin",
|
|
|
+ "updated": "2018-01-31T17:43:12+01:00",
|
|
|
+ "version": 1
|
|
|
+ }
|
|
|
+]
|
|
|
+```
|
|
|
+
|
|
|
+## Get folder by uid
|
|
|
+
|
|
|
+`GET /api/folders/:uid`
|
|
|
+
|
|
|
+Will return the folder given the folder uid.
|
|
|
+
|
|
|
+**Example Request**:
|
|
|
+
|
|
|
+```http
|
|
|
+GET /api/folders/nErXDvCkzzh HTTP/1.1
|
|
|
+Accept: application/json
|
|
|
+Content-Type: application/json
|
|
|
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
|
+```
|
|
|
+
|
|
|
+**Example Response**:
|
|
|
+
|
|
|
+```http
|
|
|
+HTTP/1.1 200
|
|
|
+Content-Type: application/json
|
|
|
+
|
|
|
+{
|
|
|
+ "id":1,
|
|
|
+ "uid": "nErXDvCkzz",
|
|
|
+ "title": "Departmenet ABC",
|
|
|
+ "url": "/dashboards/f/nErXDvCkzz/department-abc",
|
|
|
+ "hasAcl": false,
|
|
|
+ "canSave": true,
|
|
|
+ "canEdit": true,
|
|
|
+ "canAdmin": true,
|
|
|
+ "createdBy": "admin",
|
|
|
+ "created": "2018-01-31T17:43:12+01:00",
|
|
|
+ "updatedBy": "admin",
|
|
|
+ "updated": "2018-01-31T17:43:12+01:00",
|
|
|
+ "version": 1
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+Status Codes:
|
|
|
+
|
|
|
+- **200** – Found
|
|
|
+- **401** – Unauthorized
|
|
|
+- **403** – Access Denied
|
|
|
+- **404** – Folder not found
|
|
|
+
|
|
|
+## Create folder
|
|
|
+
|
|
|
+`POST /api/folders`
|
|
|
+
|
|
|
+Creates a new folder.
|
|
|
+
|
|
|
+**Example Request**:
|
|
|
+
|
|
|
+```http
|
|
|
+POST /api/folders HTTP/1.1
|
|
|
+Accept: application/json
|
|
|
+Content-Type: application/json
|
|
|
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
|
+
|
|
|
+{
|
|
|
+ "uid": "nErXDvCkzz",
|
|
|
+ "title": "Department ABC"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+JSON Body schema:
|
|
|
+
|
|
|
+- **uid** – Optional [unique identifier](/http_api/folder/#identifier-id-vs-unique-identifier-uid).
|
|
|
+- **title** – The title of the folder.
|
|
|
+
|
|
|
+**Example Response**:
|
|
|
+
|
|
|
+```http
|
|
|
+HTTP/1.1 200
|
|
|
+Content-Type: application/json
|
|
|
+
|
|
|
+{
|
|
|
+ "id":1,
|
|
|
+ "uid": "nErXDvCkzz",
|
|
|
+ "title": "Departmenet ABC",
|
|
|
+ "url": "/dashboards/f/nErXDvCkzz/department-abc",
|
|
|
+ "hasAcl": false,
|
|
|
+ "canSave": true,
|
|
|
+ "canEdit": true,
|
|
|
+ "canAdmin": true,
|
|
|
+ "createdBy": "admin",
|
|
|
+ "created": "2018-01-31T17:43:12+01:00",
|
|
|
+ "updatedBy": "admin",
|
|
|
+ "updated": "2018-01-31T17:43:12+01:00",
|
|
|
+ "version": 1
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+Status Codes:
|
|
|
+
|
|
|
+- **200** – Created
|
|
|
+- **400** – Errors (invalid json, missing or invalid fields, etc)
|
|
|
+- **401** – Unauthorized
|
|
|
+- **403** – Access Denied
|
|
|
+- **412** – Precondition failed
|
|
|
+
|
|
|
+The **412** status code is used for explaing that you cannot create the folder and why.
|
|
|
+There can be different reasons for this:
|
|
|
+
|
|
|
+- A folder or dashboard in the general folder with the same name already exists, `status=name-exists`
|
|
|
+- A folder/dashboard with the same uid already exists, `status=uid-exists`
|
|
|
+
|
|
|
+ The response body will have the following properties:
|
|
|
+
|
|
|
+```http
|
|
|
+HTTP/1.1 412 Precondition Failed
|
|
|
+Content-Type: application/json; charset=UTF-8
|
|
|
+Content-Length: 97
|
|
|
+
|
|
|
+{
|
|
|
+ "message": "A folder or dashboard in the general folder with the same name already exists",
|
|
|
+ "status": "name-exists"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## Update folder
|
|
|
+
|
|
|
+`PUT /api/folders/:uid`
|
|
|
+
|
|
|
+Updates an existing folder identified by uid.
|
|
|
+
|
|
|
+**Example Request**:
|
|
|
+
|
|
|
+```http
|
|
|
+PUT /api/folders/nErXDvCkzz HTTP/1.1
|
|
|
+Accept: application/json
|
|
|
+Content-Type: application/json
|
|
|
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
|
+
|
|
|
+{
|
|
|
+ "title":"Department DEF",
|
|
|
+ "version": 1
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+JSON Body schema:
|
|
|
+
|
|
|
+- **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**:
|
|
|
+
|
|
|
+```http
|
|
|
+HTTP/1.1 200
|
|
|
+Content-Type: application/json
|
|
|
+
|
|
|
+{
|
|
|
+ "id":1,
|
|
|
+ "uid": "nErXDvCkzz",
|
|
|
+ "title": "Departmenet DEF",
|
|
|
+ "url": "/dashboards/f/nErXDvCkzz/department-def",
|
|
|
+ "hasAcl": false,
|
|
|
+ "canSave": true,
|
|
|
+ "canEdit": true,
|
|
|
+ "canAdmin": true,
|
|
|
+ "createdBy": "admin",
|
|
|
+ "created": "2018-01-31T17:43:12+01:00",
|
|
|
+ "updatedBy": "admin",
|
|
|
+ "updated": "2018-01-31T17:43:12+01:00",
|
|
|
+ "version": 1
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+Status Codes:
|
|
|
+
|
|
|
+- **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 explaing that you cannot update the folder and why.
|
|
|
+There can be different reasons for this:
|
|
|
+
|
|
|
+- A folder or dashboard in the general folder with the same name already exists, `status=name-exists`
|
|
|
+- The folder has been changed by someone else, `status=version-mismatch`
|
|
|
+
|
|
|
+ The response body will have the following properties:
|
|
|
+
|
|
|
+```http
|
|
|
+HTTP/1.1 412 Precondition Failed
|
|
|
+Content-Type: application/json; charset=UTF-8
|
|
|
+Content-Length: 97
|
|
|
+
|
|
|
+{
|
|
|
+ "message": "The folder has been changed by someone else",
|
|
|
+ "status": "version-mismatch"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## 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**:
|
|
|
+
|
|
|
+```http
|
|
|
+DELETE /api/folders/nErXDvCkzz HTTP/1.1
|
|
|
+Accept: application/json
|
|
|
+Content-Type: application/json
|
|
|
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
|
+
|
|
|
+```
|
|
|
+
|
|
|
+**Example Response**:
|
|
|
+
|
|
|
+```http
|
|
|
+HTTP/1.1 200
|
|
|
+Content-Type: application/json
|
|
|
+
|
|
|
+{
|
|
|
+ "message":"Folder deleted"
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+Status Codes:
|
|
|
+
|
|
|
+- **200** – Deleted
|
|
|
+- **401** – Unauthorized
|
|
|
+- **403** – Access Denied
|
|
|
+- **404** – Folder not found
|
|
|
+
|
|
|
+## Get folder by id
|
|
|
+
|
|
|
+`GET /api/folders/:id`
|
|
|
+
|
|
|
+Will return the folder identified by id.
|
|
|
+
|
|
|
+**Example Request**:
|
|
|
+
|
|
|
+```http
|
|
|
+GET /api/folders/1 HTTP/1.1
|
|
|
+Accept: application/json
|
|
|
+Content-Type: application/json
|
|
|
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
|
+```
|
|
|
+
|
|
|
+**Example Response**:
|
|
|
+
|
|
|
+```http
|
|
|
+HTTP/1.1 200
|
|
|
+Content-Type: application/json
|
|
|
+
|
|
|
+{
|
|
|
+ "id":1,
|
|
|
+ "uid": "nErXDvCkzz",
|
|
|
+ "title": "Departmenet ABC",
|
|
|
+ "url": "/dashboards/f/nErXDvCkzz/department-abc",
|
|
|
+ "hasAcl": false,
|
|
|
+ "canSave": true,
|
|
|
+ "canEdit": true,
|
|
|
+ "canAdmin": true,
|
|
|
+ "createdBy": "admin",
|
|
|
+ "created": "2018-01-31T17:43:12+01:00",
|
|
|
+ "updatedBy": "admin",
|
|
|
+ "updated": "2018-01-31T17:43:12+01:00",
|
|
|
+ "version": 1
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+Status Codes:
|
|
|
+
|
|
|
+- **200** – Found
|
|
|
+- **401** – Unauthorized
|
|
|
+- **403** – Access Denied
|
|
|
+- **404** – Folder not found
|
Marcus Efraimsson