openapi: 3.0.3
info:
title: Grafana HTTP Access Groups 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: Groups
paths:
/convert/api/prom/rules:
parameters: []
post:
tags:
- Groups
summary: Grafana Route Convert Prometheus Cortex Post Rule Groups
description: This API operation converts Prometheus or Cortex rule group configurations into Grafana's native format by accepting a POST request to the /convert/api/prom/rules endpoint. It enables users to migrate their existing Prometheus-style alerting and recording rules from Prometheus or Cortex deployments into Grafana, facilitating the transition between monitoring systems while preserving rule logic and structure. The endpoint processes the submitted rule groups and transforms them into a format compatible with Grafana's alerting engine, streamlining the configuration migration process and reducing manual conversion efforts.
operationId: routeConvertPrometheusCortexPostRuleGroups
parameters:
- name: Content-Type
in: header
description: ''
required: true
schema:
const: application/json
type: string
responses:
'202':
description: ConvertPrometheusResponse
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ConvertPrometheusResponse'
'403':
description: ForbiddenError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/convert/api/prom/rules/{NamespaceTitle}:
parameters: []
post:
tags:
- Groups
summary: Grafana Route Convert Prometheus Cortex Post Rule Group
description: The Grafana API operation POST /convert/api/prom/rules/{NamespaceTitle} converts and creates a Prometheus or Cortex rule group within a specified namespace. This endpoint accepts Prometheus-style rule definitions and transforms them into Grafana's native alert rule format, allowing users to migrate their existing Prometheus alerting and recording rules into Grafana's unified alerting system. The {NamespaceTitle} parameter identifies the target namespace where the converted rule group will be stored, enabling organized management of alert rules across different teams or services within Grafana.
operationId: routeConvertPrometheusCortexPostRuleGroup
parameters:
- name: NamespaceTitle
in: path
description: ''
required: true
schema:
type: string
- name: x-grafana-alerting-datasource-uid
in: header
description: ''
schema:
type: string
- name: x-grafana-alerting-recording-rules-paused
in: header
description: ''
schema:
type: boolean
- name: x-grafana-alerting-alert-rules-paused
in: header
description: ''
schema:
type: boolean
- name: x-grafana-alerting-target-datasource-uid
in: header
description: ''
schema:
type: string
- name: x-grafana-alerting-folder-uid
in: header
description: ''
schema:
type: string
- name: x-grafana-alerting-notification-settings
in: header
description: ''
schema:
type: string
requestBody:
description: ''
content:
application/yaml:
schema:
$ref: '#/components/schemas/PrometheusRuleGroup'
required: false
responses:
'202':
description: ConvertPrometheusResponse
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ConvertPrometheusResponse'
'403':
description: ForbiddenError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/convert/api/prom/rules/{NamespaceTitle}/{Group}:
parameters: []
get:
tags:
- Groups
summary: Grafana Route Convert Prometheus Cortex Get Rule Group
description: 'This API operation retrieves a specific Prometheus rule group from a designated namespace in Grafana''s Cortex ruler service. The endpoint accepts two path parameters: NamespaceTitle which identifies the namespace containing the rule group, and Group which specifies the name of the rule group to retrieve. When called, it returns the configuration and rules defined within that particular rule group, allowing users to view and manage their Prometheus alerting and recording rules that have been converted or stored in the Cortex format within Grafana''s unified alerting system.'
operationId: routeConvertPrometheusCortexGetRuleGroup
parameters:
- name: NamespaceTitle
in: path
description: ''
required: true
schema:
type: string
- name: Group
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: PrometheusRuleGroup
headers: {}
content:
application/yaml:
schema:
contentMediaType: application/yaml
'403':
description: ForbiddenError
headers: {}
content:
application/yaml:
schema:
contentMediaType: application/yaml
'404':
description: NotFound
headers: {}
content:
application/yaml:
schema:
contentMediaType: application/yaml
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
delete:
tags:
- Groups
summary: Grafana Route Convert Prometheus Cortex Delete Rule Group
description: This API operation is used to delete a specific Prometheus rule group within Grafana's Cortex-based alerting system. It targets a rule group identified by both its namespace title and group name through the URL path parameters. When called with the DELETE HTTP method, it removes the entire rule group configuration from the specified namespace, effectively eliminating all alert and recording rules contained within that group from the Prometheus-compatible rules engine in Grafana.
operationId: routeConvertPrometheusCortexDeleteRuleGroup
parameters:
- name: NamespaceTitle
in: path
description: ''
required: true
schema:
type: string
- name: Group
in: path
description: ''
required: true
schema:
type: string
responses:
'202':
description: ConvertPrometheusResponse
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ConvertPrometheusResponse'
'403':
description: ForbiddenError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/convert/prometheus/config/v1/rules:
parameters: []
post:
tags:
- Groups
summary: Grafana Route Convert Prometheus Post Rule Groups
description: This API operation converts Prometheus rule group configurations to Grafana's format via a POST request to the /convert/prometheus/config/v1/rules endpoint. It accepts Prometheus-formatted rule groups as input and transforms them into a compatible format that can be used within Grafana's alerting and recording rule system, facilitating migration or integration between Prometheus and Grafana monitoring setups.
operationId: routeConvertPrometheusPostRuleGroups
parameters:
- name: Content-Type
in: header
description: ''
required: true
schema:
const: application/json
type: string
responses:
'202':
description: ConvertPrometheusResponse
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ConvertPrometheusResponse'
'403':
description: ForbiddenError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/convert/prometheus/config/v1/rules/{NamespaceTitle}:
parameters: []
post:
tags:
- Groups
summary: Grafana Route Convert Prometheus Post Rule Group
description: This API operation converts Prometheus rule group configurations to Grafana's native format by accepting a POST request to the endpoint /convert/prometheus/config/v1/rules/{NamespaceTitle}, where {NamespaceTitle} represents the target namespace for the rule group. It takes Prometheus-formatted alerting and recording rules as input and transforms them into Grafana-compatible rule configurations, facilitating migration or integration between Prometheus and Grafana alerting systems. The operation allows users to seamlessly transfer their existing Prometheus rule definitions into Grafana without manual reconfiguration, preserving the rule logic, labels, annotations, and evaluation intervals while adapting them to Grafana's rule management structure.
operationId: routeConvertPrometheusPostRuleGroup
parameters:
- name: NamespaceTitle
in: path
description: ''
required: true
schema:
type: string
- name: x-grafana-alerting-datasource-uid
in: header
description: ''
schema:
type: string
- name: x-grafana-alerting-recording-rules-paused
in: header
description: ''
schema:
type: boolean
- name: x-grafana-alerting-alert-rules-paused
in: header
description: ''
schema:
type: boolean
- name: x-grafana-alerting-target-datasource-uid
in: header
description: ''
schema:
type: string
- name: x-grafana-alerting-folder-uid
in: header
description: ''
schema:
type: string
- name: x-grafana-alerting-notification-settings
in: header
description: ''
schema:
type: string
requestBody:
description: ''
content:
application/yaml:
schema:
$ref: '#/components/schemas/PrometheusRuleGroup'
required: false
responses:
'202':
description: ConvertPrometheusResponse
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ConvertPrometheusResponse'
'403':
description: ForbiddenError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/convert/prometheus/config/v1/rules/{NamespaceTitle}/{Group}:
parameters: []
get:
tags:
- Groups
summary: Grafana Route Convert Prometheus Get Rule Group
description: This API operation retrieves and converts a Prometheus rule group configuration from a specific namespace in Grafana. It accepts GET requests at the endpoint path that includes both the namespace title and group name as path parameters, allowing users to fetch the configuration details of a particular Prometheus alerting or recording rule group. The operation is part of Grafana's conversion utilities that help transform Prometheus-native rule configurations into Grafana's internal format or vice versa, facilitating migration and management of alerting rules across different monitoring system configurations.
operationId: routeConvertPrometheusGetRuleGroup
parameters:
- name: NamespaceTitle
in: path
description: ''
required: true
schema:
type: string
- name: Group
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: PrometheusRuleGroup
headers: {}
content:
application/yaml:
schema:
contentMediaType: application/yaml
'403':
description: ForbiddenError
headers: {}
content:
application/yaml:
schema:
contentMediaType: application/yaml
'404':
description: NotFound
headers: {}
content:
application/yaml:
schema:
contentMediaType: application/yaml
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
delete:
tags:
- Groups
summary: Grafana Route Convert Prometheus Delete Rule Group
description: This API operation is used to delete a Prometheus rule group from a specific namespace in Grafana's configuration. It targets a particular rule group identified by both the namespace title and group name through the URL path parameters. When invoked with a DELETE HTTP method, it removes the specified rule group configuration from the Prometheus-compatible alerting and recording rules system within Grafana, effectively cleaning up rules that are no longer needed or are being replaced.
operationId: routeConvertPrometheusDeleteRuleGroup
parameters:
- name: NamespaceTitle
in: path
description: ''
required: true
schema:
type: string
- name: Group
in: path
description: ''
required: true
schema:
type: string
responses:
'202':
description: ConvertPrometheusResponse
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ConvertPrometheusResponse'
'403':
description: ForbiddenError
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
deprecated: false
x-api-evangelist-processing:
SplitPascalCaseOperationSummaries: true
CaselCaseOperationIds: true
WriteDescription: true
ChooseTags: true
/groupsync/groups:
parameters: []
get:
tags:
- Groups
summary: Grafana Get Mapped Groups
description: The Get Mapped Groups API operation retrieves a list of groups that have been configured for synchronization in Grafana's group sync functionality. This GET endpoint at /groupsync/groups returns information about groups that are mapped between an external authentication provider (such as LDAP, OAuth, or SAML) and Grafana's internal team structure, allowing administrators to view which external groups are currently being synchronized and how they correspond to teams within Grafana for access control and permission management purposes.
operationId: getMappedGroups
parameters: []
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/getGroupsResponse'
'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'
'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
/groupsync/groups/{group_id}:
parameters: []
put:
tags:
- Groups
summary: Grafana Update Group Mappings
description: This API operation updates the group mappings for a specific group in Grafana's group synchronization system. By sending a PUT request to the endpoint with a particular group ID, administrators can modify how external authentication groups (such as those from LDAP, OAuth, or SAML providers) are mapped to internal Grafana groups. This allows for dynamic management of user permissions and access control by adjusting which external groups correspond to specific Grafana organizational roles and teams. The operation requires the group ID as a path parameter and accepts a payload containing the updated mapping configuration, enabling seamless integration between external identity providers and Grafana's authorization model.
operationId: updateGroupMappings
parameters:
- name: group_id
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GroupAttributes'
required: true
responses:
'201':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/messageResponse'
'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'
'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:
- Groups
summary: Grafana Create Group Mappings
description: This API operation creates group mappings for a specific group in Grafana's group synchronization system. It uses a POST request to the endpoint /groupsync/groups/{group_id}, where {group_id} is a path parameter identifying the target group for which mappings should be created. The operation establishes connections between external authentication provider groups (such as LDAP, OAuth, or SAML groups) and Grafana's internal groups, enabling automated user group assignment based on their external group memberships. This functionality is essential for organizations implementing single sign-on (SSO) or centralized user management, as it allows administrators to synchronize group memberships from external identity providers to Grafana, ensuring users automatically receive appropriate permissions and access rights based on their organizational roles without manual intervention.
operationId: createGroupMappings
parameters:
- name: group_id
in: path
description: ''
required: true
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GroupAttributes'
required: true
responses:
'201':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/messageResponse'
'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'
'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:
- Groups
summary: Grafana Delete Group Mappings
description: This API operation removes group mappings associated with a specific group in Grafana's group synchronization system. By sending a DELETE request to the endpoint with a particular group ID, administrators can eliminate the synchronization configuration that links external identity provider groups to Grafana teams or roles. This is useful when cleaning up deprecated mappings, removing access controls, or reconfiguring how external groups are mapped within Grafana's authorization structure.
operationId: deleteGroupMappings
parameters:
- name: group_id
in: path
description: ''
required: true
schema:
type: string
responses:
'204':
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'
'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'
'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
/groupsync/groups/{group_id}/roles:
parameters: []
get:
tags:
- Groups
summary: Grafana Get Group Roles
description: This API operation retrieves the roles associated with a specific group in Grafana's group synchronization system. By providing a group_id in the URL path, the GET request returns information about what roles have been assigned to that particular group, which is useful for managing permissions and access control in Grafana when using external group synchronization features like LDAP or OAuth.
operationId: getGroupRoles
parameters:
- name: group_id
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RoleDTO'
description: ''
contentMediaType: application/json
'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
/teams/{teamId}/groups:
parameters: []
get:
tags:
- Groups
summary: Grafana Get Team Groups Api
description: This API operation retrieves the list of external groups that are synchronized with a specific team in Grafana. By providing a team ID in the path parameter, the endpoint returns all groups that have been mapped or linked to that team, which is particularly useful in environments where Grafana teams are integrated with external authentication providers like LDAP, OAuth, or SAML. This allows administrators to view and verify which external directory groups have access to a particular Grafana team, helping maintain proper access control and team membership management across integrated systems.
operationId: getTeamGroupsApi
parameters:
- name: teamId
in: path
description: ''
required: true
schema:
type: string
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TeamGroupDTO'
description: ''
contentMediaType: application/json
'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
post:
tags:
- Groups
summary: Grafana Add Team Group Api
description: The Add Team Group API is a POST operation available at the endpoint /teams/{teamId}/groups in Grafana that allows administrators to associate an external authentication group with a specific Grafana team. This operation requires the teamId parameter in the URL path to identify the target team, and typically accepts a request bod
# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/grafana/refs/heads/main/openapi/grafana-groups-api-openapi.yml