openapi: 3.0.3
info:
title: Grafana HTTP Access Teams API
description: The Grafana HTTP API provides programmatic access to Grafana's core functionality including dashboards, data sources, alerts, users, organizations, folders, annotations, and teams. Authentication is handled via API keys, basic auth, or OAuth tokens passed in the Authorization header.
version: 11.0.0
contact:
name: Grafana Labs
url: https://grafana.com
license:
name: AGPL-3.0
url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: https://{instance}.grafana.net/api
description: Grafana Cloud
variables:
instance:
default: your-instance
- url: http://localhost:3000/api
description: Local Grafana instance
security:
- BearerAuth: []
- BasicAuth: []
- ApiKeyAuth: []
tags:
- name: Teams
description: Team management
paths:
/teams/search:
parameters: []
get:
tags:
- Teams
operationId: searchTeams
summary: Search teams
parameters:
- name: query
in: query
schema:
type: string
- name: page
in: query
schema:
type: integer
- name: perpage
in: query
schema:
type: integer
responses:
'200':
description: Teams
content:
application/json:
schema:
$ref: '#/components/schemas/TeamSearchResult'
/teams:
parameters: []
post:
tags:
- Teams
operationId: createTeam
summary: Create team
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTeamCommand'
responses:
'200':
description: Team created
/teams/{id}:
get:
tags:
- Teams
operationId: getTeamById
summary: Get team by ID
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Team
content:
application/json:
schema:
$ref: '#/components/schemas/Team'
put:
tags:
- Teams
operationId: updateTeam
summary: Update team
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTeamCommand'
responses:
'200':
description: Team updated
delete:
tags:
- Teams
operationId: deleteTeam
summary: Delete team
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Team deleted
/teams/{id}/members:
get:
tags:
- Teams
operationId: getTeamMembers
summary: Get team members
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Team members
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TeamMember'
post:
tags:
- Teams
operationId: addTeamMember
summary: Add team member
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddTeamMemberCommand'
responses:
'200':
description: Member added
/teams/{team_id}:
parameters: []
get:
tags:
- Teams
summary: Grafana Get Team By ID
description: This API operation retrieves detailed information about a specific team in Grafana by providing the team's unique identifier in the URL path. When a GET request is made to the /teams/{team_id} endpoint with a valid team ID, the API returns comprehensive data about that team, including properties such as the team name, email address, member count, and other relevant team metadata. This endpoint is typically used by administrators or applications that need to fetch information about a particular team for display purposes, integration workflows, or team management operations within the Grafana platform.
operationId: getTeamByID
parameters:
- name: team_id
in: path
description: ''
required: true
schema:
type: string
- name: accesscontrol
in: query
description: ''
style: form
explode: true
schema:
type: boolean
default: false
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/TeamDTO'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
put:
tags:
- Teams
summary: Grafana Update Team
description: Updates an existing team in Grafana by modifying its properties such as name and email address. This endpoint requires the team ID as a path parameter and accepts a JSON payload containing the updated team information. The operation is typically used by administrators or users with appropriate permissions to maintain team configurations, ensuring that team metadata remains current and accurate within the Grafana organization.
operationId: updateTeam
parameters:
- name: team_id
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTeamCommand_2'
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'409':
description: ConflictError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
delete:
tags:
- Teams
summary: Grafana Delete Team By ID
description: This API operation removes a specific team from a Grafana instance by providing the team's unique identifier in the URL path. When executed, it performs a DELETE request to the endpoint /teams/{team_id}, where {team_id} is replaced with the numerical ID of the team to be deleted. The operation requires appropriate administrative permissions and will permanently remove the team along with its associated configurations, memberships, and permissions. Upon successful execution, the team will no longer exist in the Grafana system, and all users previously assigned to that team will lose their team-based access rights and dashboard permissions granted through that team membership.
operationId: deleteTeamByID
parameters:
- name: team_id
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/teams/{team_id}/members:
parameters: []
get:
tags:
- Teams
summary: Grafana Get Team Members
description: This API operation retrieves a list of all members belonging to a specific team in Grafana by providing the team's unique identifier in the URL path. When called, it returns detailed information about each team member including their user ID, email, login credentials, and role within the team. This is useful for administrators and team leaders who need to audit team composition, manage access permissions, or integrate Grafana team data with external systems for user management and reporting purposes.
operationId: getTeamMembers
parameters:
- name: team_id
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TeamMemberDTO'
description: ''
contentMediaType: application/json
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
put:
tags:
- Teams
summary: Grafana Set Team Memberships
description: The PUT operation on the /teams/{team_id}/members endpoint in Grafana allows administrators to set or update the complete membership roster for a specific team by providing the team_id parameter. This operation replaces the existing team membership list with the new set of members specified in the request body, effectively adding new members and removing any members not included in the updated list. It provides a comprehensive way to manage team composition in a single API call, rather than adding or removing members individually. The operation requires appropriate administrative permissions and is useful for bulk synchronization of team memberships, such as when integrating with external directory services or performing organizational restructuring within Grafana's access control system.
operationId: setTeamMemberships
parameters:
- name: team_id
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SetTeamMembershipsCommand'
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
post:
tags:
- Teams
summary: Grafana Add Team Member
description: This API operation adds a new member to a specific team in Grafana by making a POST request to the /teams/{team_id}/members endpoint, where {team_id} is the unique identifier of the team. The operation allows administrators or users with appropriate permissions to expand team membership by associating additional users with an existing team, typically requiring the user ID or username to be specified in the request body to identify which user should be added to the team.
operationId: addTeamMember
parameters:
- name: team_id
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AddTeamMemberCommand_2'
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/teams/{team_id}/members/{user_id}:
parameters: []
put:
tags:
- Teams
summary: Grafana Update Team Member
description: Updates the permissions of an existing team member in Grafana by specifying the team ID and user ID in the request path. This PUT operation allows administrators to modify a user's role or permission level within a specific team, such as changing them from a member to an admin or vice versa. The request typically requires authentication and appropriate administrative privileges to execute successfully, and it modifies the existing team membership record rather than creating a new one.
operationId: updateTeamMember
parameters:
- name: team_id
in: path
description: ''
required: true
schema:
type: string
- name: user_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTeamMemberCommand'
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
delete:
tags:
- Teams
summary: Grafana Remove Team Member
description: Removes a specific user from a team by their user ID. This operation requires the team ID and user ID as path parameters. When executed, it deletes the membership association between the specified user and team, effectively revoking the user's access to team-specific resources and permissions. This is typically used when a user no longer needs to be part of a team or when reorganizing team structures within Grafana.
operationId: removeTeamMember
parameters:
- name: team_id
in: path
description: ''
required: true
schema:
type: string
- name: user_id
in: path
description: ''
required: true
schema:
type: integer
contentEncoding: int64
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/teams/{team_id}/preferences:
parameters: []
get:
tags:
- Teams
summary: Grafana Get Team Preferences
description: Returns the preferences for a specific Grafana team identified by the team_id parameter, which includes settings such as the team's home dashboard, timezone, and theme preferences. This GET endpoint allows administrators and team members with appropriate permissions to retrieve the current preference configuration that applies to all members of the specified team, enabling them to view or audit the team-level settings that override individual user preferences when working within the team context.
operationId: getTeamPreferences
parameters:
- name: team_id
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/PreferencesSpec'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
put:
tags:
- Teams
summary: Grafana Update Team Preferences
description: Updates the preferences for a specific team in Grafana by making a PUT request to the /teams/{team_id}/preferences endpoint. This operation allows administrators or team members with appropriate permissions to modify team-level settings such as the default home dashboard, timezone, and theme preferences. The team_id parameter in the URL path identifies which team's preferences should be updated, and the request body contains the preference values to be applied. These preferences will affect the default Grafana interface experience for all members of the specified team, overriding individual user preferences when those team members are operating within the team context.
operationId: updateTeamPreferences
parameters:
- name: team_id
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePrefsCmd'
required: true
responses:
'200':
description: An OKResponse is returned if the request was successful.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponseBody'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/datasources/uid/{uid}/lbac/teams:
parameters: []
get:
tags:
- Teams
summary: Grafana Get Team LBAC Rules Api
description: This API operation retrieves team-based Label-Based Access Control (LBAC) rules for a specific data source in Grafana identified by its unique identifier (uid). When called with a GET request to the endpoint /datasources/uid/{uid}/lbac/teams, it returns the configured LBAC rules that determine which teams have access to specific labels or subsets of data within the specified data source. This functionality is essential for managing granular permissions and ensuring teams can only query and view data they are authorized to access within multi-tenant Grafana environments.
operationId: getTeamLBACRulesApi
parameters:
- name: uid
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/TeamLBACRules'
'400':
description: BadRequestError is returned when the request is invalid and it cannot be processed.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'401':
description: UnauthorizedError is returned when the request is not authenticated.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'403':
description: ForbiddenError is returned if the user/token has insufficient permissions to access the requested resource.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'404':
description: NotFoundError is returned when the requested resource was not found.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
'500':
description: InternalServerError is a general error indicating something went wrong internally.
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
put:
tags:
- Teams
summary: Grafana Update Team LBAC Rules Api
description: This API operation updates the Label-Based Access Control (LBAC) rules for teams associated with a specific data source in Grafana. It uses the PUT method and targets a data source identified by its unique identifier (uid) in the endpoint path. The operation allows administrators to modify which teams have access to specific labels or subsets of data within the data source, enabling fine-grained access control at the team level. By updating these LBAC rules, organizations can ensure that different teams only have access to the data relevant to their roles and responsibilities, maintaining security and data governance policies within their Grafana instance.
operationId: updateTeamLBACRulesApi
parameters:
- name: uid
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTeamLBACCommand'
required: fals
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/grafana/refs/heads/main/openapi/grafana-teams-api-openapi.yml