Notifications API

Note

Version: 1.0.0
Base URL: https://next.itrslab.com/notifications/api

The Notifications API provides endpoints to manage notifications and notification targets within the ITRS Analytics platform. You can create, update, delete, and retrieve notifications and their associated targets through this REST API.

The Notifications API is organized around two main resources:

• Notifications: Configure notification rules, conditions, triggers, and payloads
• Notification Targets: Define connection settings for external services (Slack, Email, and ServiceNow.)

Notifications API endpoints Copied

Get All Notifications Copied

GET /v1/notifications

Returns a list of all configured notifications.

Response Copied

Status Code: 200 OK

{
  "notifications": [
    {
      "id": "string",
      "version": "string",
      "notification": {
        "name": "string",
        "description": "string",
        "conditions": {
          "comparison": {
            "namespace": "",
            "name": "string",
            "operator": "EQUALS",
            "value": "string",
            "matchOn": "ANY"
          }
        },
        "groupBy": ["string"],
        "disabled": false,
        "triggers": {
          "onCritical": "60s",
          "onWarning": "300s",
          "onClear": "300s",
          "reminder": "3600s"
        },
        "payloads": {
          "onTriggered": {
            "title": "${severity} | ${date} | ${time}",
            "body": "Entity with dimensions ${dimensions} has been triggered!"
          }
        }
      }
    }
  ]
}

Create Notification Copied

POST /v1/notifications

Creates a new notification.

Request Body Copied

{
  "notification": {
    "name": "Critical System Alert",
    "description": "Alerts for critical system issues",
    "conditions": {
      "comparison": {
        "name": "severity",
        "operator": "EQUALS",
        "value": "critical",
        "matchOn": "ATTRIBUTE"
      }
    },
    "triggers": {
      "onCritical": "60s"
    },
    "payloads": {
      "onTriggered": {
        "title": "Critical Alert: ${entity}",
        "body": "Critical issue detected on ${entity}"
      }
    },
    "targets": {
      "email": {
        "emailRecipients": ["admin@company.com"]
      }
    }
  }
}

Response Copied

Status Code: 200 OK

{
  "id": "12345",
  "version": "1",
  "notification": {
    "name": "Critical System Alert",
    "description": "Alerts for critical system issues",
    "disabled": false,
    "triggers": {
      "onCritical": "60s"
    }
  }
}

Update Notification Copied

PUT /v1/notifications

Updates an existing notification.

Request Body Copied

{
  "id": "12345",
  "version": "1",
  "notification": {
    "name": "Updated Critical System Alert",
    "description": "Updated alerts for critical system issues",
    "disabled": false,
    "triggers": {
      "onCritical": "30s"
    },
    "payloads": {
      "onTriggered": {
        "title": "Updated Critical Alert: ${entity}",
        "body": "Updated critical issue detected on ${entity}"
      }
    }
  }
}

Response Copied

Status Code: 200 OK

{
  "id": "12345",
  "version": "2",
  "notification": {
    "name": "Updated Critical System Alert",
    "description": "Updated alerts for critical system issues",
    "disabled": false
  }
}

Delete Notification Copied

DELETE /v1/notifications/{id}

Deletes a notification.

Path Parameters Copied

Query Parameters Copied

Response Copied

Status Code: 200 OK

{}

Notification Targets Copied

Get All Notification Targets Copied

GET /v1/notifications/targets

Returns a list of all notification targets.

Response Copied

Status Code: 200 OK

{
  "targets": [
    {
      "id": "string",
      "version": "string",
      "target": {
        "name": "string",
        "description": "string",
        "disabled": false,
        "settings": {
          "slack": {
            "channelId": "C1234567890",
            "apiToken": "xoxb-..."
          }
        }
      }
    }
  ]
}

Create Notification Target Copied

POST /v1/notifications/targets

Creates a new notification target.

Request Body Copied

{
  "target": {
    "name": "Slack Operations Channel",
    "description": "Notifications to operations Slack channel",
    "disabled": false,
    "settings": {
      "slack": {
        "channelId": "C1234567890",
        "apiToken": "xoxb-your-slack-token"
      }
    }
  }
}

Response Copied

Status Code: 200 OK

{
  "id": "target123",
  "version": "1",
  "target": {
    "name": "Slack Operations Channel",
    "description": "Notifications to operations Slack channel",
    "disabled": false,
    "settings": {
      "slack": {
        "channelId": "C1234567890",
        "apiToken": "xoxb-your-slack-token"
      }
    }
  }
}

Update Notification Target Copied

PUT /v1/notifications/targets

Updates an existing notification target.

Request Body Copied

{
  "id": "target123",
  "version": "1",
  "target": {
    "name": "Updated Slack Operations Channel",
    "description": "Updated notifications to operations Slack channel",
    "disabled": false,
    "settings": {
      "slack": {
        "channelId": "C1234567890",
        "apiToken": "xoxb-updated-slack-token"
      }
    }
  }
}

Response Copied

