Team API

This API can be used to manage Teams and Team Memberships.

Access to these API endpoints is restricted as follows:

  • All authenticated users are able to view details of teams they are a member of.
  • Organization Admins are able to manage all teams and team members.
  • If you enable editors_can_admin configuration flag, then Organization Editors can create teams and manage teams where they are Admin.
    • If you enable editors_can_admin configuration flag, Editors can find out whether a team that they are not members of exists by trying to create a team with the same name.

If you are running Grafana Enterprise and have Fine-grained access control enabled, access to endpoints will be controlled by Fine-grained access control permissions. Refer to specific endpoints to understand what permissions are required.

Team Search With Paging

GET /api/teams/search?perpage=50&page=1&query=myteam

or

GET /api/teams/search?name=myteam

Required permissions

See note in the introduction for an explanation.

ActionScope
teams:readteams:*

Example Request:

  1. GET /api/teams/search?perpage=10&page=1&query=mytestteam HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {
  5.   "totalCount": 1,
  6.   "teams": [
  7.     {
  8.       "id": 1,
  9.       "orgId": 1,
  10.       "name": "MyTestTeam",
  11.       "email": "",
  12.       "avatarUrl": "\/avatar\/3f49c15916554246daa714b9bd0ee398",
  13.       "memberCount": 1
  14.     }
  15.   ],
  16.   "page": 1,
  17.   "perPage": 1000
  18. }

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.

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

Required permissions

See note in the introduction for an explanation.

ActionScope
teams:readteams:*

Example Request:

  1. GET /api/teams/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {
  5.   "id": 1,
  6.   "orgId": 1,
  7.   "name": "MyTestTeam",
  8.   "email": "",
  9.   "created": "2017-12-15T10:40:45+01:00",
  10.   "updated": "2017-12-15T10:40:45+01:00"
  11. }

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,orgId is optional.

POST /api/teams

Required permissions

See note in the introduction for an explanation.

ActionScope
teams:createN/A

Example Request:

  1. POST /api/teams HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Basic YWRtaW46YWRtaW4=
  6. {
  7.   "name": "MyTestTeam",
  8.   "email": "email@test.com",
  9.   "orgId": 2
  10. }

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {"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

Required permissions

See note in the introduction for an explanation.

ActionScope
teams:writeteams:*

Example Request:

  1. PUT /api/teams/2 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Basic YWRtaW46YWRtaW4=
  6. {
  7.   "name": "MyTestTeam",
  8.   "email": "email@test.com"
  9. }

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {"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

Required permissions

See note in the introduction for an explanation.

ActionScope
teams:deleteteams:*

Example Request:

  1. DELETE /api/teams/2 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {"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

Required permissions

See note in the introduction for an explanation.

ActionScope
teams.permissions:readteams:*

Example Request:

  1. GET /api/teams/1/members HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. [
  5.   {
  6.     "orgId": 1,
  7.     "teamId": 1,
  8.     "userId": 3,
  9.     "email": "user1@email.com",
  10.     "login": "user1",
  11.     "avatarUrl": "\/avatar\/1b3c32f6386b0185c40d359cdc733a79"
  12.   },
  13.   {
  14.     "orgId": 1,
  15.     "teamId": 1,
  16.     "userId": 2,
  17.     "email": "user2@email.com",
  18.     "login": "user2",
  19.     "avatarUrl": "\/avatar\/cad3c68da76e45d10269e8ef02f8e73e"
  20.   }
  21. ]

Status Codes:

  • 200 - Ok
  • 401 - Unauthorized
  • 403 - Permission denied

Add Team Member

POST /api/teams/:teamId/members

Required permissions

See note in the introduction for an explanation.

ActionScope
teams.permissions:writeteams:*

Example Request:

  1. POST /api/teams/1/members HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Basic YWRtaW46YWRtaW4=
  6. {
  7.   "userId": 2
  8. }

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {"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

Required permissions

See note in the introduction for an explanation.

ActionScope
teams.permissions:writeteams:*

Example Request:

  1. DELETE /api/teams/2/members/3 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Basic YWRtaW46YWRtaW4=

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {"message":"Team Member removed"}

Status Codes:

  • 200 - Ok
  • 401 - Unauthorized
  • 403 - Permission denied
  • 404 - Team not found/Team member not found

Get Team Preferences

GET /api/teams/:teamId/preferences

Required permissions

See note in the introduction for an explanation.

ActionScope
teams:readteams:*

Example Request:

  1. GET /api/teams/2/preferences 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.   "theme": "",
  6.   "homeDashboardId": 0,
  7.   "timezone": ""
  8. }

Update Team Preferences

PUT /api/teams/:teamId/preferences

Required permissions

See note in the introduction for an explanation.

ActionScope
teams:writeteams:*

Example Request:

  1. PUT /api/teams/2/preferences HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  6. {
  7.   "theme": "dark",
  8.   "homeDashboardId": 39,
  9.   "timezone": "utc"
  10. }

JSON Body Schema:

  • theme - One of: light, dark, or an empty string for the default theme
  • homeDashboardId - The numerical :id of a dashboard, default: 0
  • timezone - One of: utc, browser, or an empty string for the default

Omitting a key will cause the current value to be replaced with the system default value.

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: text/plain; charset=utf-8
  4. {
  5.   "message":"Preferences updated"
  6. }