--- title: Notifications API description: Create and manage notification lists to configure where and how alerts are sent via the Cronitor API. --- The Notifications API allows you to programmatically create and manage notification lists. Notification lists define where alerts are sent when monitors detect problems, including email addresses, Slack channels, PagerDuty services, and other integrations. {% .lead %} ## Authentication The Notification Lists API requires API key authentication with monitor scopes: - **`monitor:read`** - Required to list and retrieve notification lists - **`monitor:write`** - Required to create, update, and delete notification lists Create an API key with the appropriate scopes from the [API Settings](/app/settings/api) page. For more information about API authentication and scopes, see the [API documentation](/docs/api). --- ## Quick Start ### Create a Notification List ```bash curl --user API_KEY: \ --header "Content-Type: application/json" \ --request POST \ --data '{ "name": "DevOps Team", "key": "devops-team", "notifications": { "emails": ["oncall@example.com", "devops@example.com"], "slack": ["#alerts"], "pagerduty": ["P123ABC"] } }' \ https://cronitor.io/api/notifications ``` ### List All Notification Lists ```bash curl https://cronitor.io/api/notifications -u API_KEY: ``` ### Use in a Monitor ```bash curl --user API_KEY: \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "notify": ["devops-team"] }' \ https://cronitor.io/api/monitors/my-monitor ``` --- ## Notification Lists ### List Notification Lists Retrieve all notification lists for your organization. #### Endpoint ```bash GET https://cronitor.io/api/notifications ``` #### Query Parameters - **`page`** (integer) - Page number for pagination (default: 1) - **`pageSize`** (integer) - Number of results per page (default: 50) #### Example ```bash curl https://cronitor.io/api/notifications -u API_KEY: ``` #### Response ```json { "page": 1, "page_size": 50, "total_template_count": 3, "templates": [ { "key": "default", "name": "Default", "notifications": { "emails": ["admin@example.com"] }, "monitors": 45, "monitor_details": [ {"key": "api-health", "name": "API Health Check"}, {"key": "db-backup", "name": "Database Backup"} ], "status": "active", "created": "2023-01-15T10:00:00Z", "environments": [] }, { "key": "devops-team", "name": "DevOps Team", "notifications": { "emails": ["oncall@example.com"], "slack": ["#devops-alerts"] }, "monitors": 12, "monitor_details": [], "status": "active", "created": "2023-06-20T14:30:00Z", "environments": [] } ] } ``` --- ### Create a Notification List Create a new notification list to configure alert destinations. #### Endpoint ```bash POST https://cronitor.io/api/notifications ``` #### Request Body ```json { "name": "Engineering Team", "key": "engineering-team", "notifications": { "emails": ["eng-alerts@example.com"], "slack": ["#engineering"], "webhooks": ["https://example.com/webhook"] }, "environments": [ {"key": "production"} ] } ``` #### Parameters - **`name`** (string, required) - Display name for the notification list - **`key`** (string, optional) - Unique identifier. If not provided, one will be generated from the name - **`notifications`** (object, required) - Notification destinations (see Notifications Object below) - **`environments`** (array, optional) - Limit this notification list to specific environments #### Notifications Object The `notifications` object supports the following keys. Most integrations must be configured in [Settings > Integrations](https://cronitor.io/app/settings/integrations) before they can be referenced here. See the [Integrations documentation](/docs/integrations) for setup instructions. | Key | Type | Description | |-----|------|-------------| | `emails` | array of strings | Email addresses to notify | | `phones` | array of strings | Phone numbers for SMS (e.g., `+15551234567`) | | `slack` | array of strings | [Slack](/docs/using-slack-with-cronitor) integration identifiers | | `pagerduty` | array of strings | [PagerDuty](/docs/using-pagerduty-with-cronitor) integration identifiers | | `datadog-on-call` | array of strings | [Datadog On-Call](/docs/using-datadog-on-call-with-cronitor) integration identifiers | | `opsgenie` | array of strings | [Opsgenie](/docs/using-opsgenie-with-cronitor) integration identifiers | | `victorops` | array of strings | [Splunk On-Call](/docs/using-splunk-with-cronitor) integration identifiers | | `microsoft-teams` | array of strings | [Microsoft Teams](/docs/using-microsoft-teams-with-cronitor) integration identifiers | | `discord` | array of strings | [Discord](/docs/using-discord-with-cronitor) integration identifiers | | `telegram` | array of strings | [Telegram](/docs/using-telegram-with-cronitor) integration identifiers | | `gchat` | array of strings | [Google Chat](/docs/using-gchat-with-cronitor) integration identifiers | | `larksuite` | array of strings | [Lark](/docs/using-larksuite-with-cronitor) integration identifiers | | `webhooks` | array of strings | [Webhook](/docs/using-webhooks) URLs or integration identifiers | #### Example ```bash curl --user API_KEY: \ --header "Content-Type: application/json" \ --request POST \ --data '{ "name": "Critical Alerts", "key": "critical-alerts", "notifications": { "emails": ["oncall@example.com"], "pagerduty": ["PSERVICE123"], "slack": ["#critical-alerts"] } }' \ https://cronitor.io/api/notifications ``` #### Response ```json { "key": "critical-alerts", "name": "Critical Alerts", "notifications": { "emails": ["oncall@example.com"], "pagerduty": ["PSERVICE123"], "slack": ["#critical-alerts"] }, "monitors": 0, "monitor_details": [], "status": "active", "created": "2023-12-01T10:00:00Z", "environments": [] } ``` --- ### Get a Notification List Retrieve details for a specific notification list. #### Endpoint ```bash GET https://cronitor.io/api/notifications/:key ``` #### Example ```bash curl https://cronitor.io/api/notifications/devops-team -u API_KEY: ``` #### Response ```json { "key": "devops-team", "name": "DevOps Team", "notifications": { "emails": ["oncall@example.com", "devops@example.com"], "slack": ["#devops-alerts"], "pagerduty": ["P123ABC"] }, "monitors": 12, "monitor_details": [ {"key": "api-health", "name": "API Health Check"}, {"key": "payment-service", "name": "Payment Service"} ], "status": "active", "created": "2023-06-20T14:30:00Z", "environments": [] } ``` --- ### Update a Notification List Update a notification list's name or notification destinations. #### Endpoint ```bash PUT https://cronitor.io/api/notifications/:key ``` #### Request Body ```json { "key": "devops-team", "name": "DevOps Team (Updated)", "notifications": { "emails": ["oncall@example.com", "devops@example.com", "backup@example.com"], "slack": ["#devops-alerts", "#incidents"], "pagerduty": ["P123ABC"] } } ``` #### Parameters - **`key`** (string, required) - The notification list key (must match the key in the URL) - **`name`** (string) - Updated display name - **`notifications`** (object) - Updated notification destinations #### Example ```bash curl --user API_KEY: \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "key": "devops-team", "name": "DevOps Team", "notifications": { "emails": ["oncall@example.com"], "slack": ["#devops-alerts", "#incidents"], "pagerduty": ["P123ABC", "P456DEF"] } }' \ https://cronitor.io/api/notifications/devops-team ``` #### Response Returns the updated notification list object. --- ### Delete a Notification List Delete a notification list. The default notification list cannot be deleted. #### Endpoint ```bash DELETE https://cronitor.io/api/notifications/:key ``` #### Example ```bash curl --request DELETE https://cronitor.io/api/notifications/old-team -u API_KEY: ``` #### Response Returns HTTP 204 No Content on success. **Note:** The `default` notification list cannot be deleted and will return HTTP 400 Bad Request. --- ## Notification List Attributes {% attribute name="key" context="[string]" /%} Unique identifier for the notification list. Used when assigning monitors to use this notification list via the `notify` attribute. {% attribute name="name" context="[string] **required**" /%} Display name for the notification list. Shown in the Cronitor dashboard. {% attribute name="notifications" context="[object] **required**" /%} Object containing notification destinations. See the Notifications Object table above for supported keys. {% attribute name="environments" context="[array of objects]" /%} Optional array of environment objects to limit this notification list to specific environments. Each object should have a `key` property. {% attribute name="monitors" context="[integer] read-only" /%} Count of monitors using this notification list. {% attribute name="monitor_details" context="[array of objects] read-only" /%} Array of monitor objects (key and name) using this notification list. {% attribute name="status" context="[string] read-only" /%} Current status of the notification list. {% attribute name="created" context="[timestamp] read-only" /%} ISO 8601 formatted timestamp of when the notification list was created. --- ## Using Notification Lists with Monitors When creating or updating monitors, reference notification lists by their key: ```bash curl --user API_KEY: \ --header "Content-Type: application/json" \ --request POST \ --data '{ "type": "job", "key": "nightly-backup", "name": "Nightly Backup", "schedule": "0 2 * * *", "notify": ["devops-team", "critical-alerts"] }' \ https://cronitor.io/api/monitors ``` You can also mix notification list keys with direct notification targets: ```json { "notify": ["devops-team", "email:extra@example.com", "slack:#overflow"] } ``` --- ## Best Practices - **Use the default list wisely**: The default notification list is used when no `notify` attribute is specified - **Create team-based lists**: Organize notification lists by team or service ownership - **Use environment filtering**: Create environment-specific notification lists to avoid alert noise in development - **Include escalation paths**: For critical services, include both immediate (Slack) and escalation (PagerDuty) channels - **Keep lists focused**: Smaller, targeted lists are easier to maintain than large catch-all lists ## Related - [Integrations API](/docs/integrations-api) — create and list the destinations a notification list can reference - [Integrations](/docs/integrations) — dashboard overview and provider guides