Enterprise Open source Grafana Cloud

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).

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, while spec.title is 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 specifies type (for example, email, slack, webhook), version (for example, 1), settings, optional disableResolveMessage, optional uid (assigned by Grafana), and read-only secureFields indicating which keys in settings are stored encrypted.

Endpoints

The following table lists the main endpoints for Receiver resources. For PATCH, collection DELETE, and POST /receivers/search, refer to Swagger.

Base path: /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/

Replace {namespace} with your namespace. To learn which namespace to use, refer to the API overview.

MethodSummaryPath
GETList receiversreceivers
GETGet a receiverreceivers/{name}
POSTCreate a receiverreceivers
PUTUpdate a receiverreceivers/{name}
DELETEDelete a receiverreceivers/{name}
POSTTest a receiver integrationreceivers/{name}/test
GETList integration type schemasintegrationtypeschemas

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:

http
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.

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}: The metadata.name of the receiver.
Example request

The following example gets a receiver:

http
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.

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:

http
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
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"
        }
      }
    ]
  }
}

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}: The metadata.name of the receiver.
Example request

The following example updates a receiver:

http
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.

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}: The metadata.name of the receiver.
Example request

The following example deletes a receiver:

http
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).

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}: Receiver metadata.name, or - for an unsaved receiver.
Example request

The following example tests an unsaved webhook integration:

http
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
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "duration": 124
}

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:

http
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.

Details

  • Name vs. title: URL paths address a contact point by metadata.name (its UID), whereas routing trees and alert rule notificationSettings.receiver reference the contact point by spec.title.
  • Encrypted fields: Secret settings (such as webhook tokens or API keys) aren’t returned in plain text on GET unless the caller has secret-reading permissions; instead, secureFields marks 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, with receiver (contact point spec.title) and optional group_by, group_wait, group_interval, and repeat_interval.
  • spec.routes: Array of child policies. Each child policy specifies continue (true or false), optional receiver, matchers (label, type, value, where type is =, !=, =~, or !~), group_by, mute_time_intervals, active_time_intervals, group_wait, group_interval, repeat_interval, and nested routes.

Endpoints

The following table lists the main endpoints for RoutingTree resources. For PATCH, collection DELETE, and POST /routingtrees/search, refer to Swagger.

Base path: /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/

MethodSummaryPath
GETList routing treesroutingtrees
GETGet a routing treeroutingtrees/{name}
POSTCreate a named routing treeroutingtrees
PUTUpdate a routing treeroutingtrees/{name}
DELETEDelete a routing treeroutingtrees/{name}

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
http
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.

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 (or default) for the default tree, or the metadata.name of a named routing tree.
Example request
http
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.

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
http
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.

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 (or default) for the default tree, or the metadata.name of a named routing tree.
Example request
http
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.

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 (or default) for the default tree, or the metadata.name of a named routing tree.
Example request
http
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.

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) or mimir.

Endpoints

The following table lists the main endpoints for TemplateGroup resources. For PATCH, collection DELETE, and POST /templategroups/search, refer to Swagger.

Base path: /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/

MethodSummaryPath
GETList template groupstemplategroups
GETGet a template grouptemplategroups/{name}
POSTCreate a template grouptemplategroups
PUTUpdate a template grouptemplategroups/{name}
DELETEDelete a template grouptemplategroups/{name}

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
http
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.

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}: The metadata.name of the template group.
Example request
http
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.

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
http
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.

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}: The metadata.name of the template group.
Example request
http
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.

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}: The metadata.name of the template group.
Example request
http
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).

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 by mute_time_intervals and active_time_intervals in routing trees and alert rules.
  • spec.time_intervals: Required array of schedule entries. Each entry can specify times (start_time and end_time in HH:MM), weekdays (for example, saturday, sunday, or monday:friday), days_of_month, months, years, and IANA location (for example, UTC or America/New_York).

Endpoints

The following table lists the main endpoints for TimeInterval resources. For PATCH, collection DELETE, and POST /timeintervals/search, refer to Swagger.

Base path: /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/

