# Notification Channels API

Contents

* [Notification Channels API](https://docs.hostedgraphite.com/alerting-guide/notification-channels-api)
  * [Creating notification channels](#creating-notification-channels)
  * [Searching notification channels](#searching-notification-channels)
  * [Obtain information on a single notification](#obtain-information-on-a-single-notification)
  * [Updating notification channels](#updating-notification-channels)
  * [Deleting notification channels](#deleting-notification-channels)

### [Creating notification channels](#creating-notification-channels)

<mark style="color:green;">`POST`</mark> `/v2/notifications/`

#### Path Parameters

| Name                                          | Type   | Description                                                                                                 |
| --------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| type<mark style="color:red;">\*</mark>        | String | The type of notification channel to create.                                                                 |
| description<mark style="color:red;">\*</mark> | String | A name for the channel.                                                                                     |
| destination<mark style="color:red;">\*</mark> | String | The destination for the notification. ie the email address for *email*, slack webhook URL for *slack,* etc. |
| auto\_resolve                                 | String | Only used by VictorOps and PagerDuty channels. Defaults to *false*. More info here.                         |

{% tabs %}
{% tab title="201" %}

```http
HTTP/1.1 201 
Content-Type: application/json
```

```json
{
  "id": "id",
  "url": "/v2/notifications/<notification_id>"
}
```

{% endtab %}

{% tab title="404" %}
Not Found Invalid form data
{% endtab %}

{% tab title="409" %}
Conflict Channel with the description already exists.
{% endtab %}
{% endtabs %}

**Request format**:

```json
HTTP/1.1 200
Content-Type: application/json

{
  "type": "email" | "pagerduty" | "slack" | "webhook" | "victorops" | "opsgenie",
  "description": "Descriptive name for channel",
  "destination": "Destination key of the channel.",
  "auto_resolve": True | False
}
```

**Curl example**

```
curl -H "Content-Type: application/json" -X POST -d \
'{"type": "email", "description": "A test notification", "destination": "email@example.com"}' \
"https://YOUR-API-KEY@api.hostedgraphite.com/v2/notifications/"
```

***

### [Searching notification channels](#searching-notification-channels)

<mark style="color:blue;">`GET`</mark> `/v2/notifications/?query`

Returns a JSON object containing information on notification channels matching the search query. Returns all the notifications if the parameter is left empty.

#### Path Parameters

| Name          | Type   | Description                                                                                                                                                                                       |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type          | String | <p>Format: <code>\&type=\<type\_1>\&type=\<type\_2></code></p><p>The notification type to search for. Can specify multiple types to search for more than 1.</p>                                   |
| description   | String | <p>Format: <code>\&descriptions=\<descriptions\_1>\&descriptions=\<descriptions\_2></code></p><p>The descriptions to search for. Can specify multiple descriptions to search for more than 1.</p> |
| id            | String | <p>Format: <code>\&id=\<id\_1>\&id=\<id\_2></code></p><p>The notification id to search for. Can specify multiple ids to search for more than 1.</p>                                               |
| page          | String | <p>Format: <code>\&page=1</code></p><p>The page number to query. Used if there are more items than can be displayed in a single request (default: 1).</p>                                         |
| max           | String | <p>Format: <code>\&max=50</code></p><p>The maximum number of items to display. Limit of 100 (default: 100).</p>                                                                                   |
| auto\_resolve | String | For use with VictorOps and PagerDuty channels only.                                                                                                                                               |

{% tabs %}
{% tab title="200" %}

```http
HTTP/1.1 200 
Content-Type: application/json 
```

```json
{
  "notifications": [
    {
      "type": "email",
      "destination": "example@example.com",
      "description": "Email notification channel",
      "id": "notification_channel_1",
      "auto_resolve": true
    },
    {
      "type": "slack",
      "destination": "https://slack-webhook-url.com",
      "description": "Slack notification channel",
      "id": "notification_channel_2",
      "auto_resolve": false
    }
  ],
  "next_page": false
}

```

{% endtab %}

{% tab title="400" %}
Bad Request Invalid
{% endtab %}
{% endtabs %}

**Curl example**

```
curl -X GET "https://YOUR-API-KEY@api.hostedgraphite.com/v2/notifications/?type=email&type=slack"
```

Specifying multiple fields performs an `OR` operation and returns notifications that match either criteria.

***

### [Obtain information on a single notification](#obtain-information-on-a-single-notification)

<mark style="color:blue;">`GET`</mark> `/v2/notifications/<notification_id>/`

Returns a single notification identified by the notification id.

#### Path Parameters

| Name                                          | Type   | Description                                                                                                 |
| --------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| type<mark style="color:red;">\*</mark>        | String | The type of notification channel to create.                                                                 |
| description<mark style="color:red;">\*</mark> | String | A name for the channel.                                                                                     |
| destination<mark style="color:red;">\*</mark> | String | The destination for the notification. ie the email address for *email*, slack webhook URL for *slack,* etc. |
| auto\_resolve                                 | String | Only used by VictorOps and PagerDuty channels. Defaults to *false*.                                         |

{% tabs %}
{% tab title="200" %}

```http
HTTP/1.1 200 
Content-Type: application/json 
```

```json
{
  "type": "email",
  "description": "Primary email notification channel",
  "destination": "example@example.com",
  "id": "notification_channel_1",
  "auto_resolve": true
}

```

{% endtab %}

{% tab title="400" %}
Bad Request Doesn't exist
{% endtab %}
{% endtabs %}

**Curl example**

```
curl -X GET "https://YOUR-API-KEY@api.hostedgraphite.com/v2/notification/123-456-789/"
```

Obtain information of the notification channel identified by the id `123-456-789`.

***

### [Updating notification channels](#updating-notification-channels)

<mark style="color:orange;">`PUT`</mark> `/v2/notifications/<notification_id>/`

Updates a notification channel identified by the notification id.

#### Path Parameters

| Name          | Type   | Description                                                                                                 |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| type          | String | The type of notification channel to create.                                                                 |
| description   | String | A name for the channel.                                                                                     |
| destination   | String | The destination for the notification. ie the email address for *email*, slack webhook URL for *slack,* etc. |
| auto\_resolve | String | Only used by VictorOps and PagerDuty channels. Defaults to *false*.                                         |

{% tabs %}
{% tab title="200" %}

```http
HTTP/1.1 200 
Content-Type: application/json 
```

```json
{
  "type": "slack",
  "description": "Slack notification channel",
  "destination": "https://slack-webhook-url.com",
  "id": "notification_channel_2",
  "auto_resolve": false
}

```

{% endtab %}

{% tab title="400" %}
Bad Request Invalid form data
{% endtab %}

{% tab title="404" %}
Not Found Doesn't exist
{% endtab %}

{% tab title="409" %}
Conflict Notification channel with the description already exists.
{% endtab %}
{% endtabs %}

**Curl example**

```
curl -H "Content-Type: application/json" -X PUT \
 -d '{"destination": "new_email@example.com"}' \
"https://YOUR-API-KEY@api.hostedgraphite.com/v2/notifications/123-456-789/"
```

Updates the destination of notification `123-456-789`. Each field is optional and only the specified fields are updated.

***

### [Deleting notification channels](#deleting-notification-channels)

`DELETE /v2/notifications/<notification_id>/` - Deletes a notification channel identified by the notification id.

**Curl example**

```
curl -X DELETE "https://YOUR-API-KEY@api.hostedgraphite.com/v2/notifications/123-456-789/"
```

Delete the notification channel identified by the id `123-456-789`.

**Status Codes:**

> * **200** - OK
> * **404** - Notification channel doesn’t exist.