Alerting Notification Channels API

This page documents the Alerting Notification Channels API.

Identifier (id) vs unique identifier (uid)

The identifier (id) of a notification channel is an auto-incrementing numeric value and is only unique per Grafana install.

The unique identifier (uid) of a notification channel can be used for uniquely identify a notification channel between multiple Grafana installs. It’s automatically generated if not provided when creating a notification channel. The uid allows having consistent URLs for accessing notification channels and when syncing notification channels between multiple Grafana installations, refer to alert notification channel provisioning.

The uid can have a maximum length of 40 characters.

Get all notification channels

Returns all notification channels that the authenticated user has permission to view.

GET /api/alert-notifications

Example request:

  1. GET /api/alert-notifications HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. [
  5.   {
  6.     "id": 1,
  7.     "uid": "team-a-email-notifier",
  8.     "name": "Team A",
  9.     "type": "email",
  10.     "isDefault": false,
  11.     "sendReminder": false,
  12.     "disableResolveMessage": false,
  13.     "settings": {
  14.       "addresses": "dev@grafana.com"
  15.     },
  16.     "created": "2018-04-23T14:44:09+02:00",
  17.     "updated": "2018-08-20T15:47:49+02:00"
  18.   }
  19. ]

Get all notification channels (lookup)

Returns all notification channels, but with less detailed information. Accessible by any authenticated user and is mainly used by providing alert notification channels in Grafana UI when configuring alert rule.

GET /api/alert-notifications/lookup

Example request:

  1. GET /api/alert-notifications/lookup HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. [
  5.   {
  6.     "id": 1,
  7.     "uid": "000000001",
  8.     "name": "Test",
  9.     "type": "email",
  10.     "isDefault": false
  11.   },
  12.   {
  13.     "id": 2,
  14.     "uid": "000000002",
  15.     "name": "Slack",
  16.     "type": "slack",
  17.     "isDefault": false
  18.   }
  19. ]

Get notification channel by uid

GET /api/alert-notifications/uid/:uid

Returns the notification channel given the notification channel uid.

Example request:

  1. GET /api/alert-notifications/uid/team-a-email-notifier HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {
  5.   "id": 1,
  6.   "uid": "team-a-email-notifier",
  7.   "name": "Team A",
  8.   "type": "email",
  9.   "isDefault": false,
  10.   "sendReminder": false,
  11.   "disableResolveMessage": false,
  12.   "settings": {
  13.     "addresses": "dev@grafana.com"
  14.   },
  15.   "created": "2018-04-23T14:44:09+02:00",
  16.   "updated": "2018-08-20T15:47:49+02:00"
  17. }

Get notification channel by id

GET /api/alert-notifications/:id

Returns the notification channel given the notification channel id.

Example request:

  1. GET /api/alert-notifications/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {
  5.   "id": 1,
  6.   "uid": "team-a-email-notifier",
  7.   "name": "Team A",
  8.   "type": "email",
  9.   "isDefault": false,
  10.   "sendReminder": false,
  11.   "disableResolveMessage": false,
  12.   "settings": {
  13.     "addresses": "dev@grafana.com"
  14.   },
  15.   "created": "2018-04-23T14:44:09+02:00",
  16.   "updated": "2018-08-20T15:47:49+02:00"
  17. }

Create notification channel

You can find the full list of supported notifiers on the alert notifiers page.

POST /api/alert-notifications

Example request:

  1. POST /api/alert-notifications HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  6. {
  7.   "uid": "new-alert-notification", // optional
  8.   "name": "new alert notification",  //Required
  9.   "type":  "email", //Required
  10.   "isDefault": false,
  11.   "sendReminder": false,
  12.   "settings": {
  13.     "addresses": "dev@grafana.com"
  14.   }
  15. }

Example response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {
  5.   "id": 1,
  6.   "uid": "new-alert-notification",
  7.   "name": "new alert notification",
  8.   "type": "email",
  9.   "isDefault": false,
  10.   "sendReminder": false,
  11.   "settings": {
  12.     "addresses": "dev@grafana.com"
  13.   },
  14.   "created": "2018-04-23T14:44:09+02:00",
  15.   "updated": "2018-08-20T15:47:49+02:00"
  16. }

Update notification channel by uid

PUT /api/alert-notifications/uid/:uid

Updates an existing notification channel identified by uid.

Example request:

  1. PUT /api/alert-notifications/uid/cIBgcSjkk HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  6. {
  7.   "uid": "new-alert-notification", // optional
  8.   "name": "new alert notification",  //Required
  9.   "type":  "email", //Required
  10.   "isDefault": false,
  11.   "sendReminder": true,
  12.   "frequency": "15m",
  13.   "settings": {
  14.     "addresses": "dev@grafana.com"
  15.   }
  16. }

Example response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {
  5.   "id": 1,
  6.   "uid": "new-alert-notification",
  7.   "name": "new alert notification",
  8.   "type": "email",
  9.   "isDefault": false,
  10.   "sendReminder": true,
  11.   "frequency": "15m",
  12.   "settings": {
  13.     "addresses": "dev@grafana.com"
  14.   },
  15.   "created": "2017-01-01 12:34",
  16.   "updated": "2017-01-01 12:34"
  17. }

Update notification channel by id

PUT /api/alert-notifications/:id

Updates an existing notification channel identified by id.

Example request:

  1. PUT /api/alert-notifications/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  6. {
  7.   "id": 1,
  8.   "uid": "new-alert-notification", // optional
  9.   "name": "new alert notification",  //Required
  10.   "type":  "email", //Required
  11.   "isDefault": false,
  12.   "sendReminder": true,
  13.   "frequency": "15m",
  14.   "settings": {
  15.     "addresses": "dev@grafana.com"
  16.   }
  17. }

Example response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {
  5.   "id": 1,
  6.   "uid": "new-alert-notification",
  7.   "name": "new alert notification",
  8.   "type": "email",
  9.   "isDefault": false,
  10.   "sendReminder": true,
  11.   "frequency": "15m",
  12.   "settings": {
  13.     "addresses": "dev@grafana.com"
  14.   },
  15.   "created": "2017-01-01 12:34",
  16.   "updated": "2017-01-01 12:34"
  17. }

Delete alert notification by uid

DELETE /api/alert-notifications/uid/:uid

Deletes an existing notification channel identified by uid.

Example request:

  1. DELETE /api/alert-notifications/uid/team-a-email-notifier HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {
  5.   "message": "Notification deleted"
  6. }

Delete alert notification by id

DELETE /api/alert-notifications/:id

Deletes an existing notification channel identified by id.

Example request:

  1. DELETE /api/alert-notifications/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {
  5.   "message": "Notification deleted"
  6. }

Test notification channel

Sends a test notification message for the given notification channel type and settings. You can find the full list of supported notifiers at the alert notifiers page.

POST /api/alert-notifications/test

Example request:

  1. POST /api/alert-notifications/test HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  6. {
  7.   "type":  "email",
  8.   "settings": {
  9.     "addresses": "dev@grafana.com"
  10.   }
  11. }

Example response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  4. {
  5.   "message": "Test notification sent"
  6. }