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. Most error responses use the ErrorResponse shape, see Errors and Rate limits.

Endpoints

• List notification channels: GET /api/notification-channels
• Create notification channel: POST /api/notification-channels
• Get notification channel: GET /api/notification-channels/{id}
• Update notification channel: PUT /api/notification-channels/{id}
• Toggle notification channel: PATCH /api/notification-channels/{id}
• Delete notification channel: DELETE /api/notification-channels/{id}
• Test notification channel: POST /api/notification-channels/{id}/test
• List push subscriptions: GET /api/push-subscriptions
• Register push subscription: POST /api/push-subscriptions
• Remove push subscription: DELETE /api/push-subscriptions
• Get notification preferences: GET /api/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.

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.

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.

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.

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.

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.

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.

List push subscriptions

GET /api/push-subscriptions

List all browser push notification subscriptions for the current organization.

Responses

• 200: Push subscriptions list. Body: object.

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.

Responses

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

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.

Responses

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

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, CreateNotificationChannelRequest.

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