mirror of https://github.com/grafana/grafana
Daniel Lee
8 years ago
commit
cc2f478792
@ -1 +1 @@ |
||||
v4.3 |
||||
v5.0 |
||||
|
||||
@ -0,0 +1,149 @@ |
||||
+++ |
||||
title = "Dashboard Permissions HTTP API " |
||||
description = "Grafana Dashboard Permissions HTTP API" |
||||
keywords = ["grafana", "http", "documentation", "api", "dashboard", "permission", "permissions", "acl"] |
||||
aliases = ["/http_api/dashboardpermissions/"] |
||||
type = "docs" |
||||
[menu.docs] |
||||
name = "Dashboard Permissions" |
||||
parent = "http_api" |
||||
+++ |
||||
|
||||
# Dashboard Permissions API |
||||
|
||||
This API can be used to update/get the permissions for a dashboard. |
||||
|
||||
Permissions with `dashboardId=-1` are the default permissions for users with the Viewer and Editor roles. Permissions can be set for a user, a team or a role (Viewer or Editor). Permissions cannot be set for Admins - they always have access to everything. |
||||
|
||||
The permission levels for the permission field: |
||||
|
||||
- 1 = View |
||||
- 2 = Edit |
||||
- 4 = Admin |
||||
|
||||
## Get permissions for a dashboard |
||||
|
||||
`GET /api/dashboards/id/:dashboardId/permissions` |
||||
|
||||
Gets all existing permissions for the dashboard with the given `dashboardId`. |
||||
|
||||
**Example request**: |
||||
|
||||
```http |
||||
GET /api/dashboards/id/1/permissions HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk |
||||
``` |
||||
|
||||
**Example Response** |
||||
|
||||
```http |
||||
HTTP/1.1 200 OK |
||||
Content-Type: application/json; charset=UTF-8 |
||||
Content-Length: 551 |
||||
|
||||
[ |
||||
{ |
||||
"id": 1, |
||||
"dashboardId": -1, |
||||
"created": "2017-06-20T02:00:00+02:00", |
||||
"updated": "2017-06-20T02:00:00+02:00", |
||||
"userId": 0, |
||||
"userLogin": "", |
||||
"userEmail": "", |
||||
"teamId": 0, |
||||
"team": "", |
||||
"role": "Viewer", |
||||
"permission": 1, |
||||
"permissionName": "View", |
||||
"uid": "", |
||||
"title": "", |
||||
"slug": "", |
||||
"isFolder": false, |
||||
"url": "" |
||||
}, |
||||
{ |
||||
"id": 2, |
||||
"dashboardId": -1, |
||||
"created": "2017-06-20T02:00:00+02:00", |
||||
"updated": "2017-06-20T02:00:00+02:00", |
||||
"userId": 0, |
||||
"userLogin": "", |
||||
"userEmail": "", |
||||
"teamId": 0, |
||||
"team": "", |
||||
"role": "Editor", |
||||
"permission": 2, |
||||
"permissionName": "Edit", |
||||
"uid": "", |
||||
"title": "", |
||||
"slug": "", |
||||
"isFolder": false, |
||||
"url": "" |
||||
} |
||||
] |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **401** - Unauthorized |
||||
- **403** - Access denied |
||||
- **404** - Dashboard not found |
||||
|
||||
## Update permissions for a dashboard |
||||
|
||||
`POST /api/dashboards/id/:dashboardId/permissions` |
||||
|
||||
Updates permissions for a dashboard. This operation will remove existing permissions if they're not included in the request. |
||||
|
||||
**Example request**: |
||||
|
||||
```http |
||||
POST /api/dashboards/id/1/permissions |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk |
||||
|
||||
"items": [ |
||||
{ |
||||
"role": "Viewer", |
||||
"permission": 1 |
||||
}, |
||||
{ |
||||
"role": "Editor", |
||||
"permission": 2 |
||||
}, |
||||
{ |
||||
"teamId": 1, |
||||
"permission": 1 |
||||
}, |
||||
{ |
||||
"userId": 11, |
||||
"permission": 4 |
||||
} |
||||
] |
||||
} |
||||
``` |
||||
|
||||
JSON body schema: |
||||
|
||||
- **items** - The permission items to add/update. Items that are omitted from the list will be removed. |
||||
|
||||
**Example response**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 OK |
||||
Content-Type: application/json; charset=UTF-8 |
||||
Content-Length: 35 |
||||
|
||||
{"message":"Dashboard permissions updated"} |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **401** - Unauthorized |
||||
- **403** - Access denied |
||||
- **404** - Dashboard not found |
||||
@ -0,0 +1,317 @@ |
||||
+++ |
||||
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 |
||||
|
||||
## 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: |
||||
|
||||
- **uid** – Provide another [unique identifier](/http_api/folder/#identifier-id-vs-unique-identifier-uid) 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**: |
||||
|
||||
```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: |
||||
|
||||
- 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 |
||||
@ -0,0 +1,98 @@ |
||||
+++ |
||||
title = "Folder/Dashboard Search HTTP API " |
||||
description = "Grafana Folder/Dashboard Search HTTP API" |
||||
keywords = ["grafana", "http", "documentation", "api", "search", "folder", "dashboard"] |
||||
aliases = ["/http_api/folder_dashboard_search/"] |
||||
type = "docs" |
||||
[menu.docs] |
||||
name = "Folder/dashboard search" |
||||
parent = "http_api" |
||||
+++ |
||||
|
||||
# Folder/Dashboard Search API |
||||
|
||||
## Search folders and dashboards |
||||
|
||||
`GET /api/search/` |
||||
|
||||
Query parameters: |
||||
|
||||
- **query** – Search Query |
||||
- **tag** – List of tags to search for |
||||
- **type** – Type to search for, `dash-folder` or `dash-db` |
||||
- **dashboardIds** – List of dashboard id's to search for |
||||
- **folderIds** – List of folder id's to search in for dashboards |
||||
- **starred** – Flag indicating if only starred Dashboards should be returned |
||||
- **limit** – Limit the number of returned results |
||||
|
||||
**Example request for retrieving folders and dashboards of the general folder**: |
||||
|
||||
```http |
||||
GET /api/search?folderIds=0&query=&starred=false HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk |
||||
``` |
||||
|
||||
**Example response for retrieving folders and dashboards of the general folder**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 |
||||
Content-Type: application/json |
||||
|
||||
[ |
||||
{ |
||||
"id": 163, |
||||
"uid": "000000163", |
||||
"title": "Folder", |
||||
"url": "/dashboards/f/000000163/folder", |
||||
"type": "dash-folder", |
||||
"tags": [], |
||||
"isStarred": false, |
||||
"uri":"db/folder" // deprecated in Grafana v5.0 |
||||
}, |
||||
{ |
||||
"id":1, |
||||
"uid": "cIBgcSjkk", |
||||
"title":"Production Overview", |
||||
"url": "/d/cIBgcSjkk/production-overview", |
||||
"type":"dash-db", |
||||
"tags":[prod], |
||||
"isStarred":true, |
||||
"uri":"db/production-overview" // deprecated in Grafana v5.0 |
||||
} |
||||
] |
||||
``` |
||||
|
||||
**Example request searching for dashboards**: |
||||
|
||||
```http |
||||
GET /api/search?query=Production%20Overview&starred=true&tag=prod HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk |
||||
``` |
||||
|
||||
**Example response searching for dashboards**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 |
||||
Content-Type: application/json |
||||
|
||||
[ |
||||
{ |
||||
"id":1, |
||||
"uid": "cIBgcSjkk", |
||||
"title":"Production Overview", |
||||
"url": "/d/cIBgcSjkk/production-overview", |
||||
"type":"dash-db", |
||||
"tags":[prod], |
||||
"isStarred":true, |
||||
"folderId": 2, |
||||
"folderUid": "000000163", |
||||
"folderTitle": "Folder", |
||||
"folderUrl": "/dashboards/f/000000163/folder", |
||||
"uri":"db/production-overview" // deprecated in Grafana v5.0 |
||||
} |
||||
] |
||||
``` |
||||
@ -0,0 +1,149 @@ |
||||
+++ |
||||
title = "Folder Permissions HTTP API " |
||||
description = "Grafana Folder Permissions HTTP API" |
||||
keywords = ["grafana", "http", "documentation", "api", "folder", "permission", "permissions", "acl"] |
||||
aliases = ["/http_api/dashboardpermissions/"] |
||||
type = "docs" |
||||
[menu.docs] |
||||
name = "Folder Permissions" |
||||
parent = "http_api" |
||||
+++ |
||||
|
||||
# Folder Permissions API |
||||
|
||||
This API can be used to update/get the permissions for a folder. |
||||
|
||||
Permissions with `folderId=-1` are the default permissions for users with the Viewer and Editor roles. Permissions can be set for a user, a team or a role (Viewer or Editor). Permissions cannot be set for Admins - they always have access to everything. |
||||
|
||||
The permission levels for the permission field: |
||||
|
||||
- 1 = View |
||||
- 2 = Edit |
||||
- 4 = Admin |
||||
|
||||
## Get permissions for a folder |
||||
|
||||
`GET /api/folders/:uid/permissions` |
||||
|
||||
Gets all existing permissions for the folder with the given `uid`. |
||||
|
||||
**Example request**: |
||||
|
||||
```http |
||||
GET /api/folders/nErXDvCkzz/permissions HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk |
||||
``` |
||||
|
||||
**Example Response** |
||||
|
||||
```http |
||||
HTTP/1.1 200 OK |
||||
Content-Type: application/json; charset=UTF-8 |
||||
Content-Length: 551 |
||||
|
||||
[ |
||||
{ |
||||
"id": 1, |
||||
"folderId": -1, |
||||
"created": "2017-06-20T02:00:00+02:00", |
||||
"updated": "2017-06-20T02:00:00+02:00", |
||||
"userId": 0, |
||||
"userLogin": "", |
||||
"userEmail": "", |
||||
"teamId": 0, |
||||
"team": "", |
||||
"role": "Viewer", |
||||
"permission": 1, |
||||
"permissionName": "View", |
||||
"uid": "nErXDvCkzz", |
||||
"title": "", |
||||
"slug": "", |
||||
"isFolder": false, |
||||
"url": "" |
||||
}, |
||||
{ |
||||
"id": 2, |
||||
"dashboardId": -1, |
||||
"created": "2017-06-20T02:00:00+02:00", |
||||
"updated": "2017-06-20T02:00:00+02:00", |
||||
"userId": 0, |
||||
"userLogin": "", |
||||
"userEmail": "", |
||||
"teamId": 0, |
||||
"team": "", |
||||
"role": "Editor", |
||||
"permission": 2, |
||||
"permissionName": "Edit", |
||||
"uid": "", |
||||
"title": "", |
||||
"slug": "", |
||||
"isFolder": false, |
||||
"url": "" |
||||
} |
||||
] |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **401** - Unauthorized |
||||
- **403** - Access denied |
||||
- **404** - Folder not found |
||||
|
||||
## Update permissions for a folder |
||||
|
||||
`POST /api/folders/:uid/permissions` |
||||
|
||||
Updates permissions for a folder. This operation will remove existing permissions if they're not included in the request. |
||||
|
||||
**Example request**: |
||||
|
||||
```http |
||||
POST /api/folders/nErXDvCkzz/permissions |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk |
||||
|
||||
"items": [ |
||||
{ |
||||
"role": "Viewer", |
||||
"permission": 1 |
||||
}, |
||||
{ |
||||
"role": "Editor", |
||||
"permission": 2 |
||||
}, |
||||
{ |
||||
"teamId": 1, |
||||
"permission": 1 |
||||
}, |
||||
{ |
||||
"userId": 11, |
||||
"permission": 4 |
||||
} |
||||
] |
||||
} |
||||
``` |
||||
|
||||
JSON body schema: |
||||
|
||||
- **items** - The permission items to add/update. Items that are omitted from the list will be removed. |
||||
|
||||
**Example response**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 OK |
||||
Content-Type: application/json; charset=UTF-8 |
||||
Content-Length: 35 |
||||
|
||||
{"message":"Folder permissions updated"} |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **401** - Unauthorized |
||||
- **403** - Access denied |
||||
- **404** - Dashboard not found |
||||
@ -0,0 +1,316 @@ |
||||
+++ |
||||
title = "Team HTTP API " |
||||
description = "Grafana Team HTTP API" |
||||
keywords = ["grafana", "http", "documentation", "api", "team", "teams", "group"] |
||||
aliases = ["/http_api/team/"] |
||||
type = "docs" |
||||
[menu.docs] |
||||
name = "Teams" |
||||
parent = "http_api" |
||||
+++ |
||||
|
||||
# Team API |
||||
|
||||
This API can be used to create/update/delete Teams and to add/remove users to Teams. All actions require that the user has the Admin role for the organization. |
||||
|
||||
## Team Search With Paging |
||||
|
||||
`GET /api/teams/search?perpage=50&page=1&query=mytea` |
||||
|
||||
or |
||||
|
||||
`GET /api/teams/search?name=myteam` |
||||
|
||||
```http |
||||
GET /api/teams/search?perpage=10&page=1&query=myteam HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Basic YWRtaW46YWRtaW4= |
||||
``` |
||||
|
||||
### Using the query parameter |
||||
|
||||
Default value for the `perpage` parameter is `1000` and for the `page` parameter is `1`. |
||||
|
||||
The `totalCount` field in the response can be used for pagination of the teams list E.g. if `totalCount` is equal to 100 teams and the `perpage` parameter is set to 10 then there are 10 pages of teams. |
||||
|
||||
The `query` parameter is optional and it will return results where the query value is contained in the `name` field. Query values with spaces need to be url encoded e.g. `query=my%20team`. |
||||
|
||||
### Using the name parameter |
||||
|
||||
The `name` parameter returns a single team if the parameter matches the `name` field. |
||||
|
||||
**Example Response**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 |
||||
Content-Type: application/json |
||||
|
||||
"totalCount": 1, |
||||
"teams": [ |
||||
{ |
||||
"id": 1, |
||||
"orgId": 1, |
||||
"name": "MyTestTeam", |
||||
"email": "", |
||||
"avatarUrl": "\/avatar\/3f49c15916554246daa714b9bd0ee398", |
||||
"memberCount": 1 |
||||
} |
||||
], |
||||
"page": 1, |
||||
"perPage": 1000 |
||||
} |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **401** - Unauthorized |
||||
- **403** - Permission denied |
||||
- **404** - Team not found (if searching by name) |
||||
|
||||
## Get Team By Id |
||||
|
||||
`GET /api/teams/:id` |
||||
|
||||
**Example Request**: |
||||
|
||||
```http |
||||
GET /api/teams/1 HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Basic YWRtaW46YWRtaW4= |
||||
``` |
||||
|
||||
**Example Response**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 |
||||
Content-Type: application/json |
||||
|
||||
{ |
||||
"id": 1, |
||||
"orgId": 1, |
||||
"name": "MyTestTeam", |
||||
"email": "", |
||||
"created": "2017-12-15T10:40:45+01:00", |
||||
"updated": "2017-12-15T10:40:45+01:00" |
||||
} |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **401** - Unauthorized |
||||
- **403** - Permission denied |
||||
- **404** - Team not found |
||||
|
||||
## Add Team |
||||
|
||||
The Team `name` needs to be unique. `name` is required and `email` is optional. |
||||
|
||||
`POST /api/teams` |
||||
|
||||
**Example Request**: |
||||
|
||||
```http |
||||
POST /api/teams HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Basic YWRtaW46YWRtaW4= |
||||
|
||||
{ |
||||
"name": "MyTestTeam", |
||||
"email": "email@test.com" |
||||
} |
||||
``` |
||||
|
||||
**Example Response**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 |
||||
Content-Type: application/json |
||||
|
||||
{"message":"Team created","teamId":2} |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **401** - Unauthorized |
||||
- **403** - Permission denied |
||||
- **409** - Team name is taken |
||||
|
||||
## Update Team |
||||
|
||||
There are two fields that can be updated for a team: `name` and `email`. |
||||
|
||||
`PUT /api/teams/:id` |
||||
|
||||
**Example Request**: |
||||
|
||||
```http |
||||
PUT /api/teams/2 HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Basic YWRtaW46YWRtaW4= |
||||
|
||||
{ |
||||
"name": "MyTestTeam", |
||||
"email": "email@test.com" |
||||
} |
||||
``` |
||||
|
||||
**Example Response**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 |
||||
Content-Type: application/json |
||||
|
||||
{"message":"Team updated"} |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **401** - Unauthorized |
||||
- **403** - Permission denied |
||||
- **404** - Team not found |
||||
- **409** - Team name is taken |
||||
|
||||
## Delete Team By Id |
||||
|
||||
`DELETE /api/teams/:id` |
||||
|
||||
**Example Request**: |
||||
|
||||
```http |
||||
DELETE /api/teams/2 HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Basic YWRtaW46YWRtaW4= |
||||
``` |
||||
|
||||
**Example Response**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 |
||||
Content-Type: application/json |
||||
|
||||
{"message":"Team deleted"} |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **401** - Unauthorized |
||||
- **403** - Permission denied |
||||
- **404** - Failed to delete Team. ID not found |
||||
|
||||
## Get Team Members |
||||
|
||||
`GET /api/teams/:teamId/members` |
||||
|
||||
**Example Request**: |
||||
|
||||
```http |
||||
GET /api/teams/1/members HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Basic YWRtaW46YWRtaW4= |
||||
``` |
||||
|
||||
**Example Response**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 |
||||
Content-Type: application/json |
||||
|
||||
[ |
||||
{ |
||||
"orgId": 1, |
||||
"teamId": 1, |
||||
"userId": 3, |
||||
"email": "user1@email.com", |
||||
"login": "user1", |
||||
"avatarUrl": "\/avatar\/1b3c32f6386b0185c40d359cdc733a79" |
||||
}, |
||||
{ |
||||
"orgId": 1, |
||||
"teamId": 1, |
||||
"userId": 2, |
||||
"email": "user2@email.com", |
||||
"login": "user2", |
||||
"avatarUrl": "\/avatar\/cad3c68da76e45d10269e8ef02f8e73e" |
||||
} |
||||
] |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **401** - Unauthorized |
||||
- **403** - Permission denied |
||||
|
||||
## Add Team Member |
||||
|
||||
`POST /api/teams/:teamId/members` |
||||
|
||||
**Example Request**: |
||||
|
||||
```http |
||||
POST /api/teams/1/members HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Basic YWRtaW46YWRtaW4= |
||||
|
||||
{ |
||||
"userId": 2 |
||||
} |
||||
``` |
||||
|
||||
**Example Response**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 |
||||
Content-Type: application/json |
||||
|
||||
{"message":"Member added to Team"} |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **400** - User is already added to this team |
||||
- **401** - Unauthorized |
||||
- **403** - Permission denied |
||||
- **404** - Team not found |
||||
|
||||
## Remove Member From Team |
||||
|
||||
`DELETE /api/teams/:teamId/members/:userId` |
||||
|
||||
**Example Request**: |
||||
|
||||
```http |
||||
DELETE /api/teams/2/members/3 HTTP/1.1 |
||||
Accept: application/json |
||||
Content-Type: application/json |
||||
Authorization: Basic YWRtaW46YWRtaW4= |
||||
``` |
||||
|
||||
**Example Response**: |
||||
|
||||
```http |
||||
HTTP/1.1 200 |
||||
Content-Type: application/json |
||||
|
||||
{"message":"Team Member removed"} |
||||
``` |
||||
|
||||
Status Codes: |
||||
|
||||
- **200** - Ok |
||||
- **401** - Unauthorized |
||||
- **403** - Permission denied |
||||
- **404** - Team not found/Team member not found |
||||
@ -0,0 +1,52 @@ |
||||
+++ |
||||
title = "Dashboard Folders" |
||||
keywords = ["grafana", "dashboard", "dashboard folders", "folder", "folders", "documentation", "guide"] |
||||
type = "docs" |
||||
[menu.docs] |
||||
name = "Folders" |
||||
parent = "dashboard_features" |
||||
weight = 3 |
||||
+++ |
||||
|
||||
# Dashboard Folders |
||||
|
||||
Folders are a way to organize and group dashboards - very useful if you have a lot of dashboards or multiple teams using the same Grafana instance. |
||||
|
||||
## How To Create A Folder |
||||
|
||||
- Create a folder by using the Create Folder link in the side menu (under the create menu (+ icon)) |
||||
- Use the create Folder button on the Manage Dashboards page. |
||||
- When saving a dashboard, you can either choose a folder for the dashboard to be saved in or create a new folder |
||||
|
||||
On the Create Folder page, fill in a unique name for the folder and press Create. |
||||
|
||||
## Manage Dashboards |
||||
|
||||
{{< docs-imagebox img="/img/docs/v50/manage_dashboard_menu.png" max-width="300px" class="docs-image--right" >}} |
||||
|
||||
There is a new Manage Dashboards page where you can carry out a variety of tasks: |
||||
|
||||
- create a folder |
||||
- create a dashboard |
||||
- move dashboards into folders |
||||
- delete multiple dashboards |
||||
- navigate to a folder page (where you can set permissions for a folder and/or its dashboards) |
||||
|
||||
## Dashboard Folder Page |
||||
|
||||
You reach the dashboard folder page by clicking on the cog icon that appears when you hover |
||||
over a folder in the dashboard list in the search result or on the Manage dashboards page. |
||||
|
||||
The Dashboard Folder Page is similar to the Manage Dashboards page and is where you can carry out the following tasks: |
||||
|
||||
- Allows you to move or delete dashboards in a folder. |
||||
- Rename a folder (under the Settings tab). |
||||
- Set permissions for the folder (inherited by dashboards in the folder). |
||||
|
||||
## Permissions |
||||
|
||||
Permissions can assigned to a folder and inherited by the containing dashboards. An Access Control List (ACL) is used where |
||||
**Organization Role**, **Team** and Individual **User** can be assigned permissions. Read the |
||||
[Dashboard & Folder Permissions]({{< relref "administration/permissions.md#dashboard-folder-permissions" >}}) docs for more detail |
||||
on the permission system. |
||||
|
||||
|
Before Width: | Height: | Size: 1.5 KiB After Width: | Height: | Size: 1.0 KiB |
Loading…
Reference in new issue