opensource/grafana
1
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-07-29 14:12:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'docs_v5.0'

Browse Source
This commit is contained in:
Daniel Lee
2018-03-01 09:36:48 +01:00
parent f46f43dc32 01fb3ea034
commit cc2f478792
30 changed files with 1382 additions and 367 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
docs/sources/http_api/dashboard.md
View File

@ -11,6 +11,17 @@ parent = "http_api"
# Dashboard API
## Identifier (id) vs unique identifier (uid)
The identifier (id) of a dashboard is an auto-incrementing numeric value and is only unique per Grafana install.
The unique identifier (uid) of a dashboard can be used for uniquely identify a dashboard between multiple Grafana installs.
It's automatically generated if not provided when creating a dashboard. The uid allows having consistent URL's for accessing
dashboards and when syncing dashboards between multiple Grafana installs, see [dashboard provisioning](/administration/provisioning/#dashboards)
for more information. This means that changing the title of a dashboard will not break any bookmarked links to that dashboard.
The uid can have a maximum length of 40 characters.
## Create / Update dashboard
`POST /api/dashboards/db`
@ -28,6 +39,7 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
JSON Body schema:
- **dashboard** – The complete dashboard model, id = null to create a new dashboard.
- **dashboard.id** – id = null to create a new dashboard.
- **dashboard.uid** – Optional [unique identifier](/http_api/dashboard/#identifier-id-vs-unique-identifier-uid) when creating a dashboard. uid = null will generate a new uid.
@ -38,14 +50,18 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
**Example Response**:
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 78
```
Status Codes:
- **200** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **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 dashboard and why.
@ -56,9 +72,12 @@ Content-Type: application/json; charset=UTF-8
- A dashboard with the same uid already exists, `status=name-exists`
- The dashboard belongs to plugin `<plugin title>`, `status=plugin-dashboard`
```
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
```
@ -67,10 +86,18 @@ Status Codes:
## Get dashboard by uid
`GET /api/dashboards/uid/:uid`
Will return the dashboard given the dashboard unique identifier (uid).
```http
GET /api/dashboards/db/production-overview HTTP/1.1
**Example Request**:
```http
GET /api/dashboards/uid/cIBgcSjkk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
@ -85,16 +112,16 @@ Content-Length: 97
- **401** – Unauthorized
- **403** – Access denied
- **404** – Not found
## Delete dashboard by uid
`DELETE /api/dashboards/uid/:uid`
Will delete the dashboard given the specified unique identifier (uid).
**Example Request**:
Accept: application/json
```http
DELETE /api/dashboards/uid/cIBgcSjkk HTTP/1.1
Accept: application/json
Content-Type: application/json
@ -107,12 +134,9 @@ HTTP/1.1 200
HTTP/1.1 200
Content-Type: application/json
## Gets the home dashboard
`GET /api/dashboards/home`
```
Status Codes:
- **200** – Deleted
- **401** – Unauthorized
@ -122,20 +146,32 @@ Content-Type: application/json
## Gets the home dashboard
`GET /api/dashboards/home`
Will return the home dashboard.
**Example Request**:
```http
GET /api/dashboards/home HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
```
**Example Response**:
```http
HTTP/1.1 200
## Tags for Dashboard
Content-Type: application/json
```
## Tags for Dashboard
`GET /api/dashboards/tags`
Get all tags of dashboards
Get all tags of dashboards
**Example Request**:
```http
@ -147,9 +183,16 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Dashboard Search
See [Folder/Dashboard Search API](/http_api/folder_dashboard_search).
## Deprecated resources
Please note that these resource have been deprecated and will be removed in a future release.
### Get dashboard by slug
@ -172,15 +215,6 @@ HTTP/1.1 200
**Example Response**:
```http
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
HTTP/1.1 200
Content-Type: application/json
@ -206,13 +240,21 @@ Content-Type: application/json
DELETE /api/dashboards/db/test HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
Status Codes:
- **200** – Deleted
- **401** – Unauthorized
- **403** – Access denied
- **404** – Not found
- **412** – Precondition failed
@ -244,21 +286,24 @@ Content-Type: application/json
]
```
## Search Dashboards
## Dashboard Search
See [Folder/Dashboard Search API](/http_api/folder_dashboard_search).
`GET /api/search/`
## Deprecated resources
Please note that these resource have been deprecated and will be removed in a future release.
Query parameters:
### Get dashboard by slug
**Deprecated starting from Grafana v5.0. Please update to use the new *Get dashboard by uid* resource instead**
- **query** – Search Query
- **tag** – Tag to use
- **starred** – Flag indicating if only starred Dashboards should be returned
- **tagcloud** - Flag indicating if a tagcloud should be returned
`GET /api/dashboards/db/:slug`
Will return the dashboard given the dashboard slug. Slug is the url friendly version of the dashboard title.
If there exists multiple dashboards with the same slug, one of them will be returned in the response.
**Example Request**:
```http
GET /api/search?query=Production%20Overview&starred=true&tag=prod HTTP/1.1
GET /api/dashboards/db/production-overview HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
@ -270,14 +315,78 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
HTTP/1.1 200
Content-Type: application/json
[
{
"id":1,
"title":"Production Overview",
"uri":"db/production-overview",
"type":"dash-db",
"tags":[prod],
"isStarred":true
{
"dashboard": {
"id": 1,
"uid": "cIBgcSjkk",
"title": "Production Overview",
"tags": [ "templated" ],
"timezone": "browser",
"rows": [
{
}
],
"schemaVersion": 6,
"version": 0
},
"meta": {
"isStarred": false,
"url": "/d/cIBgcSjkk/production-overview",
"slug": "production-overview" // deprecated in Grafana v5.0
}
]
}
```
Status Codes:
- **200** – Found
- **401** – Unauthorized
- **403** – Access denied
- **404** – Not found
### Delete dashboard by slug
**Deprecated starting from Grafana v5.0. Please update to use the *Delete dashboard by uid* resource instead.**
`DELETE /api/dashboards/db/:slug`
Will delete the dashboard given the specified slug. Slug is the url friendly version of the dashboard title.
**Example Request**:
```http
DELETE /api/dashboards/db/test HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{"title": "Production Overview"}
```
Status Codes:
- **200** – Deleted
- **401** – Unauthorized
- **403** – Access denied
- **404** – Not found
- **412** – Precondition failed
The **412** status code is used when there exists multiple dashboards with the same slug.
The response body will look like this:
```http
HTTP/1.1 412 Precondition Failed
Content-Type: application/json; charset=UTF-8
Content-Length: 97
{
"message": "Multiple dashboards with the same slug exists",
"status": "multiple-slugs-exists"
}
```

149
docs/sources/http_api/dashboard_permissions.md Normal file
View File

@ -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
```
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
```
Status Codes:
- **200** - Ok
- **401** - Unauthorized
- **403** - Access denied
- **404** - Dashboard not found
"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

317
docs/sources/http_api/folder.md Normal file
View File

@ -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
```
## 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
```
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
```
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
```
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
```
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
```
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
```
## 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
```
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
```
Status Codes:
- **200** – Found
- **401** – Unauthorized
- **403** – Access Denied
- **404** – Folder not found
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

98
docs/sources/http_api/folder_dashboard_search.md Normal file
View File

@ -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
```
**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
```
"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
}
]
```

149
docs/sources/http_api/folder_permissions.md Normal file
View File

@ -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
```
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
```
Status Codes:
- **200** - Ok
- **401** - Unauthorized
- **403** - Access denied
- **404** - Dashboard not found
"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

4
docs/sources/http_api/index.md
View File

@ -21,6 +21,10 @@ dashboards, creating users and updating data sources.
* [Authentication API]({{< relref "/http_api/auth.md" >}})
* [Dashboard API]({{< relref "/http_api/dashboard.md" >}})
* [Dashboard Versions API]({{< relref "http_api/dashboard_versions.md" >}})
* [Dashboard Permissions API]({{< relref "http_api/dashboard_permissions.md" >}})
* [Folder API]({{< relref "/http_api/folder.md" >}})
* [Folder Permissions API]({{< relref "http_api/folder_permissions.md" >}})
* [Folder/dashboard search API]({{< relref "/http_api/folder_dashboard_search.md" >}})
* [Data Source API]({{< relref "http_api/data_source.md" >}})
* [Organisation API]({{< relref "http_api/org.md" >}})
* [Snapshot API]({{< relref "http_api/snapshot.md" >}})

316
docs/sources/http_api/team.md Normal file
View File

@ -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
```
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
```
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=
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
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=
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
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
```
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
```
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=
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
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
```
Status Codes:
- **200** - Ok
- **401** - Unauthorized
- **403** - Permission denied
- **404** - Team not found/Team member not found
```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