> For the complete documentation index, see [llms.txt](https://docs.visualsentinel.com/llms.txt)

# Notification Channels API

Manage notification destinations (email, Slack, Discord, etc.). This page lists all 12 endpoints in the Notification Channels area of the Visual Sentinel REST API.

Base URL: `https://visualsentinel.com`. Unless an endpoint says otherwise it accepts an API key or a session cookie, see [Authentication](https://docs.visualsentinel.com/guides/authentication.md). Most error responses use the [ErrorResponse](https://docs.visualsentinel.com/reference/models/error-response.md) shape, see [Errors](https://docs.visualsentinel.com/guides/errors.md) and [Rate limits](https://docs.visualsentinel.com/guides/rate-limits.md).

## Endpoints

- [List notification channels](#list-notification-channels): `GET /api/notification-channels`
- [Create notification channel](#create-notification-channel): `POST /api/notification-channels`
- [Get notification channel](#get-notification-channel): `GET /api/notification-channels/{id}`
- [Update notification channel](#update-notification-channel): `PUT /api/notification-channels/{id}`
- [Toggle notification channel](#toggle-notification-channel): `PATCH /api/notification-channels/{id}`
- [Delete notification channel](#delete-notification-channel): `DELETE /api/notification-channels/{id}`
- [Test notification channel](#test-notification-channel): `POST /api/notification-channels/{id}/test`
- [List push subscriptions](#list-push-subscriptions): `GET /api/push-subscriptions`
- [Register push subscription](#create-push-subscription): `POST /api/push-subscriptions`
- [Remove push subscription](#delete-push-subscription): `DELETE /api/push-subscriptions`
- [Get notification preferences](#get-notification-preferences): `GET /api/notification-preferences`
- [Update notification preferences](#update-notification-preferences): `PUT /api/notification-preferences`

## List notification channels

`GET /api/notification-channels`

Get all notification channels for the organization. Secrets in `config` come back masked: Slack, Discord and Teams `webhookUrl` and the custom webhook `url` show only the scheme and host followed by `••••••••`; webhook header values, the webhook `secret` and the Prometheus `basicAuth.password` show `••••••••`; PagerDuty `integrationKey`, Opsgenie `apiKey`, Telegram `botToken` and WhatsApp `accessToken` show their first characters followed by `••••••••`.

**Responses**

- `200`: List of notification channels. Body: object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `channels` | array of [NotificationChannel](https://docs.visualsentinel.com/reference/models/notification-channel.md) | No |   |

## Create notification channel

`POST /api/notification-channels`

Create a notification channel. Channel types available depend on the plan (403 `PLAN_LIMIT_EXCEEDED`).

Request body (required): [CreateNotificationChannelRequest](https://docs.visualsentinel.com/reference/models/create-notification-channel-request.md).

**Responses**

- `201`: Channel created. Body: object.
- `400`: Validation failed or required settings missing for the channel type.
- `403`: Channel type not on your plan (`PLAN_LIMIT_EXCEEDED`), read-only role, or an API key without `channels:write`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `channel` | [NotificationChannel](https://docs.visualsentinel.com/reference/models/notification-channel.md) | No |   |

## Get notification channel

`GET /api/notification-channels/{id}`

Get details of a specific notification channel. Secrets in `config` come back masked: Slack, Discord and Teams `webhookUrl` and the custom webhook `url` show only the scheme and host followed by `••••••••`; webhook header values, the webhook `secret` and the Prometheus `basicAuth.password` show `••••••••`; PagerDuty `integrationKey`, Opsgenie `apiKey`, Telegram `botToken` and WhatsApp `accessToken` show their first characters followed by `••••••••`.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Channel details. Body: [NotificationChannel](https://docs.visualsentinel.com/reference/models/notification-channel.md).

## Update notification channel

`PUT /api/notification-channels/{id}`

Update an existing notification channel. `config` replaces the saved settings. To keep a saved secret, send back the masked value exactly as a read returned it (for a webhook header, its masked value under the same header name); the stored value is kept. An address that still contains the mask but differs from the masked saved address is rejected with 400, since the hidden part cannot be edited: send the full new address instead. A rename, or an edit whose settings are unchanged, keeps the channel's verified state.

**Parameters**

- `id` (path, string (uuid), required)

Request body (required): [CreateNotificationChannelRequest](https://docs.visualsentinel.com/reference/models/create-notification-channel-request.md).

**Responses**

- `200`: Channel updated.

## Toggle notification channel

`PATCH /api/notification-channels/{id}`

Enable or disable a notification channel.

**Parameters**

- `id` (path, string (uuid), required)

Request body (required): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | No |   |

**Responses**

- `200`: Channel toggled.

## Delete notification channel

`DELETE /api/notification-channels/{id}`

Delete a notification channel.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Channel deleted.

## Test notification channel

`POST /api/notification-channels/{id}/test`

Send a test notification to verify the channel is configured correctly.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Test notification sent. The test goes to every destination real alerts reach. When real alerts would not reach this channel, wouldReceiveAlerts is false and reason says why. Body: object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | No |   |
| `message` | string | No |   |
| `sentAt` | string (date-time) | No |   |
| `wouldReceiveAlerts` | boolean | No |   |
| `reason` | string or null | No | One of: `disabled`, `paused`, `plan`, `unverified`, `null`. |
| `results` | array of object | No |   |
| `results[].target` | string | No |   |
| `results[].status` | string | No | One of: `sent`, `failed`, `skipped`. |
| `results[].error` | string | No |   |
| `results[].reason` | string | No | One of: `unverified`. |

## List push subscriptions

`GET /api/push-subscriptions`

List all browser push notification subscriptions for the current organization.

**Responses**

- `200`: Push subscriptions list. Body: object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `subscriptions` | array of object | No |   |
| `subscriptions[].channelId` | string (uuid) | No |   |
| `subscriptions[].channelName` | string | No |   |
| `subscriptions[].endpoint` | string (uri) | No |   |
| `subscriptions[].name` | string | No |   |
| `subscriptions[].createdAt` | string (date-time) | No |   |
| `subscriptions[].userId` | string (uuid) | No |   |

## Register push subscription

`POST /api/push-subscriptions`

Register a browser push notification subscription. Creates a new PUSH notification channel and auto-assigns it to all existing monitors. Requires write access and a plan that supports push notifications.

Request body (required): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `subscription` | object | Yes |   |
| `subscription.endpoint` | string (uri) | Yes |   |
| `subscription.keys` | object | Yes |   |
| `subscription.keys.p256dh` | string | Yes |   |
| `subscription.keys.auth` | string | Yes |   |
| `name` | string | No | Optional friendly name for this browser Max length 100. |

**Responses**

- `201`: Push subscription registered. Body: object.
- `400`: Validation error.
- `403`: Push notifications not available on current plan.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | No |   |
| `message` | string | No |   |
| `channelId` | string (uuid) | No |   |

## Remove push subscription

`DELETE /api/push-subscriptions`

Remove a browser push subscription by endpoint URL. If it is the last subscription in its channel, the entire channel is deleted.

Request body (required): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `endpoint` | string (uri) | Yes | The push subscription endpoint URL to remove |

**Responses**

- `200`: Push subscription removed. Body: object.
- `400`: Validation error.
- `404`: Subscription not found.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | No |   |
| `message` | string | No |   |

## Get notification preferences

`GET /api/notification-preferences`

Get the user's notification preferences (which event types trigger which channels).

**Responses**

- `200`: Notification preferences.

## Update notification preferences

`PUT /api/notification-preferences`

Update notification preferences for event types.

**Responses**

- `200`: Preferences updated.

## Data models

Request and response shapes these endpoints use: [NotificationChannel](https://docs.visualsentinel.com/reference/models/notification-channel.md), [CreateNotificationChannelRequest](https://docs.visualsentinel.com/reference/models/create-notification-channel-request.md).

Generated from the OpenAPI 3.1 specification at [https://docs.visualsentinel.com/openapi.json](https://docs.visualsentinel.com/openapi.json), the same file the interactive reference reads.