Skip to main content

​
Alerts API

The Alerts API provides endpoints for managing alert notification channels and receivers.

​
Get Alert Notifiers

Retrieve all available alert notification channel types. 
curl -X GET http://localhost:3000/api/alert-notifiers \
  -u admin:admin
​
version
string
Schema version (“2” for v2 schema)
​
type
string
Notification channel type identifier
​
name
string
Display name of the notification channel type
​
description
string
Description of the notification channel
​
options
array
Configuration options for this notification type
​
options[].name
string
Option field name
​
options[].label
string
Display label for the option
​
options[].kind
string
Data type: “string”, “boolean”, “number”, etc.
​
options[].required
boolean
Whether this option is required

​
Supported Notification Types

Grafana supports various notification channel types:

​
Email

Sends alert notifications via email. Required Options:
  • addresses: Comma-separated list of email addresses
Note: Requires SMTP server to be configured in Grafana.

​
Slack

Sends notifications to Slack channels or users. Required Options:
  • url: Slack incoming webhook URL
Optional Options:
  • channel: Slack channel or user (e.g., #alerts or @username)
  • username: Bot username to display
  • icon_emoji: Emoji to use as the bot icon

​
PagerDuty

Integrates with PagerDuty for incident management. Required Options:
  • integrationKey: PagerDuty integration key
Optional Options:
  • severity: Alert severity level
  • autoResolve: Automatically resolve incidents when alert resolves

​
Webhook

Sends HTTP POST requests to custom webhooks. Required Options:
  • url: Webhook URL endpoint
Optional Options:
  • httpMethod: HTTP method (POST, PUT)
  • username: Basic auth username
  • password: Basic auth password
  • authorization: Authorization header value

​
Microsoft Teams

Sends notifications to Microsoft Teams channels. Required Options:
  • url: Microsoft Teams webhook URL

​
OpsGenie

Integrates with OpsGenie for alert management. Required Options:
  • apiKey: OpsGenie API key
Optional Options:
  • autoClose: Automatically close alerts
  • overridePriority: Override alert priority

​
VictorOps

Integrates with VictorOps (now Splunk On-Call). Required Options:
  • url: VictorOps webhook URL

​
Pushover

Sends push notifications via Pushover. Required Options:
  • apiToken: Pushover API token
  • userKey: User or group key
Optional Options:
  • priority: Notification priority (-2 to 2)
  • sound: Notification sound

​
Alert Notification Schema

The notification schema defines the structure for configuring alert receivers.

​
Version 1 Schema (Legacy)

The v1 schema is used for backward compatibility with older alerting configurations.

​
Version 2 Schema

To retrieve the v2 schema, add ?version=2 to the request: 
curl -X GET "http://localhost:3000/api/alert-notifiers?version=2" \
  -u admin:admin
The v2 schema provides enhanced type information and validation rules for modern alerting configurations.

​
Unified Alerting

For Grafana v8.0+, the unified alerting system provides enhanced alert management features:
  • Alert Rules: Define alert conditions and evaluation rules
  • Contact Points: Configure notification destinations
  • Notification Policies: Route alerts to appropriate contact points
  • Silences: Temporarily mute notifications
Refer to the Unified Alerting documentation for API endpoints specific to unified alerting.

​
Examples

​
Email Notification Configuration

{
  "type": "email",
  "settings": {
    "addresses": "[email protected],[email protected]"
  }
}

​
Slack Notification Configuration

{
  "type": "slack",
  "settings": {
    "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX",
    "channel": "#alerts",
    "username": "Grafana"
  }
}

​
Webhook Notification Configuration

{
  "type": "webhook",
  "settings": {
    "url": "https://api.example.com/alerts",
    "httpMethod": "POST",
    "username": "grafana",
    "password": "secret"
  }
}

​
Permissions

Access to alert notification endpoints requires appropriate permissions:
  • Viewing notification types is available to all authenticated users
  • Creating and managing notification channels typically requires Editor or Admin role
  • Organization-level permissions may be required for managing org-wide notifications

Build docs developers (and LLMs) love

Get started for freeTalk to us