Use the new HTTP APIs to manage alerting resources
Use the new Grafana HTTP APIs (/apis) to create, update, and delete Grafana-managed alerting resources as standalone, versioned objects. Unlike the legacy
Alerting Provisioning HTTP API, these APIs validate requests against a typed schema, track optimistic concurrency with metadata.resourceVersion, and let you manage individual rules without rewriting an entire rule group.
Alerting resources are served across two API groups (plus a Grafana Cloud API group for alert enrichment):
rules.alerting.grafana.app/v1beta1: Alert rules, recording rules, and rule sequences. For full schemas and status codes, refer to the Alert rules HTTP API reference.notifications.alerting.grafana.app/v1beta1: Contact points (receivers), notification policy trees (routingtrees), notification template groups (templategroups), mute timings and active time intervals (timeintervals), inhibition rules (inhibitionrules), and external Alertmanager sync (configs). For full schemas and status codes, refer to the Alert notifications HTTP API reference.alertenrichment.grafana.app/v1beta1(Grafana Cloud only): Alert enrichment pipelines (alert-enrichments). Refer to the Alert enrichment HTTP API reference.
Before you begin
Before you begin, ensure you have the following:
Grafana Alerting enabled: Grafana Alerting must be enabled on your instance.
Namespace: Determine your instance’s
{namespace}:- Grafana OSS and Enterprise:
defaultfor organization 1, ororg-<ORG_ID>for other organizations. - Grafana Cloud:
stacks-<STACK_ID>.
For more details, refer to API structure in Grafana.
- Grafana OSS and Enterprise:
Authentication and permissions: Authenticate with a service account token (or basic authentication in OSS and Enterprise). By default, Viewer grants read access and Editor or Admin grants write access. For granular role-based access control (RBAC) permissions, refer to Configure RBAC for Grafana Alerting.
A folder for rules: Alert rules, recording rules, and rule sequences must belong to a folder. Pass the folder UID in
metadata.annotations["grafana.app/folder"].
Note
The JSON returned by
/apisendpoints uses the Kubernetes-style resource envelope (apiVersion,kind,metadata,spec) and isn’t compatible with provisioning via configuration files. To export resources in file-provisioning format, continue using the Export API endpoints on the legacy API.
Manage rules (rules.alerting.grafana.app/v1beta1)
Each rule resource is stored in a folder (metadata.annotations["grafana.app/folder"]) and identified in URL paths by metadata.name (its rule UID). For complete field definitions and status codes, refer to the
Alert rules HTTP API reference.
All three resources support GET (list and get), POST (create), PUT (replace), PATCH (partial update), and DELETE.
Provision an alert rule
Send a POST request to /apis/rules.alerting.grafana.app/v1beta1/namespaces/{namespace}/alertrules to create an AlertRule. Set "source": true on the expression node that acts as the alert condition, and specify notificationSettings.type (SimplifiedRouting or NamedRoutingTree) when routing directly from the rule:
POST /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/alertrules HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "rules.alerting.grafana.app/v1beta1",
"kind": "AlertRule",
"metadata": {
"name": "high-cpu-usage",
"annotations": {
"grafana.app/folder": "<FOLDER_UID>",
"grafana.com/provenance": "api"
}
},
"spec": {
"title": "High CPU usage",
"trigger": {
"interval": "1m"
},
"for": "5m",
"noDataState": "NoData",
"execErrState": "Error",
"labels": {
"severity": "warning"
},
"annotations": {
"summary": "CPU usage is above 80%"
},
"notificationSettings": {
"type": "SimplifiedRouting",
"receiver": "On-call webhook"
},
"expressions": {
"A": {
"queryType": "",
"datasourceUID": "<DATASOURCE_UID>",
"relativeTimeRange": {
"from": "5m",
"to": "0s"
},
"model": {
"expr": "100 - (avg by (instance) (rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100)"
}
},
"B": {
"model": {
"type": "reduce",
"expression": "A",
"reducer": "last"
}
},
"C": {
"source": true,
"model": {
"type": "threshold",
"expression": "B",
"conditions": [
{
"evaluator": {
"type": "gt",
"params": [80]
}
}
]
}
}
}
}
}Replace <SERVICE_ACCOUNT_TOKEN>, <FOLDER_UID>, and <DATASOURCE_UID> with values from your Grafana instance.
Provision a recording rule
Recording rules use a dedicated RecordingRule resource instead of sharing the alert rule payload. Specify the output metric name in spec.metric and the destination Prometheus-compatible data source in spec.targetDatasourceUID:
POST /apis/rules.alerting.grafana.app/v1beta1/namespaces/default/recordingrules HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "rules.alerting.grafana.app/v1beta1",
"kind": "RecordingRule",
"metadata": {
"name": "service-request-rate",
"annotations": {
"grafana.app/folder": "<FOLDER_UID>",
"grafana.com/provenance": "api"
}
},
"spec": {
"title": "Service request rate",
"metric": "job:http_requests_total:rate5m",
"targetDatasourceUID": "<TARGET_DATASOURCE_UID>",
"trigger": {
"interval": "1m"
},
"expressions": {
"A": {
"source": true,
"datasourceUID": "<SOURCE_DATASOURCE_UID>",
"relativeTimeRange": {
"from": "5m",
"to": "0s"
},
"model": {
"expr": "sum by (job) (rate(http_requests_total[5m]))"
}
}
}
}
}Replace <SERVICE_ACCOUNT_TOKEN>, <FOLDER_UID>, <SOURCE_DATASOURCE_UID>, and <TARGET_DATASOURCE_UID> with values from your Grafana instance.
Order rule evaluation with rule sequences
Because each rule is managed independently rather than inside a rule group payload, use a RuleSequence resource when a recording rule or alert rule depends on the output of another recording rule in the same folder. For details, refer to
Configure rule sequences and
Rule sequences in the Alert rules HTTP API.
Manage notification resources (notifications.alerting.grafana.app/v1beta1)
Notification resources are scoped to {namespace} (not to folders) and return resources from both active and staged Alertmanager configurations. For complete field definitions and status codes, refer to the
Alert notifications HTTP API reference.
Note
To manage access-control permissions on individual contact points for users, teams, or built-in roles, continue using the
/api/access-control/receivers/*endpoints documented in Receiver permissions.
Contact points
A Receiver resource groups all integrations for a contact point into spec.integrations. To inspect supported integration type values and required settings fields, send GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/integrationtypeschemas.
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/receivers HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "notifications.alerting.grafana.app/v1beta1",
"kind": "Receiver",
"metadata": {
"name": "oncall-webhook",
"annotations": {
"grafana.com/provenance": "api"
}
},
"spec": {
"title": "On-call webhook",
"integrations": [
{
"type": "webhook",
"version": "1",
"disableResolveMessage": false,
"settings": {
"url": "https://example.com/alerts/webhook",
"httpMethod": "POST"
}
}
]
}
}Notification policies
The organization’s default notification policy tree is a RoutingTree resource named user-defined (Grafana also accepts default as an alias). Retrieve it first with GET to obtain its metadata.resourceVersion, then update it with PUT:
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/routingtrees/user-defined HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "notifications.alerting.grafana.app/v1beta1",
"kind": "RoutingTree",
"metadata": {
"name": "user-defined",
"resourceVersion": "<RESOURCE_VERSION>",
"annotations": {
"grafana.com/provenance": "api"
}
},
"spec": {
"defaults": {
"receiver": "grafana-default-email",
"group_by": ["grafana_folder", "alertname"],
"group_wait": "30s",
"group_interval": "5m",
"repeat_interval": "4h"
},
"routes": [
{
"receiver": "On-call webhook",
"continue": false,
"mute_time_intervals": ["Weekends"],
"matchers": [
{
"label": "severity",
"type": "=",
"value": "critical"
}
]
}
]
}
}Replace <RESOURCE_VERSION> with the metadata.resourceVersion from GET .../routingtrees/user-defined. You can also create additional named routing trees with POST /routingtrees so alert rules can target them directly.
Notification template groups and mute timings
Create notification template groups with POST .../templategroups and mute timings or active time intervals with POST .../timeintervals:
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/timeintervals HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "notifications.alerting.grafana.app/v1beta1",
"kind": "TimeInterval",
"metadata": {
"name": "weekends",
"annotations": {
"grafana.com/provenance": "api"
}
},
"spec": {
"name": "Weekends",
"time_intervals": [
{
"weekdays": ["saturday", "sunday"],
"location": "UTC"
}
]
}
}Control editing in the Grafana UI (provenance)
In the /apis alerting endpoints, provenance is controlled per resource with the metadata.annotations["grafana.com/provenance"] annotation rather than the legacy X-Disable-Provenance HTTP header:
- Lock a resource from UI edits (provisioned): Set
"grafana.com/provenance": "api"inmetadata.annotations. Setting provenance requires provisioning RBAC permissions; refer to Configure RBAC for Grafana Alerting. - Allow editing in the Grafana UI: Omit
grafana.com/provenancefrommetadata.annotationswhen creating the resource. Resources created without this annotation remain editable in the Grafana UI.
To reset the default notification policy tree and unlock it for editing in the Grafana UI, send DELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees/user-defined.
Migrate from the legacy Alerting Provisioning API
If you currently use /api/v1/provisioning/* endpoints, refer to the following guides for endpoint mappings and schema differences:


