Alert notifications HTTP API
Note
Available in Grafana 13.0 and later.
This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.
The legacy Alerting Provisioning HTTP API is still available. Together with the Alert rules HTTP API, this API partially replaces it. Refer to Migrate from the legacy Alerting Provisioning API to learn how both APIs match.
This document may not contain the latest version of the API. For the most up-to-date list of available endpoints, refer to notifications.alerting.grafana.app/v1beta1 in Swagger.
This API is in
beta, so it might change in future releases.
Use this API to manage Grafana-managed alerting notification resources: contact points (Receiver), notification policy trees (RoutingTree), notification template groups (TemplateGroup), mute timings and active time intervals (TimeInterval), inhibition rules (InhibitionRule), and external Alertmanager sync settings (Config).
All paths use the notifications.alerting.grafana.app group and the v1beta1 version. Replace {namespace} with your namespace. To learn more about which namespace to use, refer to the
API overview. Grafana also serves v0alpha1 for backward compatibility; use v1beta1 for new integrations.
Before you begin
Before you begin, ensure you have the following:
- Grafana Alerting enabled: Grafana Alerting must be enabled on your instance.
- API authentication: Authenticate with a service account token or basic authentication (OSS and Enterprise). Refer to HTTP API authentication.
Requirements
By default, users with the Viewer basic role can read notification resources, and users with the Editor or Admin basic role can create, update, and delete them (updating the singleton Config resource requires the Admin role).
If you’re running Grafana Enterprise or Grafana Cloud and want to configure granular role-based access control (RBAC) permissions, including per-resource roles, scopes, and provenance permissions for grafana.com/provenance, refer to
Configure RBAC for Grafana Alerting.
Receivers (contact points)
A Receiver resource (receivers) represents a contact point and groups all of its notifier integrations (such as email, Slack, PagerDuty, or webhook) into a single object.
Schema
A Receiver resource contains the following fields in metadata and spec:
metadata.name: Optional on create (must be a lowercase DNS-compatible UID if supplied; otherwise Grafana generates one). Identifies the receiver in URL paths, whilespec.titleis the contact point name referenced by routing trees and alert rules.spec.title: Required. Display name of the contact point.spec.integrations: Required array of notifier integrations. Each item specifiestype(for example,email,slack,webhook),version(for example,1),settings, optionaldisableResolveMessage, optionaluid(assigned by Grafana), and read-onlysecureFieldsindicating which keys insettingsare stored encrypted.
Endpoints
The following table lists the main endpoints for Receiver resources. For PATCH, collection DELETE, and POST /receivers/search, refer to Swagger.
List receivers
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers
Lists all Receiver resources in the namespace that you have permission to read.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
The following example lists receivers in the namespace:
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/receivers HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with a ReceiverList object containing Receiver items in items.
Status codes
- 200:
OK - 401: Unauthorized
- 403: Access denied
Get a receiver
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{name}
Retrieves a Receiver resource by metadata.name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the receiver.
Example request
The following example gets a receiver:
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/receivers/oncall-webhook HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the Receiver object shown in Create a receiver.
Status codes
- 200: Found
- 401: Unauthorized
- 403: Access denied
- 404: Receiver not found
Create a receiver
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers
Creates a contact point with all of its notifier integrations.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
The following example creates a contact point with a webhook integration:
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"
},
"spec": {
"title": "On-call webhook",
"integrations": [
{
"type": "webhook",
"version": "1",
"disableResolveMessage": false,
"settings": {
"url": "https://example.com/alerts/webhook",
"httpMethod": "POST"
}
}
]
}
}Replace <SERVICE_ACCOUNT_TOKEN> with a token that has contact point create permissions.
Example response
The following example shows the response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"kind": "Receiver",
"apiVersion": "notifications.alerting.grafana.app/v1beta1",
"metadata": {
"name": "oncall-webhook",
"namespace": "default",
"uid": "7f3a9d2e-1b4c-4e8a-9c0d-2f4b6e8a0c12",
"resourceVersion": "a1b2c3d4e5f60718"
},
"spec": {
"title": "On-call webhook",
"integrations": [
{
"uid": "d9e8f7a6b5c4",
"type": "webhook",
"version": "1",
"disableResolveMessage": false,
"settings": {
"url": "https://example.com/alerts/webhook",
"httpMethod": "POST"
}
}
]
}
}Status codes
- 201: Created
- 400: Bad request (invalid JSON, invalid resource name, or invalid integration settings)
- 401: Unauthorized
- 403: Access denied (missing RBAC permission or provenance permission)
- 409: Conflict (a receiver with the same
metadata.nameorspec.titlealready exists) - 422: Schema validation error
Update a receiver
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{name}
Replaces an existing Receiver resource. Include metadata.resourceVersion from the latest version you read, or use PATCH for partial updates.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the receiver.
Example request
The following example updates a receiver:
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/receivers/oncall-webhook 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",
"resourceVersion": "a1b2c3d4e5f60718"
},
"spec": {
"title": "On-call webhook",
"integrations": [
{
"uid": "d9e8f7a6b5c4",
"type": "webhook",
"version": "1",
"disableResolveMessage": true,
"settings": {
"url": "https://example.com/alerts/webhook",
"httpMethod": "POST"
}
}
]
}
}Example response
The response returns 200 OK with the updated Receiver object and a new metadata.resourceVersion.
Status codes
- 200: Updated
- 400: Bad request (invalid JSON or invalid integration settings)
- 401: Unauthorized
- 403: Access denied
- 404: Receiver not found
- 409: Conflict (
metadata.resourceVersionmismatch) - 422: Schema validation error
Delete a receiver
DELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{name}
Deletes a Receiver resource by metadata.name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the receiver.
Example request
The following example deletes a receiver:
DELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/receivers/oncall-webhook HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the deleted Receiver object (or a Status object).
Status codes
- 200: Deleted
- 401: Unauthorized
- 403: Access denied
- 404: Receiver not found
- 409: Conflict (the receiver is still referenced by a notification policy or alert rule)
Test a receiver integration
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{name}/test
Sends a test alert notification through one integration. Pass an existing receiver’s metadata.name as {name} to test a saved integration (referencing integration.uid if reusing stored secrets), or pass - as {name} to test a new integration before saving it.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Receivermetadata.name, or-for an unsaved receiver.
Example request
The following example tests an unsaved webhook integration:
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/receivers/-/test HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"integration": {
"type": "webhook",
"version": "1",
"settings": {
"url": "https://example.com/alerts/webhook"
}
},
"alert": {
"labels": {
"alertname": "TestAlert",
"severity": "warning"
},
"annotations": {
"summary": "Test notification"
}
}
}Example response
The following example shows the response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success",
"duration": 124
}Status codes
- 200:
OK(checkstatusin the response body for deliverysuccessorfailure) - 400: Bad request (invalid integration configuration)
- 401: Unauthorized
- 403: Access denied
- 404: Receiver not found
List integration type schemas
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/integrationtypeschemas
Returns the notifier integration type values, versions, and settings field definitions supported on your Grafana instance.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
The following example lists integration type schemas:
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/integrationtypeschemas HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with an items array containing schema definitions for each integration type.
Status codes
- 200:
OK - 401: Unauthorized
- 403: Access denied
Details
- Name vs. title: URL paths address a contact point by
metadata.name(its UID), whereas routing trees and alert rulenotificationSettings.receiverreference the contact point byspec.title. - Encrypted fields: Secret settings (such as webhook tokens or API keys) aren’t returned in plain text on
GETunless the caller has secret-reading permissions; instead,secureFieldsmarks which keys are stored encrypted.
Routing trees (notification policies)
A RoutingTree resource (routingtrees) defines a notification policy tree that routes firing alerts to contact points.
Schema
A RoutingTree resource contains the following fields in spec:
spec.defaults: Required root route defaults, withreceiver(contact pointspec.title) and optionalgroup_by,group_wait,group_interval, andrepeat_interval.spec.routes: Array of child policies. Each child policy specifiescontinue(trueorfalse), optionalreceiver,matchers(label,type,value, wheretypeis=,!=,=~, or!~),group_by,mute_time_intervals,active_time_intervals,group_wait,group_interval,repeat_interval, and nestedroutes.
Endpoints
The following table lists the main endpoints for RoutingTree resources. For PATCH, collection DELETE, and POST /routingtrees/search, refer to Swagger.
List routing trees
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees
Lists the default routing tree (user-defined) and any named routing trees in the namespace.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/routingtrees HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with a RoutingTreeList object containing RoutingTree items in items.
Status codes
- 200:
OK - 401: Unauthorized
- 403: Access denied
Get a routing tree
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees/{name}
Retrieves a RoutingTree resource by metadata.name (use user-defined or default for the default policy tree).
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}:user-defined(ordefault) for the default tree, or themetadata.nameof a named routing tree.
Example request
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/routingtrees/user-defined HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the RoutingTree object.
Status codes
- 200: Found
- 401: Unauthorized
- 403: Access denied
- 404: Routing tree not found
Create a named routing tree
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees
Creates an additional named RoutingTree resource that alert rules can target with notificationSettings.type: "NamedRoutingTree".
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/routingtrees 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": "platform-routing"
},
"spec": {
"defaults": {
"receiver": "On-call webhook",
"group_by": ["grafana_folder", "alertname"]
},
"routes": []
}
}Example response
The response returns 201 Created with the created RoutingTree object.
Status codes
- 201: Created
- 400: Bad request (invalid JSON, reserved name, or invalid route configuration)
- 401: Unauthorized
- 403: Access denied
- 409: Conflict (a routing tree with the same
metadata.namealready exists) - 422: Schema validation error
Update a routing tree
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees/{name}
Replaces the default routing tree (user-defined) or a named routing tree. Retrieve the current RoutingTree first and include its metadata.resourceVersion.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}:user-defined(ordefault) for the default tree, or themetadata.nameof a named routing tree.
Example request
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>"
},
"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,
"matchers": [
{
"label": "severity",
"type": "=",
"value": "critical"
}
]
}
]
}
}Replace <RESOURCE_VERSION> with the metadata.resourceVersion from GET .../routingtrees/user-defined, and replace <SERVICE_ACCOUNT_TOKEN> with your token.
Example response
On success, Grafana returns 200 OK with the updated RoutingTree object.
Status codes
- 200: Updated
- 400: Bad request (invalid JSON or invalid route configuration)
- 401: Unauthorized
- 403: Access denied
- 404: Routing tree not found
- 409: Conflict (
metadata.resourceVersionmismatch) - 422: Schema validation error
Delete a routing tree
DELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees/{name}
Resets the default routing tree (user-defined) to the instance defaults, or deletes a named routing tree.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}:user-defined(ordefault) for the default tree, or themetadata.nameof a named routing tree.
Example request
DELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/routingtrees/platform-routing HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the deleted (or reset) RoutingTree object.
Status codes
- 200: Deleted (or reset, for
user-defined) - 401: Unauthorized
- 403: Access denied
- 404: Routing tree not found
- 409: Conflict (the named routing tree is still referenced by an alert rule)
Details
Every organization has a default notification policy tree addressed by metadata.name set to user-defined (Grafana also accepts default as an alias in requests). Both user-defined and default are reserved and can’t be used as custom names when creating named routing trees with POST /routingtrees.
Template groups
A TemplateGroup resource (templategroups) stores reusable Go notification templates referenced by contact point integrations.
Schema
A TemplateGroup resource contains the following fields in spec:
spec.title: Required. Display name of the template group.spec.content: Required. Notification template definitions in Go template syntax ({{ define "..." }}...{{ end }}).spec.kind: Required. Template kind:grafana(default) ormimir.
Endpoints
The following table lists the main endpoints for TemplateGroup resources. For PATCH, collection DELETE, and POST /templategroups/search, refer to Swagger.
List template groups
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups
Lists all TemplateGroup resources in the namespace.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/templategroups HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with a TemplateGroupList object containing TemplateGroup items in items.
Status codes
- 200:
OK - 401: Unauthorized
- 403: Access denied
Get a template group
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups/{name}
Retrieves a TemplateGroup resource by metadata.name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the template group.
Example request
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/templategroups/slack-summary HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the TemplateGroup object.
Status codes
- 200: Found
- 401: Unauthorized
- 403: Access denied
- 404: Template group not found
Create a template group
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups
Creates a TemplateGroup resource.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/templategroups HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "notifications.alerting.grafana.app/v1beta1",
"kind": "TemplateGroup",
"metadata": {
"name": "slack-summary"
},
"spec": {
"title": "slack-summary",
"kind": "grafana",
"content": "{{ define \"slack.summary\" }}[{{ .Status | toUpper }}] {{ .CommonLabels.alertname }}{{ end }}"
}
}Example response
The response returns 201 Created with the created TemplateGroup object.
Status codes
- 201: Created
- 400: Bad request (invalid JSON or invalid Go template syntax)
- 401: Unauthorized
- 403: Access denied
- 409: Conflict (a template group with the same
metadata.namealready exists) - 422: Schema validation error
Update a template group
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups/{name}
Replaces an existing TemplateGroup resource. Include metadata.resourceVersion from the latest version you read.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the template group.
Example request
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/templategroups/slack-summary HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "notifications.alerting.grafana.app/v1beta1",
"kind": "TemplateGroup",
"metadata": {
"name": "slack-summary",
"resourceVersion": "<RESOURCE_VERSION>"
},
"spec": {
"title": "slack-summary",
"kind": "grafana",
"content": "{{ define \"slack.summary\" }}[{{ .Status | toUpper }}] {{ .CommonLabels.alertname }} ({{ .CommonLabels.severity }}){{ end }}"
}
}Example response
The response returns 200 OK with the updated TemplateGroup object.
Status codes
- 200: Updated
- 400: Bad request (invalid JSON or invalid Go template syntax)
- 401: Unauthorized
- 403: Access denied
- 404: Template group not found
- 409: Conflict (
metadata.resourceVersionmismatch) - 422: Schema validation error
Delete a template group
DELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups/{name}
Deletes a TemplateGroup resource by metadata.name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the template group.
Example request
DELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/templategroups/slack-summary HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the deleted TemplateGroup object (or a Status object).
Status codes
- 200: Deleted
- 401: Unauthorized
- 403: Access denied
- 404: Template group not found
Details
Named templates defined with {{ define "..." }} inside spec.content can be referenced across contact point integrations in the same namespace.
Time intervals (mute timings)
A TimeInterval resource (timeintervals) defines recurring schedules that you can reference as mute timings or active time intervals.
Schema
A TimeInterval resource contains the following fields in spec:
spec.name: Required. Schedule name referenced bymute_time_intervalsandactive_time_intervalsin routing trees and alert rules.spec.time_intervals: Required array of schedule entries. Each entry can specifytimes(start_timeandend_timeinHH:MM),weekdays(for example,saturday,sunday, ormonday:friday),days_of_month,months,years, and IANAlocation(for example,UTCorAmerica/New_York).
Endpoints
The following table lists the main endpoints for TimeInterval resources. For PATCH, collection DELETE, and POST /timeintervals/search, refer to Swagger.
List time intervals
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals
Lists all TimeInterval resources in the namespace.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/timeintervals HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with a TimeIntervalList object containing TimeInterval items in items.
Status codes
- 200:
OK - 401: Unauthorized
- 403: Access denied
Get a time interval
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals/{name}
Retrieves a TimeInterval resource by metadata.name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the time interval.
Example request
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/timeintervals/weekends HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the TimeInterval object.
Status codes
- 200: Found
- 401: Unauthorized
- 403: Access denied
- 404: Time interval not found
Create a time interval
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals
Creates a TimeInterval resource.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
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"
},
"spec": {
"name": "Weekends",
"time_intervals": [
{
"weekdays": ["saturday", "sunday"],
"location": "UTC"
}
]
}
}Example response
The response returns 201 Created with the created TimeInterval object.
Status codes
- 201: Created
- 400: Bad request (invalid JSON or invalid schedule syntax)
- 401: Unauthorized
- 403: Access denied
- 409: Conflict (a time interval with the same
metadata.nameorspec.namealready exists) - 422: Schema validation error
Update a time interval
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals/{name}
Replaces an existing TimeInterval resource. Include metadata.resourceVersion from the latest version you read.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the time interval.
Example request
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/timeintervals/weekends 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",
"resourceVersion": "<RESOURCE_VERSION>"
},
"spec": {
"name": "Weekends",
"time_intervals": [
{
"weekdays": ["saturday", "sunday"],
"location": "Europe/London"
}
]
}
}Example response
The response returns 200 OK with the updated TimeInterval object.
Status codes
- 200: Updated
- 400: Bad request (invalid JSON or invalid schedule syntax)
- 401: Unauthorized
- 403: Access denied
- 404: Time interval not found
- 409: Conflict (
metadata.resourceVersionmismatch) - 422: Schema validation error
Delete a time interval
DELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals/{name}
Deletes a TimeInterval resource by metadata.name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the time interval.
Example request
DELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/timeintervals/weekends HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the deleted TimeInterval object (or a Status object).
Status codes
- 200: Deleted
- 401: Unauthorized
- 403: Access denied
- 404: Time interval not found
- 409: Conflict (the time interval is still referenced by a routing tree or alert rule)
Details
Deleting a TimeInterval that is still referenced in mute_time_intervals or active_time_intervals on a routing tree or alert rule returns 409 Conflict.
Inhibition rules
An InhibitionRule resource (inhibitionrules) suppresses notifications for target alerts while a matching source alert is firing.
Schema
An InhibitionRule resource contains the following fields in spec:
spec.source_matchers: Optional array of matchers (label,type,value, wheretypeis=,!=,=~, or!~) identifying firing alerts that inhibit other alerts.spec.target_matchers: Optional array of matchers identifying alerts to suppress.spec.equal: Optional array of label names that must have identical values on both the source and target alerts for inhibition to apply.
Endpoints
The following table lists the main endpoints for InhibitionRule resources. For PATCH, collection DELETE, and POST /inhibitionrules/search, refer to Swagger.
List inhibition rules
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules
Lists all InhibitionRule resources in the namespace.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/inhibitionrules HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with an InhibitionRuleList object containing InhibitionRule items in items.
Status codes
- 200:
OK - 401: Unauthorized
- 403: Access denied
Get an inhibition rule
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules/{name}
Retrieves an InhibitionRule resource by metadata.name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the inhibition rule.
Example request
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/inhibitionrules/840967b51b1bbda8 HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the InhibitionRule object.
Status codes
- 200: Found
- 401: Unauthorized
- 403: Access denied
- 404: Inhibition rule not found
Create an inhibition rule
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules
Creates an InhibitionRule resource.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
POST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/inhibitionrules HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "notifications.alerting.grafana.app/v1beta1",
"kind": "InhibitionRule",
"spec": {
"source_matchers": [
{
"label": "severity",
"type": "=",
"value": "critical"
}
],
"target_matchers": [
{
"label": "severity",
"type": "=",
"value": "warning"
}
],
"equal": ["cluster"]
}
}Example response
The response returns 201 Created with the created InhibitionRule object and its generated metadata.name.
Status codes
- 201: Created
- 400: Bad request (invalid JSON or invalid matcher syntax)
- 401: Unauthorized
- 403: Access denied
- 409: Conflict (an inhibition rule with the same
metadata.namealready exists) - 422: Schema validation error
Update an inhibition rule
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules/{name}
Replaces an existing InhibitionRule resource. Include metadata.resourceVersion from the latest version you read.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the inhibition rule.
Example request
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/inhibitionrules/840967b51b1bbda8 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "notifications.alerting.grafana.app/v1beta1",
"kind": "InhibitionRule",
"metadata": {
"name": "840967b51b1bbda8",
"resourceVersion": "<RESOURCE_VERSION>"
},
"spec": {
"source_matchers": [
{
"label": "severity",
"type": "=",
"value": "critical"
}
],
"target_matchers": [
{
"label": "severity",
"type": "=",
"value": "warning"
}
],
"equal": ["cluster", "namespace"]
}
}Example response
The response returns 200 OK with the updated InhibitionRule object.
Status codes
- 200: Updated
- 400: Bad request (invalid JSON or invalid matcher syntax)
- 401: Unauthorized
- 403: Access denied
- 404: Inhibition rule not found
- 409: Conflict (
metadata.resourceVersionmismatch) - 422: Schema validation error
Delete an inhibition rule
DELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules/{name}
Deletes an InhibitionRule resource by metadata.name.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: Themetadata.nameof the inhibition rule.
Example request
DELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/inhibitionrules/840967b51b1bbda8 HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the deleted InhibitionRule object (or a Status object).
Status codes
- 200: Deleted
- 401: Unauthorized
- 403: Access denied
- 404: Inhibition rule not found
Details
Both source and target alerts must share equal values for every label listed in spec.equal before Grafana suppresses notifications for the target alert.
Alertmanager sync configuration
The Config resource (configs) is a per-organization singleton (metadata.name: "default") for administrative notification settings.
Schema
A Config resource contains the following fields in spec and status:
spec.externalAlertmanagerSync.datasourceUid: Optional UID of a Mimir or Cortex Alertmanager data source to periodically sync Alertmanager configuration from. Empty disables sync.status.conditions: Read-only Kubernetes-style conditions (such asExternalAlertmanagerSynced) reporting sync health.status.externalAlertmanagerSync: Read-only observation of the last sync run (datasourceUid,originset toapiorini, and imported routing treeidentifier).
Endpoints
The following table lists the main endpoints for the singleton Config resource. For PATCH and /status endpoints, refer to Swagger.
Get external Alertmanager sync configuration
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/configs/default
Retrieves the organization’s Config singleton, including current sync status in status.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
GET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/configs/default HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The response returns 200 OK with the Config singleton object.
Status codes
- 200: Found
- 401: Unauthorized
- 403: Access denied
- 404: Singleton configuration not yet initialized
Update external Alertmanager sync configuration
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/configs/default
Updates spec.externalAlertmanagerSync.datasourceUid on the default Config singleton (you can also use PATCH). Users can’t create other Config names with POST or delete configs/default with DELETE.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Example request
PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/default/configs/default HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"apiVersion": "notifications.alerting.grafana.app/v1beta1",
"kind": "Config",
"metadata": {
"name": "default",
"resourceVersion": "<RESOURCE_VERSION>"
},
"spec": {
"externalAlertmanagerSync": {
"datasourceUid": "<ALERTMANAGER_DATASOURCE_UID>"
}
}
}Example response
The response returns 200 OK with the updated Config singleton object.
Status codes
- 200: Updated
- 400: Bad request (feature toggle disabled, operator
grafana.inioverride set, or ineligible data source) - 401: Unauthorized
- 403: Access denied
- 404: Data source or configuration not found
- 409: Conflict (
metadata.resourceVersionmismatch)
Details
Updating spec.externalAlertmanagerSync.datasourceUid requires the alertingSyncExternalAlertmanager feature toggle to be enabled and the unified_alerting.external_alertmanager_uid setting in grafana.ini to be unset (when set in grafana.ini, the operator override takes precedence and API writes are rejected).
Migrate from the legacy Alerting Provisioning API
Together with the Alert rules HTTP API, this API partially replaces the legacy Alerting Provisioning HTTP API. Specifically, this API replaces the contact points, notification policies, template groups, and mute timings CRUD endpoints, and adds support for staged Alertmanager configurations, named routing trees, inhibition rules, and receiver testing.
The following table shows how the legacy notification endpoints map to notifications.alerting.grafana.app/v1beta1:
When you migrate, consider the following differences:
- Contact point structure: The legacy API creates or updates one
EmbeddedContactPointintegration per request and groups integrations that share the samename. Innotifications.alerting.grafana.app/v1beta1, aReceiverresource contains all of the contact point’s integrations inspec.integrations, addressed by the contact point’smetadata.name. - Staged Alertmanager configurations: Unlike the legacy provisioning endpoints, this API returns and manages resources from staged Alertmanager configurations (such as imported Alertmanager configurations).
- Routing trees: The root notification policy is the
user-definedRoutingTreeresource (withdefaultaccepted as an alias), and you can also manage separate named routing trees. - Provenance: Instead of sending the
X-Disable-Provenancerequest header, setmetadata.annotations["grafana.com/provenance"]to"api"when you want a resource locked from UI edits. - Alert rules: Alert rules and recording rules are managed through the Alert rules HTTP API.
Related resources
Use the following resources to keep working with Grafana Alerting APIs:
- Alert rules HTTP API: Refer to Alert rules HTTP API.
- Alert enrichment HTTP API: Refer to Alert enrichment HTTP API.
- Configure notifications: Refer to Configure notifications.
- API structure: Refer to API structure in Grafana.