Status Code: 200 OK

{
  "id": "target123",
  "version": "2",
  "target": {
    "name": "Updated Slack Operations Channel",
    "description": "Updated notifications to operations Slack channel",
    "disabled": false
  }
}

Delete Notification Target Copied

DELETE /v1/notifications/targets/{id}

Deletes a notification target.

Path Parameters Copied

Query Parameters Copied

Response Copied

Status Code: 200 OK

{}

Supported Integration Types Copied

The Notifications API supports the following target types:

Email Settings Copied

• SMTP Host — SMTP server hostname.
• SMTP Port— SMTP server port number.
• TLS Mode— Security mode (NONE, TLS, STARTTLS).
• Authentication— Basic authentication with username/password.
• Email Recipients— List of email addresses.

Slack Settings Copied

• Channel ID— Slack channel ID (for example, C1234567890).
• API Token— Slack bot token (for example, xoxb-…).
• Reply to Thread— Whether to reply in threads for subsequent notifications.

Microsoft Teams Settings Copied

• URL— Teams Workflow URL.

ServiceNow Settings Copied

• Instance— ServiceNow instance name.
• Incident Table— Table name for incidents (defaults to ‘incident’).
• Authentication— Basic or OAuth 2.0 authentication.
• Table Field Overrides— Custom field mappings.

Webhook Settings Copied

• URL— Webhook endpoint URL.
• HTTP Method— POST or PUT (defaults to POST).
• Authentication— Optional basic authentication.
• Content Type— JSON or YAML format.
• Batch Size— Number of notifications per batch (defaults to 1).

Notification Triggers Copied

Notifications can be configured with the following triggers:

Template Variables Copied

Notification payloads support template variables for dynamic content:

• ${severity} — Current severity level.
• ${date} — Current date.
• ${time} — Current time.
• ${entity} — Entity name.
• ${dimensions} — Entity dimensions.
• Other entity attributes and dimensions can be referenced by name.

Schemas Copied

This section describes the data structures used in the Notifications API.

ArrayComparisonPredicate Copied

Compares an entity attribute to an array of values.

BasicAuth Copied

Basic authentication credentials.

BooleanExpression Copied

Logically combines other expressions using AND/OR operators.

ComparisonPredicate Copied

Compares an entity dimension or attribute to a single specified value.

CreateNotificationRequest Copied

Request to create a new notification.

CreateNotificationResponse Copied

Response containing the created notification.

CreateTargetRequest Copied

Request to create a new notification target.

CreateTargetResponse Copied

Response containing the created notification target.

DeleteNotificationResponse Copied

Response for notification deletion (empty response).

DeleteTargetResponse Copied

Response for target deletion (empty response).

EmailSettings Copied

Configuration for email notification delivery.

EmailTarget Copied

Notification-specific settings for email targets within a notification.

ExistencePredicate Copied

Tests whether an entity has a dimension or attribute, regardless of value.

Expression Copied

Represents a boolean condition to be evaluated against an entity. Used for filtering notifications.

GetNotificationsResponse Copied

Response containing all configured notifications.

GetTargetsResponse Copied

Response containing all notification targets.

IncidentTableField Copied

ServiceNow incident table field override configuration.

Notification Copied

Represents a notification configuration with conditions, triggers, and payloads.

NotificationTarget Copied

Defines connection settings for external notification services.

NotificationTargetPayload Copied

Defines the content structure for notification messages.

NotificationTargetPayloads Copied

Contains payload templates for different notification trigger types.

NotificationTargetSettings Copied

Contains integration-specific connection settings. Only one integration type should be specified.

NotificationTargetTriggers Copied

Configures when notifications should be triggered based on entity severity states.

Duration Format: Duration strings follow the pattern ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ (e.g., “60s”, “300s”, “3600s”).

Notification_Targets Copied

Notification target type and notification-specific settings.

OAuth Copied

OAuth 2.0 authentication credentials using password grant.

ServiceNowSettings Copied

Configuration for ServiceNow integration.

ServiceNowTarget Copied

Notification-specific settings for ServiceNow targets within a notification.

SetPredicate Copied

Compares an entity dimension or attribute value against a set of specified values.

SlackSettings Copied

Configuration for Slack notification delivery.

SlackTarget Copied

Notification-specific settings for Slack targets within a notification.

TeamsSettings Copied

Configuration for Microsoft Teams notification delivery.

TeamsTarget Copied

Notification-specific settings for Microsoft Teams targets within a notification.

UpdateNotificationRequest Copied

Request to update an existing notification.

UpdateNotificationResponse Copied

Response containing the updated notification.

UpdateTargetRequest Copied

Request to update an existing notification target.

UpdateTargetResponse Copied

Response containing the updated notification target.

WebhookSettings Copied

Configuration for webhook notification delivery.

WebhookTarget Copied

Notification-specific settings for webhook targets within a notification.

WrappedNotification Copied

Container for notification with metadata.

WrappedNotificationTarget Copied

Container for notification target with metadata.