New AlertRule and RecordingRule APIs for Grafana Managed Alerts
New AlertRule and RecordingRule APIs for Grafana Managed Alerts
You can now manage Grafana-managed alert rules and recording rules as first-class resources through the Grafana App Platform APIs. The new AlertRule and RecordingRule types in the rules.alerting.grafana.app API group give each rule its own versioned, schema-validated resource, built on the same Kubernetes-style API model as dashboards and folders.
One resource per rule
Each alert rule and recording rule is its own resource with a stable name, so you can create, read, update, and delete a single rule without touching the rest of its rule group. Use standard REST verbs against these endpoints:
/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules/apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/recordingrules
Every resource carries standard metadata, including a resourceVersion for optimistic concurrency and who created and last updated it. Concurrent changes don’t silently overwrite each other.
A dedicated type for each kind of rule
Alert rules and recording rules now have separate schemas, each with only the fields that apply to it:
AlertRule: the query and expressions, evaluation interval, pending period (for),keepFiringFor, no data and error handling, labels, annotations, an optional dashboard panel link, and notification settings. You can route notifications to a contact point directly or to a named notification policy tree.RecordingRule: the query and expressions, evaluation interval, labels, the name of the metric to record, and the data source to write it to.
Grafana validates each request against the schema when you submit it, so mistakes such as an invalid duration, a malformed metric name, or a missing source expression are rejected with a clear error instead of surfacing at evaluation time.
Rule status in the same place as its definition
Each resource includes a status that reports how the rule is running: its health, last evaluation time and duration, and last error. Alert rules also report their current state and how many alert instances are firing, pending, recovering, healthy, in no data, or in error. You can check whether a rule works from the same response you used to define it.
Built for automation
Because these APIs follow the Kubernetes resource model, they fit the tools you already use to manage configuration as code. You can filter lists with field selectors, such as by title, paused state, linked dashboard, contact point, recorded metric, or target data source, which makes it easier to find and sync exactly the rules you need from CI/CD pipelines, GitOps workflows, and custom tooling.
You can already manage these resources with:
- gcx
- grafanactl
- The Grafana Terraform provider, with the
grafana_apps_rules_alertrule_v0alpha1andgrafana_apps_rules_recordingrule_v0alpha1resources, which use thev0alpha1API (v1beta1resources will land in the next release!)
API version and stability
The APIs are available as v1beta1. From v1beta1 onward, we’ll avoid breaking changes until the APIs reach v1.
The earlier v0alpha1 version is still served, so existing clients keep working, but we recommend moving to v1beta1. In v1beta1, an alert rule’s notification settings must include a type (SimplifiedRouting or NamedRoutingTree). v0alpha1 still treats a missing type as SimplifiedRouting.
The AlertRule and RecordingRule APIs replace the alert rule endpoints in the alerting provisioning HTTP API, which are now deprecated. Plan to move your automation to the new APIs.
