WatchGuard NDR Assets API

Version: 2.0.0

WatchGuard NDR Assets API Version History

Introduction

The WatchGuard NDR Assets API is a RESTful API that you can use to create, retrieve, update, delete, and search assets in WatchGuard NDR. This documentation explains how to get access to the WatchGuard NDR Assets API and includes examples to help you get started.

Get Started

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

API URL

The WatchGuard NDR Assets API API URL is:

https://{base API URL}/rest/watchguard-ndr/assets/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 Assets 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 Assets API.

Authentication

WatchGuard public APIs use the Open Authorization (OAuth) 2.0 authorization framework for token-based authentication. To use the WatchGuard NDR Assets 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 Assets 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 Assets 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).

Create an Asset

/{v2}/accounts/{accountId}/assets

Make a request to this endpoint to create an asset.

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: ACC-1234567

Query Parameters

tenantName
string
REQUIRED

Specifies the WatchGuard Cloud account ID for the target account.

Example: WGC-1-123abc456

Request Body

name string REQUIRED	Specifies the name or identifier of the asset. Example: 203.0.113.10
description string	Specifies the description of the asset. Example: This is sample description for the asset.
addresses array REQUIRED	Specifies the address details of the asset. Accepts only IP_V4 for create and update operations.
type string	Specifies the address type for an asset. The allowed value is IP_V4. Example: IP_V4
value string	Specifies the IP address of the asset. Example: 203.0.113.10
roles array	Lists the roles associated with the asset. The allowed values are: Active Directory Server Backup Server DHCP Server DNS Server Domain Controller Exchange Server File Server Firewall FTP Server IMAP Mail Server IMAP/SSL Mail Server LDAP Server LDAP/SSL Server NFS Server Oracle Database Server POP3 Mail Server POP3/SSL Mail Server Proxy Server/Edge Remote Desktop Services SCVMM Secure Web Server Security Server SMTP Mail Server SMTP/SSL Mail Server SQL Database Server SSH Server Telnet server Web Server WSUS Server Example: DHCP Server
deviceType array REQUIRED	Lists the device types the asset belongs to. The allowed values are: Access Point Application Server Cluster Cluster SAN Fabric Computer Database Server Domain Controller Email Gateway End User Computing Firewall Gateway Network Network Attached Storage Network Switch Printer Proxy Server Router Server Storage Device Switch Vpn Server Wireless Access Point Example: Server
tags array	Lists the tags associated with the asset. Example: ["server1"]
importance integer REQUIRED	Specifies the asset importance. The allowed values are: 1 - Very Low 2 - Low 3 - Medium 4 - High 5 - Very High Example: 1

Example Request

This request creates an asset for account ID ACC-1234567:

curl -X POST 
	https://api.usa.cloud.watchguard.com/rest/watchguard-ndr/assets/v2/accounts/ACC-1234567/assets?tenantName=WGC-1-123abc456
	-H 'Authorization: Bearer TOKEN' \
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-d '{
		"name": "203.0.113.10",
		"description": "This is sample description for the asset.",
		"addresses": [
		{
			"type": "IP_V4",
			"value": "203.0.113.10"
		}
		],
		"roles": [
			"DHCP Server",
			"DNS Server"
			],
		"deviceType": [
			"Server"
			],
		"importance": 3
	}'

Example Response

This response includes the new asset object in JSON format:

{
    "data": [
        {
            "id": "30a3d6ca-aeee-4331-bf2f-49aa70f709aa",
            "name": "203.0.113.10",
            "description": "This is sample description for the asset.",
            "addresses": [
                {
                    "type": "IP_V4",
                    "value": "203.0.113.10"
                }
            ],
            "roles": [
                "DHCP Server",
                "DNS Server"
            ],
            "threatScore": 0,
            "isActive": true,
            "deviceType": "Server",
            "tags": [],
            "importance": 3,
            "assetInformationSources": [
                "USER"
            ],
            "firstSeen": 1759887000000,
            "lastSeen": 1759887000000,
            "smartAlertCount": 0,
            "operatingSystem": null,
            "state": null
        }
    ],
    "meta": {
        "dataTotalCount": 1
    },
    "requestId": "01182ddd-14a0-43e9-b91e-43372237cdfc",
    "status": 200
}

