openapi: 3.0.3
info:
title: Grafana HTTP Access Rules 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: Rules
paths:
/datasources/uid/{uid}/lbac/teams:
parameters: []
get:
tags:
- Rules
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:
- Rules
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: false
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/updateTeamLBACRulesResponse'
'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
/convert/api/prom/rules:
parameters: []
get:
tags:
- Rules
summary: Grafana Route Convert Prometheus Cortex Get Rules
description: This API operation retrieves Prometheus or Cortex alerting and recording rules from a configured data source and converts them into Grafana's unified alerting format. It acts as a migration utility that fetches existing Prometheus-compatible rules and transforms them so they can be imported or managed within Grafana's alerting system, enabling users to consolidate their monitoring rules into Grafana's native rule structure while maintaining compatibility with Prometheus-style rule definitions.
operationId: routeConvertPrometheusCortexGetRules
parameters: []
responses:
'200':
description: PrometheusNamespace
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
post:
tags:
- Rules
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:
- Rules
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:
- Rules
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:
- Rules
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: []
get:
tags:
- Rules
summary: Grafana Route Convert Prometheus Get Rules
description: This API operation retrieves Prometheus alerting and recording rules from a Grafana instance and converts them into a standardized configuration format. When a GET request is made to the /convert/prometheus/config/v1/rules endpoint, it fetches the existing Prometheus-style rules configured within Grafana and transforms them into a version 1 configuration schema, making it easier to migrate, backup, or integrate these rules with other systems or Prometheus instances. This is particularly useful for administrators who need to export their Grafana-managed Prometheus rules or maintain consistency across multiple monitoring environments.
operationId: routeConvertPrometheusGetRules
parameters: []
responses:
'200':
description: PrometheusNamespace
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
post:
tags:
- Rules
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:
- Rules
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:
- Rules
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:
- Rules
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
/recording-rules:
parameters: []
get:
tags:
- Rules
summary: Grafana List Recording Rules
description: This API operation retrieves a list of all recording rules configured in Grafana. Recording rules are used to pre-compute frequently needed or computationally expensive expressions and save their result as a new set of time series data, which can improve query performance and reduce load on data sources. The GET request to the /recording-rules endpoint returns details about existing recording rules including their names, expressions, labels, and associated data sources, allowing administrators and users to view and manage their configured recording rules within the Grafana instance.
operationId: listRecordingRules
parameters: []
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RecordingRuleJSON'
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:
- Rules
summary: Grafana Update Recording Rule
description: Updates an existing recording rule in Grafana's alerting system. Recording rules are used to pre-calculate frequently needed or computationally expensive expressions and save their results as a new set of time series. This operation allows you to modify the configuration of a recording rule including its query expressions, labels, evaluation interval, and other parameters. You need to provide the complete updated recording rule configuration in the request body, and the rule will be identified by its UID or name. This is commonly used when you need to adjust the recording rule's query, change its labels, modify the evaluation frequency, or update any other aspect of how the rule processes and stores metric data. Proper authentication and appropriate permissions are required to perform this operation.
operationId: updateRecordingRule
parameters: []
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/RecordingRuleJSON'
required: true
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/RecordingRuleJSON'
'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:
- Rules
summary: Grafana Create Recording Rule
description: Creates a new recording rule in Grafana's alerting system that allows you to pre-compute frequently needed or computationally expensive expressions and save their result as a new set of time series. This POST endpoint accepts a recording rule definition including the rule name, query expression, labels, and evaluation interval, then stores it in the Grafana instance for continuous evaluation. Recording rules are particularly useful for dashboard performance optimization and creating aggregated metrics that can be queried more efficiently than running complex calculations repeatedly.
operationId: createRecordingRule
parameters: []
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/RecordingRuleJSON'
required: true
responses:
'200':
description: (empty)
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/RecordingRuleJSON'
'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:
S
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/grafana/refs/heads/main/openapi/grafana-rules-api-openapi.yml