Notifications 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.

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 page. For more information about API authentication and scopes, see the API documentation.

Quick Start

Create a Notification List

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

curl https://cronitor.io/api/notifications -u API_KEY:

Use in a Monitor

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

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

curl https://cronitor.io/api/notifications -u API_KEY:

Response

{
  "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

POST https://cronitor.io/api/notifications

Request Body

{
  "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. Connect an integration before you reference it here; see Integrations. For an integration, the key is its service and the value is the integration's label from List Integrations. Reads return the same labels, except webhooks, which return their identifier. Either value is accepted on write.

Example

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

{
  "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

GET https://cronitor.io/api/notifications/:key

Example

curl https://cronitor.io/api/notifications/devops-team -u API_KEY:

Response

{
  "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

PUT https://cronitor.io/api/notifications/:key

Request Body

{
  "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

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

DELETE https://cronitor.io/api/notifications/:key

Example

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

key[string]

Unique identifier for the notification list. Used when assigning monitors to use this notification list via the notify attribute.

name[string] **required**

Display name for the notification list. Shown in the Cronitor dashboard.

notifications[object] **required**

Object containing notification destinations. See the Notifications Object table above for supported keys.

environments[array of objects]

Optional array of environment objects to limit this notification list to specific environments. Each object should have a key property.

monitors[integer] read-only

Count of monitors using this notification list.

monitor_details[array of objects] read-only

Array of monitor objects (key and name) using this notification list.

status[string] read-only

Current status of the notification list.

created[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:

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:

{
  "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 — create and list the destinations a notification list can reference
• Integrations — dashboard overview and provider guides