Get Assets

/{v2}/accounts/{accountId}/assets

Make a request to this endpoint to retrieve a list of all the assets for the specified tenant. To filter the list, you can specify the field and value parameters.

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: ACC-1234567

Query Parameters

tenantName string REQUIRED	Specifies the WatchGuard Cloud account ID for the target account. Example: WGC-1-123abc456
field string	Specifies the asset field to filter on. If not specified, returns all assets. The allowed values are: name deviceType addresses roles assetInformationSources operatingSystem Example: deviceType
value string	Specifies the filter value for the `field`. Required when `field` is specified. Example: router
size integer	Specifies the number of assets to return in the response. The default value is 10. Valid range: 10–5000 Example: 20
offset integer	Specifies the index from which the result set starts (used for pagination). Example: 0
sort string	Specifies the field to sort by. The allowed values are: name description deviceType importance firstSeen lastSeen smartAlertCount threatScore Example: name
order integer	Specifies the sort order. The default value is 0. The allowed values are: 0 - ascending 1 - descending Example: 1

Example Request

This request retrieves assets with deviceType router for account ID ACC-1234567:

curl -X GET 
	https://api.usa.cloud.watchguard.com/rest/watchguard-ndr/assets/v2/accounts/ACC-1234567/assets?tenantName=WGC-1-123abc456&field=deviceType&value=router
	-H 'Authorization: Bearer TOKEN' \
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Example Response

This response includes a list of asset objects in JSON format:

{
    "data": [
        {
            "id": "30a3d6ca-aeee-4331-bf2f-49aa70f709aa",
            "name": "203.0.113.101",
            "description": "This is a sample description.",
            "addresses": [
                {
                    "type": "IP_V4",
                    "value": "203.0.113.80"
                }
            ],
            "roles": [
                "DHCP Server",
                "DNS Server"
            ],
            "threatScore": 25,
            "isActive": true,
            "deviceType": "Router",
            "tags": [
                "server1"
            ],
            "importance": 1,
            "assetInformationSources": [
                "USER"
            ],
            "firstSeen": 1759887000000,
            "lastSeen": 1759887000000,
            "smartAlertCount": 0,
            "operatingSystem": "Windows",
            "state": "Confirmed"
        }
    ],
    "meta": {
        "dataTotalCount": 581
    },
    "requestId": "xyz",
    "status": 200,
    "nextPageUri": "/v2/assets?tenantName=WGC-1-123abc456&field=deviceType&value=router&offset=10&size=20",
    "previousPageUri": "/v2/assets?tenantName=WGC-1-123abc456&field=name&value=server&offset=0&size=20"
}

For exact matches (for example, addresses, assetInformationSources, roles), with no results, the API returns a 404 status. For partial matches (for example, name, deviceType), the API returns a 200 status with meta.dataTotalCount set to zero. The API also returns a 400 status if a filter value is provided without field, and a 404 status if field is provided without value, or if the field or value is not valid.

Data returned in the response might include:

data array	Contains a list of asset response objects.
id string	Represents the unique identifier of the asset. Example: 30a3d6ca-aeee-4331-bf2f-49aa70f709aa
name string	Specifies the name or identifier of the asset. Example: 203.0.113.101
description string	Specifies the description of the asset. Example: This is a sample description.
addresses array	Lists the addresses associated with the asset.
type string	Specifies the address type for an asset. The allowed values are: IP_V4 IP_V6 MAC WINDOWS DNS AWS_AMI_ID DOCKER_IMAGE_ID ORGANIZATION HOSTNAME VPN_USERNAME VPN_REMOTE_IP OFFICE365_USERNAME AD Example: IP_V4
value string	Value of the asset address.
roles array	Lists the roles associated with the asset. The allowed values are: Active Directory Server Backup Server DHCP Server DNS Server Domain Controller Exchange Server File Server Firewall FTP Server IMAP Mail Server IMAP/SSL Mail Server LDAP Server LDAP/SSL Server NFS Server Oracle Database Server POP3 Mail Server POP3/SSL Mail Server Proxy Server/Edge Remote Desktop Services SCVMM Secure Web Server Security Server SMTP Mail Server SMTP/SSL Mail Server SQL Database Server SSH Server Telnet server Web Server WSUS Server
threatScore integer	Specifies the threat score for the asset.
isActive boolean	Indicates whether the asset is active.
deviceType string	Specifies the device type of the asset. The allowed values are: Access Point Application Server Cluster Cluster SAN Fabric Computer Database Server Domain Controller Email Gateway End User Computing Firewall Gateway Network Network Attached Storage Network Switch Printer Proxy Server Router Server Storage Device Switch Vpn Server Wireless Access Point
tags array	Lists the tags associated with the asset.
importance integer	Specifies the asset importance. Allowed values: 1 (Very Low), 2 (Low), 3 (Medium), 4 (High), 5 (Very High).
assetInformationSources array	Lists the sources that initiate creation of the asset. The possible values are: DHCP_LOG - Indicates that a DHCP log initiated the creation of the asset. USER - Indicates that a user initiated the creation of the asset. VPN_LOG - Indicates that a VPN log initiated the creation of the asset. SYSTEM - Indicates that a system initiated the creation of the asset.
firstSeen integer	Unix epoch time in milliseconds when the system first detects the asset.
lastSeen integer	Unix epoch time in milliseconds when the system last detects the asset.
smartAlertCount integer	Specifies the number of Smart Alerts received on the asset.
operatingSystem string	Operating system information for the asset.
state string	Indicates whether bidirectional traffic validates the asset. Example: Confirmed
requestId string	Specifies unique identifier of the request. Example: xyz
status integer	Indicates the response status. Example: 200
meta object	Specifies metadata for the request.
dataTotalCount integer	Specifies the total number of assets that match the request. Example: 581
nextPageUri string	Specifies the URI to retrieve the next page of results, if available.
previousPageUri string	Specifies the URI to retrieve the previous page of results, if available.

Get a Specific Asset

/{v2}/accounts/{accountId}/assets/{assetId}

Make a request to this endpoint to retrieve details for an asset specified by asset 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: ACC-1234567

assetId
string
REQUIRED

ID of the asset to retrieve.

Query Parameters

tenantName
string
REQUIRED

Specifies the WatchGuard Cloud account ID for the target account.

Example: WGC-1-123abc456

Example Request

This request retrieves the asset with asset ID 30a3d6ca-aeee-4331-bf2f-49aa70f709aa for account ID ACC-1234567:

curl -X GET 
	https://api.usa.cloud.watchguard.com/rest/watchguard-ndr/assets/v2/accounts/ACC-1234567/assets/30a3d6ca-aeee-4331-bf2f-49aa70f709aa?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 asset object in JSON format:

{
    "data": [
        {
            "id": "30a3d6ca-aeee-4331-bf2f-49aa70f709aa",
            "name": "203.0.113.101",
            "description": "This is a sample description.",
            "addresses": [
                {
                    "type": "IP_V4",
                    "value": "203.0.113.80"
                }
            ],
            "roles": [
                "DHCP Server",
                "DNS Server"
            ],
            "threatScore": 25,
            "isActive": true,
            "deviceType": "Server",
            "tags": [
                "server1"
            ],
            "importance": 1,
            "assetInformationSources": [
                "USER"
            ],
            "firstSeen": 1759887000000,
            "lastSeen": 1759887000000,
            "smartAlertCount": 0,
            "operatingSystem": "Windows",
            "state": "Confirmed"
        }
    ],
    "meta": {
        "dataTotalCount": 1
    },
    "requestId": "xyz",
    "status": 200
}

Data returned in the response might include:

data array	Contains a list of asset response objects.
id string	Represents the unique identifier of the asset. Example: 30a3d6ca-aeee-4331-bf2f-49aa70f709aa
name string	Specifies the name or identifier of the asset. Example: 203.0.113.101
description string	Specifies the description of the asset. Example: This is a sample description.
addresses array	Lists the addresses associated with the asset.
type string	Specifies the address type for an asset. The allowed values are: IP_V4 IP_V6 MAC WINDOWS DNS AWS_AMI_ID DOCKER_IMAGE_ID ORGANIZATION HOSTNAME VPN_USERNAME VPN_REMOTE_IP OFFICE365_USERNAME AD Example: IP_V4
value string	Value of the asset address.
roles array	Lists the roles associated with the asset. The allowed values are: Active Directory Server Backup Server DHCP Server DNS Server Domain Controller Exchange Server File Server Firewall FTP Server IMAP Mail Server IMAP/SSL Mail Server LDAP Server LDAP/SSL Server NFS Server Oracle Database Server POP3 Mail Server POP3/SSL Mail Server Proxy Server/Edge Remote Desktop Services SCVMM Secure Web Server Security Server SMTP Mail Server SMTP/SSL Mail Server SQL Database Server SSH Server Telnet server Web Server WSUS Server
threatScore integer	Specifies the threat score for the asset.
isActive boolean	Indicates whether the asset is active.
deviceType string	Specifies the device type of the asset. The allowed values are: Access Point Application Server Cluster Cluster SAN Fabric Computer Database Server Domain Controller Email Gateway End User Computing Firewall Gateway Network Network Attached Storage Network Switch Printer Proxy Server Router Server Storage Device Switch Vpn Server Wireless Access Point
tags array	Lists the tags associated with the asset.
importance integer	Specifies the asset importance. Allowed values: 1 (Very Low), 2 (Low), 3 (Medium), 4 (High), 5 (Very High).
assetInformationSources array	Lists the sources that initiate creation of the asset. The possible values are: DHCP_LOG - Indicates that a DHCP log initiated the creation of the asset. USER - Indicates that a user initiated the creation of the asset. VPN_LOG - Indicates that a VPN log initiated the creation of the asset. SYSTEM - Indicates that a system initiated the creation of the asset.
firstSeen integer	Unix epoch time in milliseconds when the system first detects the asset.
lastSeen integer	Unix epoch time in milliseconds when the system last detects the asset.
smartAlertCount integer	Specifies the number of Smart Alerts received on the asset.
operatingSystem string	Operating system information for the asset.
state string	Indicates whether bidirectional traffic validates the asset. Example: Confirmed
requestId string	Specifies unique identifier of the request. Example: xyz
status integer	Indicates the response status. Example: 200
meta object	Specifies metadata for the request.
dataTotalCount integer	Specifies the total number of assets that match the request. Example: 581
nextPageUri string	Specifies the URI to retrieve the next page of results, if available.
previousPageUri string	Specifies the URI to retrieve the previous page of results, if available.

Update an Asset

/{v2}/accounts/{accountId}/assets/{assetId}

Make a request to this endpoint to update an asset detail specified by asset ID. The request body must include the required parameters for the asset.

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: ACC-1234567

assetId
string
REQUIRED

ID of the asset to update.

Query Parameters

tenantName
string
REQUIRED

Specifies the WatchGuard Cloud account ID for the target account.

Example: WGC-1-123abc456

Request Body

name string REQUIRED	Specifies the name or identifier of the asset. Example: 203.0.113.10
description string	Specifies the description of the asset. Example: This is sample description for the asset.
addresses array REQUIRED	Specifies the address details of the asset. Accepts only IP_V4 for create and update operations.
type string	Specifies the address type for an asset. The allowed value is IP_V4. Example: IP_V4
value string	Specifies the IP address of the asset. Example: 203.0.113.10
roles array	Lists the roles associated with the asset. The allowed values are: Active Directory Server Backup Server DHCP Server DNS Server Domain Controller Exchange Server File Server Firewall FTP Server IMAP Mail Server IMAP/SSL Mail Server LDAP Server LDAP/SSL Server NFS Server Oracle Database Server POP3 Mail Server POP3/SSL Mail Server Proxy Server/Edge Remote Desktop Services SCVMM Secure Web Server Security Server SMTP Mail Server SMTP/SSL Mail Server SQL Database Server SSH Server Telnet server Web Server WSUS Server Example: DHCP Server
deviceType array REQUIRED	Lists the device types the asset belongs to. The allowed values are: Access Point Application Server Cluster Cluster SAN Fabric Computer Database Server Domain Controller Email Gateway End User Computing Firewall Gateway Network Network Attached Storage Network Switch Printer Proxy Server Router Server Storage Device Switch Vpn Server Wireless Access Point Example: Server
tags array	Lists the tags associated with the asset. Example: ["server1"]
importance integer REQUIRED	Specifies the asset importance. The allowed values are: 1 - Very Low 2 - Low 3 - Medium 4 - High 5 - Very High Example: 1

Example Request

This request updates the asset with asset ID 30a3d6ca-aeee-4331-bf2f-49aa70f709aa:

curl -X PUT 
	https://api.usa.cloud.watchguard.com/rest/watchguard-ndr/assets/v2/accounts/ACC-1234567/assets/30a3d6ca-aeee-4331-bf2f-49aa70f709aa?tenantName=WGC-1-123abc456
	-H 'Authorization: Bearer TOKEN' \
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-d '{
		"name": "203.0.113.10",
		"description": "This is an updated description for the asset.",
		"addresses": [
		{
			"type": "IP_V4",
			"value": "203.0.113.15"
		}
		],
		"roles": [
			"DHCP Server",
			"DNS Server",
			"Web Server"
			],
		"deviceType": [
			"Server"
			],
		"importance": 3
	}'

Example Response

This response includes the updated asset object in JSON format:

{
    "data": [
        {
            "id": "30a3d6ca-aeee-4331-bf2f-49aa70f709aa",
            "name": "203.0.113.10",
            "description": "This is an updated description for the asset.",
            "addresses": [
                {
                    "type": "IP_V4",
                    "value": "203.0.113.15"
                }
            ],
            "roles": [
                "DHCP Server",
                "DNS Server",
                "Web Server"
            ],
            "threatScore": 0,
            "isActive": true,
            "deviceType": "Server",
            "tags": [],
            "importance": 3,
            "assetInformationSources": [
                "USER"
            ],
            "firstSeen": 1759887000000,
            "lastSeen": 1759887000000,
            "smartAlertCount": 0,
            "operatingSystem": null,
            "state": "Confirmed"
        }
    ],
    "meta": {
        "dataTotalCount": 1
    },
    "requestId": "3c5fa6eb-ba27-4917-b548-8af791d860aa",
    "status": 200
}

Delete an Asset

/{v2}/accounts/{accountId}/assets/{assetId}

Make a request to this endpoint to delete an asset specified by asset 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: ACC-1234567

assetId
string
REQUIRED

ID of the asset to delete.

Query Parameters

tenantName
string
REQUIRED

Specifies the WatchGuard Cloud account ID for the target account.

Example: WGC-1-123abc456

Example Request

This request deletes the asset with asset ID 30a3d6ca-aeee-4331-bf2f-49aa70f709aa for account ID ACC-1234567:

curl -X DELETE 
	https://api.usa.cloud.watchguard.com/rest/watchguard-ndr/assets/v2/accounts/ACC-1234567/assets/30a3d6ca-aeee-4331-bf2f-49aa70f709aa?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 shows a successful deletion with an empty data array and a status of 200:

{
    "data": [],
    "meta": {
        "dataTotalCount": 0
    },
    "requestId": "8ca74597-2cf5-49d4-a66b-2878a64c8cc2",
    "status": 200
}