MethodSummaryPath
GETList time intervalstimeintervals
GETGet a time intervaltimeintervals/{name}
POSTCreate a time intervaltimeintervals
PUTUpdate a time intervaltimeintervals/{name}
DELETEDelete a time intervaltimeintervals/{name}

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
http
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.

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}: The metadata.name of the time interval.
Example request
http
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.

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
http
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.

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}: The metadata.name of the time interval.
Example request
http
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.

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}: The metadata.name of the time interval.
Example request
http
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).

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 requires a metadata.name, which must be a valid DNS subdomain name, and contains the following fields in spec:

  • spec.source_matchers: Required array of at least one matcher (label, type, value, where type is =, !=, =~, or !~) identifying firing alerts that inhibit other alerts.
  • spec.target_matchers: Required array of at least one matcher 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.

Base path: /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/

MethodSummaryPath
GETList inhibition rulesinhibitionrules
GETGet an inhibition ruleinhibitionrules/{name}
POSTCreate an inhibition ruleinhibitionrules
PUTUpdate an inhibition ruleinhibitionrules/{name}
DELETEDelete an inhibition ruleinhibitionrules/{name}

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
http
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.

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}: The metadata.name of the inhibition rule.
Example request
http
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.

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
http
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",
  "metadata": {
    "name": "critical-inhibits-warning"
  },
  "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.

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}: The metadata.name of the inhibition rule.
Example request
http
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.

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}: The metadata.name of the inhibition rule.
Example request
http
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).

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 as ExternalAlertmanagerSynced) reporting sync health.
  • status.externalAlertmanagerSync: Read-only observation of the last sync run (datasourceUid, origin set to api or ini, and imported routing tree identifier).

Endpoints

The following table lists the main endpoints for the singleton Config resource. For PATCH and /status endpoints, refer to Swagger.

Base path: /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/

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
http
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.

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
http
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.

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).

Status codes

The following sections list the status codes that the endpoints on this page return, by resource.

Receivers (contact points)

The endpoints for receivers return the following status codes:

CodeMeaningReturned by
200OK.List receivers, Get, Update, Delete, List integration type schemas
200OK (check status in the response body for delivery success or failure).Test
201Created.Create
400Bad request (invalid JSON, invalid resource name, or invalid integration settings).Create
400Bad request (invalid JSON, invalid integration settings, spec.title already used by another receiver, or the receiver belongs to an imported Alertmanager configuration).Update
400Bad request (the receiver belongs to an imported Alertmanager configuration).Delete
400Bad request (invalid integration configuration).Test
401Unauthorized.All endpoints
403Access denied.List receivers, Get, Update, Delete, Test, List integration type schemas
403Access denied (missing RBAC permission or provenance permission).Create
404Receiver not found.Get, Update, Delete
404Receiver or integration not found.Test
409Conflict (a receiver with the same metadata.name or spec.title already exists).Create
409Conflict (metadata.resourceVersion doesn’t match the stored version, or you rename a receiver that provisioned resources reference).Update
409Conflict (the receiver is still referenced by a notification policy or alert rule, or the resourceVersion precondition doesn’t match).Delete

Routing trees (notification policies)

The endpoints for routing trees return the following status codes:

CodeMeaningReturned by
200OK.List, Get, Update
200Deleted (or reset, for user-defined).Delete
201Created.Create
400Bad request (invalid JSON, invalid name, or invalid route configuration).Create
400Bad request (invalid JSON, invalid route configuration, or the routing tree belongs to an imported Alertmanager configuration).Update
400Bad request (the routing tree belongs to an imported Alertmanager configuration).Delete
401Unauthorized.All endpoints
403Access denied.All endpoints
404Routing tree not found.Get, Update, Delete
409Conflict (a routing tree with the same metadata.name already exists, the name is reserved, such as user-defined, or it conflicts with an imported routing tree).Create
409Conflict (metadata.resourceVersion doesn’t match the stored version).Update
409Conflict (the resourceVersion precondition doesn’t match).Delete

Template groups

The endpoints for template groups return the following status codes:

CodeMeaningReturned by
200OK.List, Get, Update, Delete
201Created.Create
400Bad request (invalid JSON, invalid name, invalid Go template syntax, or a template group with the same spec.title already exists).Create
400Bad request (invalid JSON, invalid Go template syntax, spec.title already used by another template group, or the template group belongs to an imported Alertmanager configuration).Update
400Bad request (the template group belongs to an imported Alertmanager configuration).Delete
401Unauthorized.All endpoints
403Access denied.All endpoints
404Template group not found.Get, Update, Delete
409Conflict (a template group with the same metadata.name already exists).Create
409Conflict (metadata.resourceVersion doesn’t match the stored version).Update
409Conflict (the resourceVersion precondition doesn’t match).Delete

