Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentationbreadcrumb arrow Grafana documentationbreadcrumb arrow Developer resourcesbreadcrumb arrow Grafana APIsbreadcrumb arrow HTTP APIbreadcrumb arrow Legacy Grafana HTTP APIbreadcrumb arrow Team Sync HTTP API
Enterprise Open source Grafana Cloud

Team Sync API

Note

Starting in Grafana 13, /api endpoints are being deprecated in favor of the /apis route. Note that while Grafana is working on migrating existing APIs, currently there may not be an exact match to the legacy API you’re using.

This change doesn’t disrupt or break your current setup. Legacy APIs are not being disabled and remain fully accessible and operative, but /api routes will no longer be updated.

To learn more refer to the new API structure in Grafana.

Team Sync is only available in Grafana Enterprise. Read more about Grafana Enterprise.

If you are running Grafana Enterprise, for some endpoints you’ll need to have specific permissions. Refer to Role-based access control permissions for more information.

Get External Groups

GET /api/teams/:teamId/groups

Required permissions

See note in the introduction for an explanation.

ActionScope
teams.permissions:readteams:*

Example Request:

http 
GET /api/teams/1/groups HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697

Example Response:

http 
HTTP/1.1 200
Content-Type: application/json

[
  {
    "orgId": 1,
    "teamId": 1,
    "groupId": "cn=editors,ou=groups,dc=grafana,dc=org"
  }
]

Status Codes:

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

Add External Group

POST /api/teams/:teamId/groups

Required permissions

See note in the introduction for an explanation.

ActionScope
teams.permissions:writeteams:*

Example Request:

http 
POST /api/teams/1/groups HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer YWRtaW46YWRtaW4=

{
  "groupId": "cn=editors,ou=groups,dc=grafana,dc=org"
}

Example Response:

http 
HTTP/1.1 200
Content-Type: application/json

{"message":"Group added to Team"}

Status Codes:

  • 200 - Ok
  • 400 - Group is already added to this team
  • 401 - Unauthorized
  • 403 - Permission denied
  • 404 - Team not found

Remove External Group

DELETE /api/teams/:teamId/groups?groupId=external-group-id

Required permissions

See note in the introduction for an explanation.

ActionScope
teams.permissions:writeteams:*

Example Request:

http 
DELETE /api/teams/1/groups?groupId=cn%3Deditors%2Cou%3Dgroups%2Cdc%3Dgrafana%2Cdc%3Dorg HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697

Example Response:

http 
HTTP/1.1 200
Content-Type: application/json

{"message":"Team Group removed"}

Status Codes:

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

Search Team Groups

GET /api/teams/:teamId/groups/search

Search for team groups with pagination support.

Required permissions

ActionScope
teams.permissions:readteams:*

Example Request:

http 
GET /api/teams/1/groups/search?name=editors&query=group&page=1&perpage=10 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697

Example Response:

http 
HTTP/1.1 200
Content-Type: application/json

[
  {
    "totalCount": 1,
    "teamGroups": [
      {
        "orgId": 1,
        "teamId": 1,
        "groupId": "cn=editors,ou=groups,dc=grafana,dc=org"
      }
    ],
    "page": 1,
    "perPage": 10
  }
]

Status Codes:

  • 200 - Ok
  • 400 - Bad Request (invalid team ID format or missing query parameter)
  • 401 - Unauthorized
  • 403 - Permission denied
  • 500 - Internal Server Error