energylink/docs/sources/http_api/alerting_notification_channels.md

+++ title = "Alerting Notification Channels HTTP API " description = "Grafana Alerting Notification Channel HTTP API" keywords = ["grafana", "http", "documentation", "api", "alerting", "alerts", "notifications"] aliases = [] type = "docs" [menu.docs] name = "Alerting Notification Channels" parent = "http_api" +++

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 URL's for accessing notification channels and when syncing notification channels between multiple Grafana installs, see alert notification channel provisioning for more information.

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:

GET /api/alert-notifications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "id": 1,
    "uid": "team-a-email-notifier",
    "name": "Team A",
    "type": "email",
    "isDefault": false,
    "sendReminder": false,
    "disableResolveMessage": false,
    "settings": {
      "addresses": "carl@grafana.com;dev@grafana.com"
    },
    "created": "2018-04-23T14:44:09+02:00",
    "updated": "2018-08-20T15:47:49+02:00"
  }
]

Get notification channel by uid

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

Will return the notification channel given the notification channel uid.

Example Request:

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

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "team-a-email-notifier",
  "name": "Team A",
  "type": "email",
  "isDefault": false,
  "sendReminder": false,
  "disableResolveMessage": false,
  "settings": {
    "addresses": "carl@grafana.com;dev@grafana.com"
  },
  "created": "2018-04-23T14:44:09+02:00",
  "updated": "2018-08-20T15:47:49+02:00"
}

Get notification channel by id

GET /api/alert-notifications/:id

Will return the notification channel given the notification channel id.

Example Request:

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

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "team-a-email-notifier",
  "name": "Team A",
  "type": "email",
  "isDefault": false,
  "sendReminder": false,
  "disableResolveMessage": false,
  "settings": {
    "addresses": "carl@grafana.com;dev@grafana.com"
  },
  "created": "2018-04-23T14:44:09+02:00",
  "updated": "2018-08-20T15:47:49+02:00"
}

Create notification channel

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

POST /api/alert-notifications

Example Request:

POST /api/alert-notifications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "name": "new alert notification",  //Required
  "type":  "email", //Required
  "isDefault": false,
  "sendReminder": false,
  "settings": {
    "addresses": "carl@grafana.com;dev@grafana.com"
  }
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "cIBgcSjkk",
  "name": "new alert notification",
  "type": "email",
  "isDefault": false,
  "sendReminder": false,
  "settings": {
    "addresses": "carl@grafana.com;dev@grafana.com"
  },
  "created": "2018-04-23T14:44:09+02:00",
  "updated": "2018-08-20T15:47:49+02:00"
}

Update notification channel by uid

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

Updates an existing notification channel identified by uid.

Example Request:

PUT /api/alert-notifications/uid/cIBgcSjkk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "name": "new alert notification",  //Required
  "type":  "email", //Required
  "isDefault": false,
  "sendReminder": true,
  "frequency": "15m",
  "settings": {
    "addresses": "carl@grafana.com;dev@grafana.com"
  }
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "cIBgcSjkk",
  "name": "new alert notification",
  "type": "email",
  "isDefault": false,
  "sendReminder": true,
  "frequency": "15m",
  "settings": {
    "addresses": "carl@grafana.com;dev@grafana.com"
  },
  "created": "2017-01-01 12:34",
  "updated": "2017-01-01 12:34"
}

Update notification channel by id

PUT /api/alert-notifications/:id

Updates an existing notification channel identified by id.

Example Request:

PUT /api/alert-notifications/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "id": 1,
  "uid": "cIBgcSjkk",
  "name": "new alert notification",  //Required
  "type":  "email", //Required
  "isDefault": false,
  "sendReminder": true,
  "frequency": "15m",
  "settings": {
    "addresses": "carl@grafana.com;dev@grafana.com"
  }
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "cIBgcSjkk",
  "name": "new alert notification",
  "type": "email",
  "isDefault": false,
  "sendReminder": true,
  "frequency": "15m",
  "settings": {
    "addresses": "carl@grafana.com;dev@grafana.com"
  },
  "created": "2017-01-01 12:34",
  "updated": "2017-01-01 12:34"
}

Delete alert notification by uid

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

Deletes an existing notification channel identified by uid.

Example Request:

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

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "Notification deleted"
}

Delete alert notification by id

DELETE /api/alert-notifications/:id

Deletes an existing notification channel identified by id.

Example Request:

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

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "Notification deleted"
}

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:

POST /api/alert-notifications/test HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "type":  "email",
  "settings": {
    "addresses": "carl@grafana.com;dev@grafana.com"
  }
}

Example Response:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "Test notification sent"
}