Time intervals (mute timings)

The endpoints for time intervals return the following status codes:

CodeMeaningReturned by
200OK.List, Get, Update, Delete
201Created.Create
400Bad request (invalid JSON, invalid schedule syntax, or a time interval with the same spec.name already exists).Create
400Bad request (invalid JSON, invalid schedule syntax, spec.name already used by another time interval, or the time interval belongs to an imported Alertmanager configuration).Update
400Bad request (the time interval belongs to an imported Alertmanager configuration).Delete
401Unauthorized.All endpoints
403Access denied.All endpoints
404Time interval not found.Get, Update, Delete
409Conflict (a time interval with the same metadata.name already exists).Create
409Conflict (metadata.resourceVersion doesn’t match the stored version, or you rename a time interval that provisioned resources reference).Update
409Conflict (the time interval is still referenced by a routing tree or alert rule, or the resourceVersion precondition doesn’t match).Delete

Inhibition rules

The endpoints for inhibition rules return the following status codes:

CodeMeaningReturned by
200OK.List, Get, Update, Delete
201Created.Create
400Bad request (invalid JSON, missing or invalid metadata.name, missing source_matchers or target_matchers, invalid matcher syntax, or an inhibition rule with the same metadata.name already exists).Create
400Bad request (invalid JSON, missing source_matchers or target_matchers, invalid matcher syntax, or the inhibition rule belongs to an imported Alertmanager configuration).Update
400Bad request (the inhibition rule belongs to an imported Alertmanager configuration).Delete
401Unauthorized.All endpoints
403Access denied.All endpoints
404Inhibition rule not found.Get, Update, Delete
409Conflict (metadata.resourceVersion doesn’t match the stored version).Update
409Conflict (the resourceVersion precondition doesn’t match).Delete

Alertmanager sync configuration

The endpoints for Alertmanager sync configuration return the following status codes:

CodeMeaningReturned by
200OK.All endpoints
401Unauthorized.All endpoints
403Access denied.Get
403Access denied, or the update is rejected (feature toggle disabled, operator grafana.ini override set, data source not found or ineligible, or the configuration isn’t initialized yet).Update
404Singleton configuration not yet initialized.Get
409Conflict (metadata.resourceVersion doesn’t match the stored version).Update

You can’t create or delete the configuration with POST or DELETE. These requests return 403 for all users.

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:

Legacy endpointNew endpoint
GET /api/v1/provisioning/contact-pointsGET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers
POST /api/v1/provisioning/contact-pointsPOST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers
PUT /api/v1/provisioning/contact-points/:uidPUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{name}
DELETE /api/v1/provisioning/contact-points/:uidDELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{name}
GET /api/v1/provisioning/policiesGET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees/user-defined
PUT /api/v1/provisioning/policiesPUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees/user-defined
DELETE /api/v1/provisioning/policiesDELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees/user-defined
GET /api/v1/provisioning/templatesGET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups
GET /api/v1/provisioning/templates/:nameGET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups/{name}
PUT /api/v1/provisioning/templates/:namePOST or PUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups/{name}
DELETE /api/v1/provisioning/templates/:nameDELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups/{name}
GET /api/v1/provisioning/mute-timingsGET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals
GET /api/v1/provisioning/mute-timings/:nameGET /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals/{name}
POST /api/v1/provisioning/mute-timingsPOST /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals
PUT /api/v1/provisioning/mute-timings/:namePUT /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals/{name}
DELETE /api/v1/provisioning/mute-timings/:nameDELETE /apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals/{name}
GET /api/v1/provisioning/*/exportNo equivalent in this API; file-provisioning export remains on the legacy API
POST /api/access-control/receivers/:uid/*No equivalent in this API; receiver access-control permissions remain on /api/access-control/receivers/*

When you migrate, consider the following differences:

  • Contact point structure: The legacy API creates or updates one EmbeddedContactPoint integration per request and groups integrations that share the same name. In notifications.alerting.grafana.app/v1beta1, a Receiver resource contains all of the contact point’s integrations in spec.integrations, addressed by the contact point’s metadata.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-defined RoutingTree resource (with default accepted as an alias), and you can also manage separate named routing trees.
  • Provenance: Instead of sending the X-Disable-Provenance request header, set metadata.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.

Use the following resources to keep working with Grafana Alerting APIs: