WatchGuard NDR Smart Alerts API

Version: 2.0.0

WatchGuard NDR Smart Alerts API Version History

Download the API specification

Introduction

The WatchGuard NDR Smart Alerts API is a RESTful API that you can use to retrieve details for a WatchGuard NDR Smart Alert and to close a Smart Alert with a specific reason and related details.

This documentation explains how to get access to the WatchGuard NDR Smart Alerts API and includes examples to help you get started.

Get Started

This section describes how to submit requests to the WatchGuard NDR Smart Alerts API.

API URL

The WatchGuard NDR Smart Alerts API API URL is:

https://{base API URL}/rest/watchguard-ndr/smartalerts/v2/

The base URL for WatchGuard public APIs varies by environment and region. The base API URL for your account appears on the Managed Access page in WatchGuard Cloud.

Endpoint Path Parameters

Each WatchGuard public API has a version, expressed as <major>.<minor>.<patch>. You specify the major API version, such as v1 or v2, as part of the endpoint URI path.

Version 1 of the WatchGuard NDR Smart Alerts API is deprecated and will no longer accept requests after 6 August 2027. Although v1 endpoints continue to accept requests, we strongly recommend that you use version 2 of the WatchGuard NDR Smart Alerts API.

Authentication

WatchGuard public APIs use the Open Authorization (OAuth) 2.0 authorization framework for token-based authentication. To use the WatchGuard NDR Smart Alerts API, you must first enable API access in your WatchGuard Cloud account and make an API request to generate an access token.

You must include the access token and your API Key in the header of each request you make to the WatchGuard NDR Smart Alerts API.

For more information, see Authentication.

Request Headers

You must include this information in the header of each request you make to the WatchGuard NDR Smart Alerts API:

Content-Type

application/json

Accept

application/json

Authorization

The access token that you generate with the WatchGuard Authentication API. For more information, see Authentication.

WatchGuard-API-Key

The API Key associated with your WatchGuard Cloud account (shown on the Managed Access page in WatchGuard Cloud).

Get a Smart Alert

/{v2}/accounts/{accountId}/smartalerts/{smartAlertId}

Make a request to this endpoint to retrieve details of a Smart Alert specified by a Smart Alert ID.

Path Parameters

When you send a request to this endpoint, you must include these path parameters:

accountId
string
REQUIRED

Your WatchGuard Cloud account ID. You can see your accountId on the My Account page in WatchGuard Cloud.

Example: WGC-1-123abc456

smartAlertId
string
REQUIRED

Specifies the Smart Alert ID.

Example: 1756794600000||f81dc9a0-5b46-4ceb-b030-7a3eb0fee8ca||int_to_int_PRA

Query Parameters

tenantName
string
REQUIRED

Specifies the WatchGuard Cloud account name for the target account.

Example: WGC-1-123abc456 or ACC-1234567

Example Request

This request retrieves a Smart Alert with Smart Alert ID 1756794600000||f81dc9a0-5b46-4ceb-b030-7a3eb0fee8ca||int_to_int_PRA for account ID WGC-1-123abc456:

curl -X GET 
	https://api.usa.cloud.watchguard.com/rest/watchguard-ndr/smartalerts/v2/accounts/WGC-1-123abc456/smartalerts/1756794600000%7C%7Cf81dc9a0-5b46-4ceb-b030-7a3eb0fee8ca%7C%7Cint_to_int_PRA?tenantName=WGC-1-123abc456
	-H 'Authorization: Bearer TOKEN' \
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Example Response

This response includes the Smart Alert object in JSON format:

{
    "data": [
        {
            "smartAlertId": "1756794600000||f81dc9a0-5b46-4ceb-b030-7a3eb0fee8ca||int_to_int_PRA",
            "name": "Probing or Reconnaissance Activity",
            "siteId": 74,
            "siteName": "WGC-1-123abc456",
            "summary": "The following behaviors suggest that host 10.0.1.2 is conducting a network reconnaissance activity.",
            "majorActorDisplayName": [
                "10.0.1.2"
            ],
            "startTime": 1756794600000,
            "endTime": 1756796400000,
            "confidenceLevel": 100,
            "aocState": "Closed",
            "property1": "Vertical port scan detected: 174 ports scanned",
            "property2": "Primary organization scanned: Untrusted Private",
            "property3": "Number of subnets scanned: 1",
            "behaviorKeyFeatures": [
                "INT_INT_HORIZONTAL_PORT_SCAN_NG.MAJOR_ASSETS_SCANNED_NONE_HIGH"
            ]
        }
    ]
}

Data returned in the response might include:

Some responses might not include all data.

data
array

Lists the Smart Alerts.

smartAlertId
string

Unique identifier of the Smart Alert.

Example: 1756794600000||f81dc9a0-5b46-4ceb-b030-7a3eb0fee8ca||int_to_int_PRA

name
string

Specifies the name of the Smart Alert.

Example: Probing or Reconnaissance Activity

siteId
integer

Unique site identifier.

Example: 74

siteName
string

WatchGuard Cloud Account ID for the site.

Example: WGC-1-123abc456 or ACC-1234567

summary
string

Summary of the Smart Alert.

Example: The following behaviors suggest that host 10.0.1.2 is conducting a network reconnaissance activity.

majorActorDisplayName
array

List of major actors.

Example: 10.0.1.2

startTime
integer

Specifies the start time of the Smart Alert in Unix epoch time format.

Example: 1756794600000

endTime
integer

Specifies the end time of the Smart Alert in Unix epoch time format.

Example: 1756796400000

confidenceLevel
integer

Specifies the confidence level of the Smart Alert.

Example: 100

aocState
string

Indicates the state of the Smart Alert.

Example: Closed

property1
string

Specifies dynamic behavior summary details.

property2
string

Specifies dynamic behavior summary details.

property3
string

Specifies dynamic behavior summary details.

behaviorKeyFeatures
array

Lists the key behavior features of the Smart Alert.

Example: INT_INT_HORIZONTAL_PORT_SCAN_NG.MAJOR_ASSETS_SCANNED_NONE_HIGH

Close a Smart Alert

/{v2}/accounts/{accountId}/smartalerts/{smartAlertId}/close

Make a request to this endpoint to close a Smart Alert specified by a Smart Alert ID. You can also specify the reason to close the Smart Alert.

Path Parameters

When you send a request to this endpoint, you must include these path parameters:

accountId
string
REQUIRED

Your WatchGuard Cloud account ID. You can see your accountId on the My Account page in WatchGuard Cloud.

Example: WGC-1-123abc456

smartAlertId
string
REQUIRED

Specifies the Smart Alert ID.

Example: 1756794600000||f81dc9a0-5b46-4ceb-b030-7a3eb0fee8ca||int_to_int_PRA

Query Parameters

tenantName
string
REQUIRED

Specifies the WatchGuard Cloud account name for the target account.

Example: WGC-1-123abc456 or ACC-1234567

Request Body

includeSimilar
boolean

Indicates whether to include similar Smart Alerts.

Example: true

reasonForClose
string

Reason for closing the Smart Alert. You can specify one of these values:

  • ABNORMAL_UNAUTHORIZED - WatchGuard NDR correctly identified abnormal activity and this activity is not authorized on your network. You do not recognize the activity as part of your authorized business activity.
  • ABNORMAL_AUTHORIZED - WatchGuard NDR correctly identified abnormal activity but you understand the source of the activity and know that it is authorized on the network. This might include activity such as authorized penetration tests or port scans.
  • NORMAL - This activity is expected on the network. When you close these Smart Alerts, you can specify that WatchGuard NDR must suppress future alerts.
  • OTHER - You do not know what the Smart Alert is. It might be a threat but you cannot determine the root cause.

Example: NORMAL

reasonForAuthorizedAbnormal
string

Specifies the reason to close the Smart Alert. Required when reasonForClose is ABNORMAL_AUTHORIZED.

You can specify one of these values:

  • PENETRATION_TESTING - Specify when penetration testing generates a Smart Alert.
  • SCANNING_APPLICATION - Specify when port scans generate a Smart Alert.
  • AD_HOC_TESTING - Specify when ad hoc testing generates a Smart Alert.
  • OTHER - Specify another reason to close the Smart Alert.

Example: PENETRATION_TESTING

reasonForUnauthorizedAbnormal
string

Specifies the reason to close the Smart Alert. Required when reasonForClose is ABNORMAL_UNAUTHORIZED.

You can specify one of these values:

  • KNOWN_THREAT
  • UNKNOWN_THREAT
  • MISCONFIG
  • OTHER

Example: KNOWN_THREAT

allowInFuture
string

Specifies whether similar activity is allowed in the future.

You can specify one of these values:

  • AUTHORIZED - Specify to allow similar activity only during the time periods and frequency observed.
  • AUTHORIZED_ONCE - Specify to allow similar activity only between the Actors included.

Example: AUTHORIZED

authorizedActivities
array

Lists the activities to allow in the future when allowInFuture is AUTHORIZED or AUTHORIZED_ONCE.

You can specify one of these values:

  • AUTHORIZED_TIMES_FREQUENCIES
  • AUTHORIZED_ACTORS

Example: ["AUTHORIZED_TIMES_FREQUENCIES"]

falsePositive
boolean

Indicates whether the Smart Alert is a false positive.

Example: true

reasonForIncorrectInterpretation
array

Lists the key features used to determine that the Smart Alert is not a threat.

Example: ["INT_INT_HORIZONTAL_PORT_SCAN_NG.MAJOR_ASSETS_SCANNED_NONE_HIGH"]

otherReasonForClose
string

Specifies the subtype of the close reason when reasonForClose is OTHER.

You can specify one of these values:

  • UI_NOT_INTERESTING
  • UI_NOT_CLEAR
  • UI_NOT_HELPFUL
  • OTHER

Example: UI_NOT_INTERESTING

additionalInformation
string

Specifies additional information about the Smart Alert.

Example: Any additional information regarding the Smart Alert.

comment
string

Specifies comments related to major actors, ports, or other details.

Example: Any Comments related to the Smart Alert.

Example Request

This request closes the Smart Alert with Smart Alert ID 1756794600000||f81dc9a0-5b46-4ceb-b030-7a3eb0fee8ca||int_to_int_PRA for account ID WGC-1-123abc456:

curl -X PUT 
	https://api.usa.cloud.watchguard.com/rest/watchguard-ndr/smartalerts/v2/accounts/WGC-1-123abc456/smartalerts/1756794600000%7C%7Cf81dc9a0-5b46-4ceb-b030-7a3eb0fee8ca%7C%7Cint_to_int_PRA/close?tenantName=WGC-1-123abc456
	-H 'Authorization: Bearer TOKEN' \
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-d '{
		"includeSimilar": true,
		"reasonForClose": "NORMAL",
		"comment": "Any Comments related to the Smart Alert."
	}'

Example Response

This response indicates that the Smart Alert closed successfully:

{
    "statusMessage": "Success"
}

Data returned in the response might include:

statusMessage
string

Indicates the result of the close operation.

Example: Success