This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

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

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

MethodSummaryURI
GETList receivers/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers
GETGet a receiver/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{name}
POSTCreate a receiver/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers
PUTUpdate a receiver/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{name}
DELETEDelete a receiver/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{name}
POSTTest a receiver integration/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/receivers/{name}/test
GETList integration type schemas/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/integrationtypeschemas

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.

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}: 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.

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:

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"
        }
      }
    ]
  }
}
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.name or spec.title already 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}: 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.

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.resourceVersion mismatch)
  • 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}: 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).

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}: 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
}
Status codes
  • 200: OK (check status in the response body for delivery success or failure)
  • 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:

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.

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

MethodSummaryURI
GETList routing trees/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees
GETGet a routing tree/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees/{name}
POSTCreate a named routing tree/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees
PUTUpdate a routing tree/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees/{name}
DELETEDelete a routing tree/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/routingtrees/{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.

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

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

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.name already 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 (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.

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.resourceVersion mismatch)
  • 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 (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.

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

Endpoints

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

MethodSummaryURI
GETList template groups/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups
GETGet a template group/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups/{name}
POSTCreate a template group/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups
PUTUpdate a template group/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups/{name}
DELETEDelete a template group/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/templategroups/{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.

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}: 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.

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

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.name already 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}: 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.

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.resourceVersion mismatch)
  • 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}: 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).

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

MethodSummaryURI
GETList time intervals/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals
GETGet a time interval/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals/{name}
POSTCreate a time interval/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals
PUTUpdate a time interval/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals/{name}
DELETEDelete a time interval/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/timeintervals/{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.

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}: 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.

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

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.name or spec.name already 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}: 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.

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.resourceVersion mismatch)
  • 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}: 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).

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, where type is =, !=, =~, 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.

MethodSummaryURI
GETList inhibition rules/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules
GETGet an inhibition rule/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules/{name}
POSTCreate an inhibition rule/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules
PUTUpdate an inhibition rule/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules/{name}
DELETEDelete an inhibition rule/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/inhibitionrules/{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.

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}: 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.

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
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",
  "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.name already 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}: 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.

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.resourceVersion mismatch)
  • 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}: 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).

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

MethodSummaryURI
GETGet external Alertmanager sync configuration/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/configs/default
PUTUpdate external Alertmanager sync configuration/apis/notifications.alerting.grafana.app/v1beta1/namespaces/{namespace}/configs/default

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.

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

Status codes
  • 200: Updated
  • 400: Bad request (feature toggle disabled, operator grafana.ini override set, or ineligible data source)
  • 401: Unauthorized
  • 403: Access denied
  • 404: Data source or configuration not found
  • 409: Conflict (metadata.resourceVersion mismatch)

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:

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: