Reveal(x) 360 REST API Guide

Reveal(x) 360 REST API Guide

The Reveal(x) 360 REST API enables you to automate configuration tasks and retrieve metrics, packets, and detections from Reveal(x) 360. You can send requests to the API through a Representational State Transfer (REST) interface, which is accessed through resource URIs and standard HTTP methods.

Before you can send a REST API request to Reveal(x) 360, you must enable the system for REST API access and generate credentials. Then, you must retrieve a temporary access token by sending the ID and secret of your REST API credentials to Reveal(x) 360. Finally, include the access token in the header of your request for authentication. REST API credentials do not expire automatically and must be manually deleted before they become invalid.

Note:This guide is intended for an audience that has a basic familiarity with software development and the ExtraHop system.

Enable the REST API for Reveal(x) 360

Before you can send REST API requests to Reveal(x) 360, you must enable REST API access.

Before you begin

  • You must have OktaAdmin or ApplianceAdmin privileges.
  1. Log in to Reveal(x) 360.
  2. Click the System Settings icon at the top right of the page and then click Administration.
  3. Click API Access.
  4. In the Manage API Access section, click Enable.
    If you disable and then re-enable the REST API, the REST API might be unavailable for approximately 15 minutes due to DNS propagation, even if the Status section indicates that access is enabled. We recommend that you do not disable and re-enable the REST API often.

Create REST API credentials

These credentials are required to retrieve temporary API access tokens that must be included in requests to the REST API.

Note:REST API credentials do not expire automatically. The credentials created by a user are not deleted when the user is removed from the system. The credentials remain valid until deleted. Any administrator can delete any credentials, regardless of which user created the credentials.

The Reveal(x) 360 REST API does not support cross-origin resource sharing (CORS).

Before you begin

  • You must have OktaAdmin or ApplianceAdmin privileges.
  1. Log in to Reveal(x) 360.
  2. Click the System Settings icon at the top right of the page and then click Administration.
  3. Click API Access.
  4. Click Create Credentials.
  5. In the Name field, type a name for the credentials.
  6. In the Privileges field, specify a privilege level for the credentials.
    The privilege level determines which actions can be performed with the credential. Do not grant more privileges to REST API credentials than needed because it can create a security risk. For example, applications that only retrieve metrics should not be granted credentials that grant administrative privileges. For more information about each privilege level, see User privileges.
    Note:Cloud setup privileges are similar to Full write privileges and allow the credentials to connect self-managed sensors and Trace appliances to Reveal(x) 360.
  7. In the Packet Access field, specify whether you can retrieve packets and session keys with the credentials.
  8. Click Save.
    The Copy REST API Credentials pane appears.
  9. Under ID, click Copy to Clipboard and save the ID to your local machine.
  10. Under Secret, click Copy to Clipboard and save the secret to your local machine.
    Important:The secret cannot be viewed or retrieved later.
  11. Click Done.

Generate a REST API token

A temporary API access token must be included with all REST API requests to Reveal(x) 360. After you create REST API credentials, you can write scripts that generate temporary API access tokens with the credentials. The scripts can then authenticate REST API requests to Reveal(x) 360 with the tokens. Tokens are valid for 60 minutes after being generated.

The HTTPS token request must meet the following requirements:

  • The token is sent in a POST request to the API token endpoint, which is displayed on the API Access page under API Endpoint in Reveal(x) 360.
  • Include the following headers:
    • Authorization: Basic <auth>

      Where <auth> is a bas64 encoded string of the ID and secret joined by a colon.

    • Content-Type: application/x-www-form-urlencoded
  • Include the following payload:
    grant_type=client_credentials
Note:The temporary API access tokens created by the example scripts are only valid for 60 minutes. If a script takes longer than 60 minutes to run, the script must generate a new token every 60 minutes to ensure that it does not send an expired token. If a script sends an expired token, the system responds with a 401 HTTP error code and the following error message:
 The incoming token has expired

Retrieve and run the example Python script

The ExtraHop GitHub repository contains an example Python script that generates a temporary API access token and then authenticates two simple requests with the token that retrieve devices and device groups from Reveal(x) 360.

  1. Go to the ExtraHop code-examples GitHub repository and download the py_rx360_auth/py_rx360_auth.py file to your local machine.
  2. In a text editor, open the py_rx360_auth.py file and replace the following configuration variables with information from your environment:

    HOST: The hostname of the Reveal(x) 360 API. This hostname is displayed in the Reveal(x) 360 API Access page under API Endpoint. The hostname does not include the /oauth/token.

    ID: The ID of the REST API credentials.

    SECRET: The secret of the REST API credentials.

Run the following command:
python3 py_rx360_auth.py

Bash and cURL example

The ExtraHop GitHub repository contains an example Bash script that generates a REST API token with the cURL command and then authenticates two simple requests with the token that retrieve devices and device groups from the Reveal(x) 360 REST API.

  1. Go to the ExtraHop code-examples GitHub repository and download the bash_rx360_auth/bash_rx360_auth.sh file to your local machine.
  2. In a text editor, open the bash_rx360_auth.sh file and replace the following configuration variables with information from your environment:

    HOST: The hostname of the Reveal(x) 360 API. This hostname is displayed in the Reveal(x) 360 API Access page under API Endpoint. The hostname does not include the /oauth/token.

    ID: The ID of the REST API credentials.

    SECRET: The secret of the REST API credentials.

  3. Run the following command:
    ./bash_auth.sh

Reveal(x) 360 resources

You can perform operations on the following resources through the Reveal(x) 360 REST API. You also can also view more detailed information about these resources, such as available HTTP methods, query parameters, and object properties.

Note:API endpoints are located at <host>/api/v1/<endpoint>, where host is the hostname of the Reveal(x) 360 API. For example, if the hostname of the API is https://example.com, the endpoint for activity maps would be the following URL:

https://example.com/api/v1/activitymaps

You can derive the hostname from the API token endpoint by removing /oauth/token from the endpoint string, which appears on the Reveal(x) 360 API Access page under API Endpoint.

Activity Map

An activity map is a dynamic visual representation of the L4-L7 protocol activity between devices in your network. Create a 2D or 3D layout of device connections in real-time to learn about the traffic flow and relationships between devices.

Here are some important considerations about activity maps:

  • You can only create activity maps for devices in Standard Analysis and Advanced Analysis. Discovery Mode devices are not included in activity maps. For more information, see Analysis levels.
  • If you create an activity map for a device, activity group, or device group with no protocol activity in the selected time interval, the map appears without any data. Change the time interval or your origin selection and try again.
  • You can create an activity map in a Command appliance or in Reveal(x) 360 to view device connections across all of your sensors.

To learn about configuring and navigating activity maps, see Activity maps.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /activitymaps Retrieve all activity maps.
POST /activitymaps Create a new activity map.
POST /activitymaps/query Perform a network topology query, which returns activity map data in flat file content.
DELETE /activitymaps/{id} Delete a specific activity map.
GET /activitymaps/{id} Retrieve a specific activity map.
PATCH /activitymaps/{id} Update a specific activity map.
POST /activitymaps/{id}/query Perform a topology query for a specific activity map, which returns activity map data in flat file content.
GET /activitymaps/{id}/sharing Retrieve the users and their sharing permissions for a specific activity map.
PATCH /activitymaps/{id}/sharing Update the users and their sharing permissions for a specific activity map.
PUT /activitymaps/{id}/sharing Replace the users and their sharing permissions for a specific activity map.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

POST /activitymaps

Specify the following parameters.

body: Object
The activity map properties.
name: String
The friendly name for the activity map.
short_code: String
(Optional) The unique short code that is global to all activity maps.
description: String
The description for the activity map.
weighting: String
(Optional) The metric value that determines how activity is weighted between devices. Supported element values are "bytes", "connections", and "turns".
mode: String
(Optional) The layout of the activity map. Supported values are "2dforce" and "3dforce".
show_alert_status: Boolean
(Optional) Indicates whether to show the alert status for devices on the activity map. If enabled, the color of each device on the map represents the most severe alert level associated with the device.
walks: Array of Objects
The list of one or more walk objects. A walk is the path of traffic composed of one or more steps. Each walk begins with one or more origin devices and expands to connections to peer devices that are based on protocol activity. Each expansion from the origin is a step. The contents of the object are defined in the "walk" section below.
origins: Array of Objects
The list of one or more origin devices of the first step within the walk. Object contents are defined in the "source_object" section below.
object_type: String
The metric source type.

The following values are valid:

  • device
  • device_group
object_id: Number
The unique identifier for the source object.
steps: Array of Objects
The list of one or more steps within the walk. Each step is defined by the protocol activity between devices of the previous step to a new set of peer devices. Object contents are defined in the "step" section below.
relationships: Array of Objects
(Optional) The list of one or more filters that define the relationship between two devices. The filters specify which roles and protocols to search for when locating peer devices in the step. Relationships are represented as an edge in the activity map. Object contents are defined in the "relationship" section below. If no value is specified, the operation will locate all peers.
protocol: String
(Optional) The metric protocol associated with the relationship, such as "HTTP" or "DNS". The operation only locates connections between devices over the specified protocol.
role: String
(Optional) The device role associated with the metric protocol of the relationship. The operation only locates connections between devices over the associated protocol in the specified role. Supported role values are "client", "server", or "any". Set to "any" to locate all client, server, and peer device relationships associated with the specified protocol.
peer_in: Array of Objects
(Optional) The list of one or more peer device objects to include in the activity map. Only relationships to peers of the specified source object are included. Object contents are defined in the "source_object" section below.
object_type: String
The metric source type.

The following values are valid:

  • device
  • device_group
object_id: Number
The unique identifier for the source object.
peer_not_in: Array of Objects
(Optional) The list of one or more peer device objects to exclude from the activity map. Relationships to peers of the specified source object are excluded. Object contents are defined in the "source_object" section below.
object_type: String
The metric source type.

The following values are valid:

  • device
  • device_group
object_id: Number
The unique identifier for the source object.

Specify the body parameter in the following JSON format.

{
    "description": "string",
    "mode": "string",
    "name": "string",
    "short_code": "string",
    "show_alert_status": true,
    "walks": {
        "origins": {
            "object_type": "string",
            "object_id": 0
        },
        "steps": {
            "relationships": {
                "protocol": "string",
                "role": "string"
            },
            "peer_in": {
                "object_type": "string",
                "object_id": 0
            },
            "peer_not_in": {
                "object_type": "string",
                "object_id": 0
            }
        }
    },
    "weighting": "string"
}
POST /activitymaps/query

Specify the following parameters.

body: Object
The topology query properties.
from: Number
The beginning timestamp of the time range the query will search, expressed in milliseconds since the epoch.
until: Number
(Optional) The ending timestamp of the time range the query will search, expressed in milliseconds since the epoch. If no value is set, the query end defaults to "now".
weighting: String
(Optional) The metric value that determines how activity is weighted between devices.

The following values are valid:

  • bytes
  • connections
  • turns
edge_annotations: Array of Strings
(Optional) The list of one or more edge annotations to include in the topology query.

The following values are valid:

  • protocols
  • appearances
walks: Array of Objects
The list of one or more walk objects to include in the topology query. A walk is the path of traffic composed of one or more steps. Each walk begins with one or more origin devices and expands to connections to peer devices that are based on protocol activity. Each expansion from the origin is a step. Object contents are defined in the "topology_walk" section below.
origins: Array of Objects
The list of one or more origin devices of the first step within the walk. Object contents are defined in the "topology_source" section below.
object_type: String
The type of source object.

The following values are valid:

  • all_devices
  • device_group
  • device
object_id: Number
The unique identifier for the source object. Set to 0 if the value of the "object_type" parameter is "all_devices".
steps: Array of Objects
The list of one or more steps within the walk. Each step is defined by the protocol activity between devices of the previous step to a new set of peer devices. Object coontents are defined in the "topology_step" section below.
relationships: Array of Objects
(Optional) The list of one or more filters that define the relationship between two devices. The filters specify which roles and protocols to search for when locating peer devices in the step. Relationships are represented as an edge in the activity map. If no value is set, the operation includes all peers. Object contents are defined in the "topology_relationship" section below.
role: String
(Optional) The role of the peer device in relation to the origin device.

The following values are valid:

  • client
  • server
  • any
protocol: String
(Optional) The protocol over which the origin device is communicating, such as "HTTP". If no value is set, the object includes any protocol.
peer_in: Array of Objects
(Optional) The list of one or more peer devices to include in the topology graph. Only relationships to peers of the specified source object are included. Object contents are defined in the "topology_source" section below.
object_type: String
The type of source object.

The following values are valid:

  • all_devices
  • device_group
  • device
object_id: Number
The unique identifier for the source object. Set to 0 if the value of the "object_type" parameter is "all_devices".
peer_not_in: Array of Objects
(Optional) The list of one or more peer devices to exclude from the topology graph. Relationships to peer devices of the specified source object are excluded. Object contents are defined in the "topology_source" section below.
object_type: String
The type of source object.

The following values are valid:

  • all_devices
  • device_group
  • device
object_id: Number
The unique identifier for the source object. Set to 0 if the value of the "object_type" parameter is "all_devices".

Specify the body parameter in the following JSON format.

{
    "edge_annotations": [],
    "from": 0,
    "until": 0,
    "walks": {
        "origins": {
            "object_type": "string",
            "object_id": 0
        },
        "steps": {
            "relationships": {
                "role": "string",
                "protocol": "string"
            },
            "peer_in": {
                "object_type": "string",
                "object_id": 0
            },
            "peer_not_in": {
                "object_type": "string",
                "object_id": 0
            }
        }
    },
    "weighting": "string"
}
GET /activitymaps

There are no parameters for this operation.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "description": "string",
    "id": 0,
    "mod_time": 0,
    "mode": "string",
    "name": "string",
    "owner": "string",
    "rights": [
        "string"
    ],
    "short_code": "string",
    "show_alert_status": true,
    "walks": [],
    "weighting": "string"
}
GET /activitymaps/{id}

Specify the following parameters.

id: Number
The unique identifier for the activity map.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "description": "string",
    "id": 0,
    "mod_time": 0,
    "mode": "string",
    "name": "string",
    "owner": "string",
    "rights": [
        "string"
    ],
    "short_code": "string",
    "show_alert_status": true,
    "walks": [],
    "weighting": "string"
}
POST /activitymaps/{id}/query

Specify the following parameters.

id: Number
The unique identifier for the activity map.
body: Object
The topology query properties.
from: Number
The beginning timestamp of the time range the query will search, expressed in milliseconds since the epoch.
until: Number
(Optional) The ending timestamp of the time range the query will search, expressed in milliseconds since the epoch. If no value is set, the query end defaults to "now".
edge_annotations: Array of Strings
(Optional) The list of one or more edge annotations to include in the topology query.

The following values are valid:

  • protocols
  • appearances

Specify the body parameter in the following JSON format.

{
    "edge_annotations": [],
    "from": 0,
    "until": 0
}
DELETE /activitymaps/{id}

Specify the following parameters.

id: Number
The unique identifier for the activity map.
PATCH /activitymaps/{id}

Specify the following parameters.

id: Number
The unique identifier for the activity map.
body: Object
The activity map properties to update.
GET /activitymaps/{id}/sharing

Specify the following parameters.

id: Number
The unique identifier for the activity map.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "anyone": "string",
    "groups": {},
    "users": {}
}
PUT /activitymaps/{id}/sharing

Specify the following parameters.

body: Object
The users and their permission levels.
id: Number
The unique identifier for the activity map.
PATCH /activitymaps/{id}/sharing

Specify the following parameters.

body: Object
The users and their permission levels.
id: Number
The unique identifier for the activity map.

Alert

Alerts are system notifications that are generated upon specified alert criteria. Default alerts are available in the system, or you can create a custom alert.

Detections and threshold alerts can be set to alert you if a metric crosses the value defined in the alert configuration. Trend alerts cannot be configured through the REST API. For more information, see Alerts.
Note:Machine learning detections require a connection to ExtraHop Cloud Services.

The following table displays all of the operations you can perform this resource:

Operation Description
GET /alerts Retrieve all alerts.
POST /alerts Create a new alert with specified values.
DELETE /alerts{id} Delete a specific alert.
GET /alerts{id} Retrieve a specific alert.
PATCH /alerts{id} Apply updates to a specific alert.
GET /alerts{id}/applications Retrieve all applications that have a specific alert assigned.
POST /alerts{id}/applications Assign and unassign a specific alert to applications.
DELETE /alerts{id}/applications/{child-id} Unassign an application from a specific alert.
POST /alerts{id}/applications/{child-id} Assign an application to a specific alert.
GET /alerts/{id}/devicegroups Retrieve all device groups that have a specific alert assigned.
POST /alerts/{id}/devicegroups Assign and unassign a specific alert to device groups.
DELETE /alerts/{id}/devicegroups/{child-id} Unassign a device group from a specific alert.
POST /alerts/{id}/devicegroups/{child-id} Assign a device group to a specific alert.
GET /alerts/{id}/devices Retrieve all devices that have a specific alert assigned.
POST /alerts/{id}/devices Assign and unassign a specific alert to devices.
DELETE /alerts/{id}/devices/{child-id} Unassign a device from a specific alert.
POST /alerts/{id}/devices/{child-id} Assign a device to a specific alert.
GET /alerts/{id}/emailgroups Retrieve all email groups that have a specific alert assigned.
POST /alerts/{id}/emailgroups Assign and unassign a specific alert to email groups.
DELETE /alerts/{id}/emailgroups/{child-id} Unassign a email group from a specific alert.
POST /alerts/{id}/emailgroups/{child-id} Assign a email group to a specific alert.
GET /alerts/{id}/exclusionintervals Retrieve all exclustion intervals that have a specific alert assigned.
POST /alerts/{id}/exclusionintervals Assign and unassign a specific alert to exclustion intervals.
DELETE /alerts/{id}/exclusionintervals/{child-id} Unassign an exclusion interval from a specific alert.
POST /alerts/{id}/exclusionintervals/{child-id} Assign an exclusion interval to a specific alert.
GET /alerts/{id}/networks Retrieve all networks that have a specific alert assigned.
POST /alerts/{id}/networks Assign and unassign a specific alert to networks.
DELETE /alerts/{id}/networks/{child-id} Unassign a network from a specific alert.
POST /alerts/{id}/networks/{child-id} Assign a network to a specific alert.
GET /alerts/{id}/stats Retrieve all additional statistics for a specific alert.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /alerts

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "apply_all": true,
    "author": "string",
    "categories": [
        "string"
    ],
    "cc": [],
    "description": "string",
    "disabled": true,
    "field_name": "string",
    "field_name2": "string",
    "field_op": "string",
    "id": 0,
    "interval_length": 0,
    "mod_time": 0,
    "name": "string",
    "notify_snmp": true,
    "object_type": "string",
    "operand": "string",
    "operator": "string",
    "param": {},
    "param2": {},
    "protocols": [
        "string"
    ],
    "refire_interval": 0,
    "severity": 0,
    "stat_name": "string",
    "type": "string",
    "units": "string"
}
POST /alerts

Specify the following parameters.

body: Object
Apply the specified property values to the new alert.
description: String
An optional description for the alert.
notify_snmp: Boolean
Indicates whether to send an SNMP trap when an alert is generated.
field_op: String
The type of comparison between the field_name and field_name2 fields when applying a ratio. Only applicable to threshold alerts.

The following values are valid:

  • /
  • null
stat_name: String
The statistic name for the alert. Only applicable to threshold alerts.
disabled: Boolean
Indicates whether the alert is disabled.
operator: String
The logical operator applied when comparing the value of the operand field to alert conditions. Only applicable to threshold alerts.

The following values are valid:

  • ==
  • >
  • <
  • >=
  • <=
operand: String
The value to compare against alert conditions. The compare method is specified by the value of the operator field. Only applicable to threshold alerts.
field_name: String
The name of the monitored metric. Only applicable to threshold alerts.
name: String
The unique, friendly name for the alert.
cc: Array of Strings
The list of email addresses, not included in an email group, to receive notifications.
apply_all: Boolean
Indicates whether the alert is assigned to all available data sources.
severity: Number
The severity level of the alert, which is displayed in the Alert History, email notifications, and SNMP traps. Severity levels 0-2 require immediate attention. Severity levels are described in the REST API Guide.
author: String
The name of the user that created the alert.
param: Object
The first alert parameter, which is either a key pattern or a data point. Only applicable to threshold alerts.
interval_length: Number
The length of the alert interval, expressed in seconds. Only applicable to threshold alerts.

The following values are valid:

  • 30
  • 60
  • 120
  • 300
  • 600
  • 900
  • 1200
  • 1800
param2: Object
The second alert parameter, which is either a key pattern or a data point. Only applicable to threshold alerts.
units: String
The interval in which to evaluate the alert condition. Only applicable to threshold alerts.

The following values are valid:

  • none
  • period
  • 1 sec
  • 1 min
  • 1 hr
field_name2: String
The second monitored metric when applying a ratio. Only applicable to threshold alerts.
refire_interval: Number
The time interval in which alert conditions are monitored, expressed in seconds.

The following values are valid:

  • 300
  • 600
  • 900
  • 1800
  • 3600
  • 7200
  • 14400
type: String
The type of alert.

The following values are valid:

  • detection
  • threshold
object_type: String
The type of metric source monitored by the alert configuration. Only applicable to detection alerts.

The following values are valid:

  • application
  • device
protocols: Array of Strings
(Optional) The list of monitored protocols. Only applicable to detection alerts.
categories: Array of Strings
(Optional) The list of one or more detection categories. An alert is generated only if a detection is identified in the specified categories. Only applicable to detection alerts.

Specify the body parameter in the following JSON format.

{
    "apply_all": true,
    "author": "string",
    "categories": [
        "string"
    ],
    "cc": [],
    "description": "string",
    "disabled": true,
    "field_name": "string",
    "field_name2": "string",
    "field_op": "string",
    "interval_length": 0,
    "name": "string",
    "notify_snmp": true,
    "object_type": "string",
    "operand": "string",
    "operator": "string",
    "param": {},
    "param2": {},
    "protocols": [
        "string"
    ],
    "refire_interval": 0,
    "severity": 0,
    "stat_name": "string",
    "type": "string",
    "units": "string"
}
GET /alerts/{id}

Specify the following parameters.

id: Number
The unique identifier for the alert.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "apply_all": true,
    "author": "string",
    "categories": [
        "string"
    ],
    "cc": [],
    "description": "string",
    "disabled": true,
    "field_name": "string",
    "field_name2": "string",
    "field_op": "string",
    "id": 0,
    "interval_length": 0,
    "mod_time": 0,
    "name": "string",
    "notify_snmp": true,
    "object_type": "string",
    "operand": "string",
    "operator": "string",
    "param": {},
    "param2": {},
    "protocols": [
        "string"
    ],
    "refire_interval": 0,
    "severity": 0,
    "stat_name": "string",
    "type": "string",
    "units": "string"
}
DELETE /alerts/{id}

Specify the following parameters.

id: Number
The unique identifier for the alert.
PATCH /alerts/{id}

Specify the following parameters.

body: Object
Apply the specified property value updates to the alert.
id: Number
The unique identifier for the alert.
GET /alerts/{id}/stats

Specify the following parameters.

id: Number
The unique identifier for the alert.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "alert_id": 0,
    "field_name": "string",
    "id": 0,
    "param": "string",
    "stat_name": "string"
}
GET /alerts/{id}/devicegroups

Specify the following parameters.

id: Number
The unique identifier for the alert.
POST /alerts/{id}/devicegroups

Specify the following parameters.

body: Object
The list of unique identifiers for device groups that is assigned and unassigned to the alert.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the alert.
POST /alerts/{id}/devicegroups/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device group.
id: Number
The unique identifier for the alert.
DELETE /alerts/{id}/devicegroups/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device group.
id: Number
The unique identifier for the alert.
GET /alerts/{id}/emailgroups

Specify the following parameters.

id: Number
The unique identifier for the alert.
POST /alerts/{id}/emailgroups

Specify the following parameters.

body: Object
The list of unique identifiers for email groups that is assigned and unassigned to the alert.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the alert.
POST /alerts/{id}/emailgroups/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the email group.
id: Number
The unique identifier for the alert.
DELETE /alerts/{id}/emailgroups/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the email group.
id: Number
The unique identifier for the alert.
GET /alerts/{id}/exclusionintervals

Specify the following parameters.

id: Number
The unique identifier for the alert.
POST /alerts/{id}/exclusionintervals

Specify the following parameters.

body: Object
The list of unique identifiers for exclusion intervals that is assigned and unassigned to the alert.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the alert.
POST /alerts/{id}/exclusionintervals/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the exclusion interval.
id: Number
The unique identifier for the alert.
DELETE /alerts/{id}/exclusionintervals/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the exclusion interval.
id: Number
The unique identifier for the alert.
GET /alerts/{id}/devices

Specify the following parameters.

id: Number
The unique identifier for the alert.
POST /alerts/{id}/devices

Specify the following parameters.

body: Object
The list of unique identifiers for devices that is assigned and unassigned to the alert.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the alert.
POST /alerts/{id}/devices/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device.
id: Number
The unique identifier for the alert.
DELETE /alerts/{id}/devices/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device.
id: Number
The unique identifier for the alert.
GET /alerts/{id}/networks

Specify the following parameters.

id: Number
The unique identifier for the alert.
POST /alerts/{id}/networks

Specify the following parameters.

body: Object
The list of unique identifiers for networks that is assigned and unassigned to the alert.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the alert.
POST /alerts/{id}/networks/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the network.
id: Number
The unique identifier for the alert.
DELETE /alerts/{id}/networks/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the network.
id: Number
The unique identifier for the alert.
GET /alerts/{id}/applications

Specify the following parameters.

id: Number
The unique identifier for the alert.
POST /alerts/{id}/applications

Specify the following parameters.

body: Object
The list of unique identifiers for applications that is assigned and unassigned to the alert.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the alert.
POST /alerts/{id}/applications/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the application.
id: Number
The unique identifier for the alert.
DELETE /alerts/{id}/applications/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the application.
id: Number
The unique identifier for the alert.

Analysis Priority

The ExtraHop system analyzes and classifies traffic for every device it discovers. Your license reserves capacity for the ExtraHop system to collect metrics for high-value devices. This capacity is associated with two analysis levels: Advanced Analysis and Standard Analysis.

You can specify which devices receive Advanced Analysis and Standard Analysis levels by configuring analysis priority rules. Analysis priorities help inform the ExtraHop system about which devices are important in your environment. A third analysis level, Discovery Mode, is available for devices that are not in Advanced or Standard Analysis.

Note:By default, each sensor (Discover appliance) manages its own analysis priorities. If the sensor is connected to a Command appliance or to Reveal(x) 360, you can centrally manage these shared system settings from one of those systems.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /analysispriority/config/{sensor_id} Retrieve the analysis priority rules for a specific sensor.
PUT /analysispriority/config/{sensor_id} Replace the analysis priority rules for a specific sensor.
GET /analysispriority/{sensor_id}/manager Retrieve the system that is configured to manage the analysis priority rules for the sensor.
PATCH /analysispriority/{sensor_id}/manager Update the system that manages analysis priority rules for a specific sensor.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /analysispriority/{appliance_id}/manager

Specify the following parameters.

appliance_id: Number
The identifier for the local sensor. This value must be set to 0.
GET /analysispriority/config/{appliance_id}

Specify the following parameters.

appliance_id: Number
The identifier for a sensor. Set this value to 0 if calling on a sensor.
PUT /analysispriority/config/{appliance_id}

Specify the following parameters.

body: Object
The properties of the priority analysis rules.
autofill_advanced: Boolean
Indicates whether to automatically place devices in Advanced Analysis until capacity is reached. Devices in the advanced_rules list are prioritized, followed by devices in the standard_rules list, and then by the discovery time for the device. The capacity for Advanced Analysis is determined by the ExtraHop system license.
advanced_rules: Array of Objects
(Optional) The Advanced Analysis priority rules for a device group.
type: String
The type of group the analysis priority rules apply to.

The following values are valid:

  • device_group
object_id: Number
The unique identifier for the group.
description: String
(Optional) The description for analysis priority rules.
autofill_standard: Boolean
Indicates whether to automatically place devices in Standard Analysis until total capacity is reached. Devices in the standard_rules list are prioritized, followed by the discovery time for the device. The total capacity is determined by the ExtraHop system license.
standard_rules: Array of Objects
(Optional) The Standard Analysis priority rules for a device group.
type: String
The type of group the analysis priority rules apply to.

The following values are valid:

  • device_group
object_id: Number
The unique identifier for the group.
description: String
(Optional) The description for analysis priority rules.

Specify the body parameter in the following JSON format.

{
    "advanced_rules": {
        "type": "string",
        "object_id": 0,
        "description": "string"
    },
    "autofill_advanced": true,
    "autofill_standard": true,
    "standard_rules": {
        "type": "string",
        "object_id": 0,
        "description": "string"
    }
}
appliance_id: Number
The identifier for a sensor. Set this value to 0 if calling on a sensor.
PATCH /analysispriority/{appliance_id}/manager

Specify the following parameters.

body: Object
The ID of the appliance that will now manage analysis priority rules for the local Discover appliance. Set this value to 0 to restore management to the local appliance.
manager: Number
The unique identifier for the managing ExtraHop system.

Specify the body parameter in the following JSON format.

{
    "manager": 0
}
appliance_id: Number
The identifier for the local sensor. This value must be set to 0.

Application

Applications are user-defined groups that collect metrics identified through triggers across multiple types of traffic. The default All Activity application contains all collected metrics.

The following table displays all of the operations you can perform on the application resource:

Operation Description
GET /applications Retrieve all applications that were active within a specific timeframe.
POST /applications Create a new application.
GET /applications/{id} Retreive a specific application.
PATCH /applications/{id} Update a specific application.
GET /applications/{id}/activity Retrieve all activity for a specific application.
GET /applications/{id}/alerts Retrieve all alerts that are assigned to a specific application.
POST /applications/{id}/alerts Assign and unassign alerts to a specific application.
DELETE /applications/{id}/alerts/{child-id} Unassign an alert from a specific application.
POST /applications/{id}/alerts/{child-id} Assign an alert to a specific application.
GET /applications/{id}/dashboards Retrieve all dashboards related to a specific application.
GET /applications/{id}/pages Retrieve all pages that are assigned to a specific application.
POST /applications/{id}/pages Assign and unassign pages to a specific application.
DELETE /applications/{id}/pages/{child-id} Unassign a page from a specific application.
POST /applications/{id}/pages/{child-id} Assign a page to a specific application.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /applications/{id}

Specify the following parameters.

id: Number
The unique identifier for the application.
include_criteria: Boolean
(Optional) Indicates whether to include the criteria associated with the application in the response.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "criteria": [],
    "description": "string",
    "discovery_id": "string",
    "display_name": "string",
    "extrahop_id": "string",
    "id": 0,
    "mod_time": 0,
    "node_id": 0,
    "user_mod_time": 0
}
POST /applications

Specify the following parameters.

body: Object
The properties of the application.
node_id: Number
(Optional) The unique identifier for the sensor that this application is associated with. The identifier can be retrieved through the GET /nodes operation. This field is valid only on a Command appliance or Reveal(x) 360.
discovery_id: String
The unique identifier for the application, which is displayed on the application page in the ExtraHop system.
display_name: String
The friendly name for the application.
description: String
(Optional) An optional description for the application.
criteria: Array of Objects
(Optional) An array of protocol and source criteria associated with the application. The contents of this array are defined in the 'criteria' section below.
protocol_default: String
The default protocols monitored by the application. Supported values are 'any' and 'none'.
sources: Array of Objects
An array containing one or more metric sources associated with the application. The application only collects metrics from the specified sources. The contents of this array are defined in the 'source' section below.
type: String
The type of metric source associated with the application. Supported source type values are 'device' and 'device_group'.
id: Number
The unique identifier for the device or device group associated with the application.
protocols: Object
(Optional) The list of one or more protocol and role mappings associated with the application. The application only collects metrics from the specified protocols. The format of each protocol is {'protocol':'role'}. Example: {'http': 'server'}. Supported role values are 'client', 'server', 'any', or 'none'.

Specify the body parameter in the following JSON format.

{
    "criteria": {
        "protocol_default": "string",
        "sources": {
            "type": "string",
            "id": 0
        },
        "protocols": {}
    },
    "description": "string",
    "discovery_id": "string",
    "display_name": "string",
    "node_id": 0
}
PATCH /applications/{id}

Specify the following parameters.

body: Object
Apply the specified property updates to the application.
id: Number
The unique identifier for the application.
GET /applications

Specify the following parameters.

active_from: Number
(Optional) Return only applications that are active after the specified time. Positive values specify the time in milliseconds since the epoch. Negative values specify the time in milliseconds before the current time.
active_until: Number
(Optional) Return only applications that are active before the specified time. Positive values specify the time in milliseconds since the epoch. Negative values specify the time in milliseconds before the current time.
limit: Number
(Optional) Limit the number of applications that are returned to the specified maximum number.
offset: Number
(Optional) Skip the first n application results. This parameter is often combined with the limit parameter.
search_type: String
The object type to search for.

The following values are valid:

  • any
  • name
  • node
  • discovery_id
  • extrahop-id
value: String
(Optional) The search criteria. Add a forward slash before and after the criteria to apply RegEx matching.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "criteria": [],
    "description": "string",
    "discovery_id": "string",
    "display_name": "string",
    "extrahop_id": "string",
    "id": 0,
    "mod_time": 0,
    "node_id": 0,
    "user_mod_time": 0
}
GET /applications/{id}/activity

Specify the following parameters.

id: Number
The unique identifier for the application.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "application_id": 0,
    "from_time": 0,
    "id": 0,
    "mod_time": 0,
    "stat_name": "string",
    "until_time": 0
}
GET /applications/{id}/alerts

Specify the following parameters.

id: Number
Retrieve the unique identifier for the application.
direct_assignments_only: Boolean
(Optional) Indicates whether results are restricted to alerts that are directly assigned to the application.
POST /applications/{id}/alerts

Specify the following parameters.

body: Object
Assign or unassign the specified list of unique identifiers for alerts.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
Provide a unique identifier for the application.
POST /applications/{id}/alerts/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the alert.
id: Number
The unique identifier for the application.
DELETE /applications/{id}/alerts/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the alert.
id: Number
The unique identifier for the application.
GET /applications/{id}/dashboards

Specify the following parameters.

id: Number
The unique identifier for the application.

Bundle

Bundles are JSON-formatted documents that contain information about selected system configuration, such as triggers, dashboards, applications, or alerts.

You can create a bundle and then transfer those configurations to another ExtraHop system, or save the bundle as a backup. Bundles can also be downloaded from ExtraHop Solution Bundles and applied through the REST API. For more information, see Bundles.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /bundles Retrieve metadata about all bundles on the ExtraHop system.
POST /bundles Upload a new bundle to the ExtraHop system.
DELETE /bundles/{id} Delete a specific bundle.
GET /bundles/{id} Retrieve a specific bundle export.
POST /bundles/{id}/apply Apply a saved bundle to the ExtraHop system.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /bundles

There are no parameters for this operation.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "built_in": true,
    "created_time": 0,
    "description": "string",
    "id": 0,
    "mod_time": 0,
    "name": "string"
}
POST /bundles

Specify the following parameters.

body: String
A JSON formatted bundle export.
name: String
The friendly name for the bundle.
description: String
(Optional) An optional description for the bundle.

Specify the body parameter in the following JSON format.

{
    "description": "string",
    "name": "string"
}
GET /bundles/{id}

Specify the following parameters.

id: Number
The unique identifier for the bundle.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "built_in": true,
    "created_time": 0,
    "description": "string",
    "id": 0,
    "mod_time": 0,
    "name": "string"
}
DELETE /bundles/{id}

Specify the following parameters.

id: Number
The unique identifier for the bundle.
POST /bundles/{id}/apply

Specify the following parameters.

id: Number
The unique identifier for the bundle.
body: Object
The configuration options for applying the bundle.
policy: String
Indicates whether conflicting objects should be overwritten or skipped.

The following values are valid:

  • overwrite
  • skip
include_assignments: Boolean
Indicates whether object assignments should be restored with the bundle.
node_ids: Array of Numbers
A list of unique identifiers for the nodes on which to apply the bundle. Only applicable on a Command appliance or Reveal(x) 360.

Specify the body parameter in the following JSON format.

{
    "include_assignments": true,
    "node_ids": [],
    "policy": "string"
}

Dashboards

Dashboards are built-in or customized views of your ExtraHop metrics information. For more information, see Dashboards.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /dashboards Retrieve all dashboards.
DELETE /dashboards/{id} Delete a specific dashboard.
GET /dashboards/{id} Retrieve a specific dashboard.
PATCH /dashboards/{id} Update ownership of a specific dashboard.
GET /dashboards/{id}/reports Retrieve scheduled reports that contain a specific dashboard.
Important:This operation is only available from an ExtraHop Command appliance.
GET /dashboards/{id}/sharing Retrieve the users and their sharing permissions for a specific dashboard.
PATCH /dashboards/{id}/sharing Update the users and their sharing permissions for a specific dashboard.
PUT /dashboards/{id}/sharing Replace the users and their sharing permissions for a specific dashboard.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /dashboards

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "author": "string",
    "comment": "string",
    "id": 0,
    "mod_time": 0,
    "name": "string",
    "owner": "string",
    "rights": [
        "string"
    ],
    "short_code": "string",
    "type": "string"
}
GET /dashboards/{id}

Specify the following parameters.

id: Number
The unique identifier for the dashboard.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "author": "string",
    "comment": "string",
    "id": 0,
    "mod_time": 0,
    "name": "string",
    "owner": "string",
    "rights": [
        "string"
    ],
    "short_code": "string",
    "type": "string"
}
DELETE /dashboards/{id}

Specify the following parameters.

id: Number
The unique identifier for the dashboard.
PATCH /dashboards/{id}

Specify the following parameters.

body: Object
The username of the dashboard owner.
id: Number
The unique identifier for the dashboard.
GET /dashboards/{id}/sharing

Specify the following parameters.

id: Number
The unique identifier for the dashboard.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "anyone": "string",
    "groups": {},
    "users": {}
}
PUT /dashboards/{id}/sharing

Specify the following parameters.

body: Object
The users and their permission levels.
id: Number
The unique identifier for the dashboard.
PATCH /dashboards/{id}/sharing

Specify the following parameters.

body: Object
The users and their permission levels.
id: Number
The unique identifier for the dashboard.
GET /dashboards/{id}/reports

Specify the following parameters.

id: Number
The unique identifier for the report.

Detections

The Detections class enables you to retrieve detections that have been identified by the ExtraHop system.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /detections Retrieve all detections.
GET /detections/formats Retrieve all detection formats.
POST /detections/formats Create a new detection format.
DELETE /detections/formats/{id} Delete a specific detection format.
PATCH /detections/formats Update a specific detection format.
GET /detections​/rules​/hiding Retrieve all detection hiding rules.
POST /detections​/rules​/hiding Create a detection hiding rule.
DELETE /detections​/rules​/hiding​/{id} Delete a detection hiding rule.
PATCH ​/detections​/rules​/hiding​/{id} Update a detection hiding rule.
POST /detections/search Retrieve detections that match the specified search criteria.
PATCH /detections​/tickets Update a ticket associated with detections.
GET /detections/{id} Retrieve a specific detection.
PATCH /detections/{id} Update a detection.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /detections/{id}

Specify the following parameters.

id: Number
The unique identifier for the detection.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "appliance_id": 0,
    "assignee": "string",
    "categories": [
        "string"
    ],
    "description": "string",
    "end_time": 0,
    "id": 0,
    "is_user_created": true,
    "mitre_tactics": [],
    "mitre_techniques": [],
    "participants": [],
    "properties": {},
    "resolution": "string",
    "risk_score": 0,
    "start_time": 0,
    "status": "string",
    "ticket_id": "string",
    "ticket_url": "string",
    "title": "string",
    "type": "string",
    "update_time": 0
}
GET /detections

Specify the following parameters.

limit: Number
(Optional) Limit the number of detections returned to the specified maximum number. A random selection of detections is returned.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "appliance_id": 0,
    "assignee": "string",
    "categories": [
        "string"
    ],
    "description": "string",
    "end_time": 0,
    "id": 0,
    "is_user_created": true,
    "mitre_tactics": [],
    "mitre_techniques": [],
    "participants": [],
    "properties": {},
    "resolution": "string",
    "risk_score": 0,
    "start_time": 0,
    "status": "string",
    "ticket_id": "string",
    "ticket_url": "string",
    "title": "string",
    "type": "string",
    "update_time": 0
}
POST /detections/search

Specify the following parameters.

body: Object
The detection search parameters.
filter: Object
Detection-specific filters.
category: String
Return detections from the specified category.
assignee: Array of Strings
Returns detections assigned to the specified user. Specify ".none" to search for unassigned detections or specify ".me" to search for detections assigned to the authenticated user.
ticket_id: Array of Strings
Returns detections that are associated with the specified tickets. Specify ".none" to search for detections that are not associated with tickets.
status: Array of Strings
Returns detections for tickets with the specified status. Specify ".none" to search for detections without a ticket status.

The following values are valid:

  • new
  • in_progress
  • closed
resolution: Array of Strings
Returns detections for tickets with the specified resolution. Specify ".none" to search for detections without resolutions.

The following values are valid:

  • action_taken
  • no_action_taken
from: Number
Returns detections that occurred after the specified date, expressed in milliseconds since the epoch. Detections that started before the specified date are returned if the detection was ongoing at that time.
limit: Number
Returns no more than the specified number of detections.
offset: Number
The number of detections to skip for pagination.
sort: Array of Objects
Sorts returned detections by the specified fields.
direction: String
The order in which returned detections are sorted.

The following values are valid:

  • asc
  • desc
field: String
The field to sort detections by.
until: Number
Return detections that ended before the specified date, expressed in milliseconds since the epoch.
update_time: Number
Return detections that were updated on or after the specified date, expressed in milliseconds since the epoch.

Specify the body parameter in the following JSON format.

{
    "filter": {
        "category": "string",
        "assignee": [],
        "ticket_id": [],
        "status": [],
        "resolution": []
    },
    "from": 0,
    "limit": 0,
    "offset": 0,
    "sort": {
        "direction": "string",
        "field": "string"
    },
    "until": 0,
    "update_time": 0
}
PATCH /detections/{id}

Specify the following parameters.

id: Number
The unique identifier for the detection.
body: Object
Values to update detections ticketing.
PATCH /detections/tickets

Specify the following parameters.

body: Object
The detection ticketing values to update.
ticket_id: String
The ID of the ticket associated with the detection.
assignee: String
The assignee of the ticket associated with the detection.
status: String
The status of the ticket associated with the detection.

The following values are valid:

  • new
  • in_progress
  • closed
resolution: String
The resolution of the ticket associated with the detection.

The following values are valid:

  • action_taken
  • no_action_taken

Specify the body parameter in the following JSON format.

{
    "assignee": "string",
    "resolution": "string",
    "status": "string",
    "ticket_id": "string"
}
GET /detections/formats

There are no parameters for this operation.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "author": "string",
    "display_name": "string",
    "is_user_created": true,
    "mitre_categories": [],
    "properties": {},
    "type": "string"
}
POST /detections/formats

Specify the following parameters.

body: Object
The parameters of the detection format.
type: String
A string identifier for the detection type. The string can only contain letters, numbers, and underscores. Although detection types are unique across built-in formats, and detection types are unique across custom formats, a built-in and custom format can share the same detection type.
display_name: String
The display name of the detection type that appears on the Detections page in the ExtraHop system.
mitre_categories: Array of Strings
(Optional) The IDs of the MITRE techniques associated with the detection.
author: String
(Optional) The author of the detection format.

Specify the body parameter in the following JSON format.

{
    "author": "string",
    "display_name": "string",
    "mitre_categories": [],
    "type": "string"
}
DELETE /detections/formats/{id}

Specify the following parameters.

id: String
The string identifier of the detection format.
PATCH /detections/formats/{id}

Specify the following parameters.

id: String
The string identifier of the detection format.
body: Object
The parameters of the detection format.
GET /detections/rules/hiding

There are no parameters for this operation.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "author": "string",
    "create_time": 0,
    "description": "string",
    "detection_type": "string",
    "detections_hidden": 0,
    "enabled": true,
    "expiration": 0,
    "hide_past_detections": true,
    "id": 0,
    "offender": {},
    "victim": {}
}
POST /detections/rules/hiding

Specify the following parameters.

body: Object
The detection hiding rule parameters.
offender: Object
The offender that this detection hiding rule applies to. Specify a detection_hiding_participant object to apply the rule to a specific victim, or specify "Any" to apply the rule to any offender.
object_type: String
The type of participant.

The following values are valid:

  • device
  • device_group
  • ipaddr
object_id: Number
The ID for the device or device group participant. This option is valid only if the object_type is "device" or "device_group."
object_value: String
The IP address of the participant. This option is valid only if the object_type is "ipaddr."
victim: Object
The victim that this detection hiding rule applies to. Specify a detection_hiding_participant object to apply the rule to a specific victim, or specify "Any" to apply the rule to any victim.
object_type: String
The type of participant.

The following values are valid:

  • device
  • device_group
  • ipaddr
object_id: Number
The ID for the device or device group participant. This option is valid only if the object_type is "device" or "device_group."
object_value: String
The IP address of the participant. This option is valid only if the object_type is "ipaddr."
expiration: Number
The time that the detection hiding rule expires, expressed in milliseconds since the epoch or as null to indicate the rule does not expire.
description: String
(Optional) The description of the detection hiding rule.
detection_type: String
The detection_type that this detection hiding rule applies to. Specify "All" to apply the rule to all detection types.
hide_past_detections: Boolean
(Optional) Indicates whether to hide past detections that the rule applies to. If this parameter is set to false, the rule only hides detections that occur after the rule is created.

Specify the body parameter in the following JSON format.

{
    "description": "string",
    "detection_type": "string",
    "expiration": 0,
    "hide_past_detections": true,
    "offender": {
        "object_type": "string",
        "object_id": 0,
        "object_value": "string"
    },
    "victim": {
        "object_type": "string",
        "object_id": 0,
        "object_value": "string"
    }
}
PATCH /detections/rules/hiding/{id}

Specify the following parameters.

id: Number
The unique identifier for the detection hiding rule.
body: Object
The detection hiding rule fields to update.
enabled: Boolean
Indicates whether the detection hiding rule is enabled.
expiration: Number
The time that the detection hiding rule expires, expressed in milliseconds since the epoch or as null to indicate the rule does not expire.

Specify the body parameter in the following JSON format.

{
    "enabled": true,
    "expiration": 0
}
DELETE /detections/rules/hiding/{id}

Specify the following parameters.

id: Number
The unique identifier for the detection hiding rule.

Device group

Device groups can be either static or dynamic.

A static device group is user-defined; you create a device group and then manually identify and assign each device to that group. A dynamic device group is defined and automatically managed by a set of configured rules.

For example, you can create a device group and then set a rule to classify all devices within a certain IP address range to be added to that group automatically. For more information, see Device Groups.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /devicegroups Retrieve all device groups that were active within a specific time period.
POST /devicegroups Create a new device group.
DELETE /devicegroups/{id} Delete a device group.
GET /devicegroups/{id} Retrieve a specific device group.
PATCH /devicegroups/{id} Update a specific device group.
GET /devicegroups/{id}/alerts Retrieve all alerts that are assigned to a specific device group.
POST /devicegroups/{id}/alerts Assign and unassign a specific device group to alerts.
DELETE /devicegroups/{id}/alerts/{child-id} Unassign an alert from a specific device group.
POST /devicegroups/{id}/alerts/{child-id} Assign an alert to a specific device group.
GET /devicegroups/{id}/dashboards Retrieve all dashboards related to a specific device group.
GET /devicegroups/{id}/devices Retrieve all devices in the device group that are active within a specific time window.
Note:A device is considered inactive after five minutes of not sending or receiving packets. However, if a device resumes sending or receiving packets after a period of inactivity shorter than five days, the device is considered to have been active continuously, including during the period of inactivity.
POST /devicegroups/{id}/devices Assign and unassign a devices to a specific static device group.
DELETE /devicegroups/{id}/devices/{child-id} Unassign a device from a specific static device group.
POST /devicegroups/{id}/devices/{child-id} Assign a device to a specific static device group.
GET /devicegroups/{id}/pages Retrieve all pages that are assigned to a specific device group.
POST /devicegroups/{id}/pages Assign and unassign a specific device to pages group.
DELETE /devicegroups/{id}/pages/{child-id} Unassign a page from a specific device group.
POST /devicegroups/{id}/pages/{child-id} Assign a page to a specific device group.
GET /devicegroups/{id}/triggers Retrieve all triggers that are assigned to a specific device group.
POST /devicegroups/{id}/triggers Assign and unassign a specific device group to triggers.
DELETE /devicegroups/{id}/triggers/{child-id} Unassign a trigger from a specific device group.
POST /devicegroups/{id}/triggers/{child-id} Assign a trigger to a specific device group.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /devicegroups

Specify the following parameters.

since: Number
(Optional) Only return device groups that were modified after this time, expressed in milliseconds since the epoch.
all: Boolean
(Optional) Deprecated. Replaced by the type parameter.
name: String
(Optional) The Regex search value to filter the device groups by name.
type: String
(Optional) Only return device groups of the specified type.

The following values are valid:

  • user_created
  • built_in
  • all

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "built_in": true,
    "description": "string",
    "dynamic": true,
    "field": "string",
    "filter": {},
    "id": 0,
    "include_custom_devices": true,
    "mod_time": 0,
    "name": "string",
    "value": "string"
}
GET /devicegroups/{id}

Specify the following parameters.

id: Number
The unique identifier for the device group.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "built_in": true,
    "description": "string",
    "dynamic": true,
    "field": "string",
    "filter": {},
    "id": 0,
    "include_custom_devices": true,
    "mod_time": 0,
    "name": "string",
    "value": "string"
}
POST /devicegroups

Specify the following parameters.

body: Object
Apply the specified property values to the new device group.
description: String
An optional description of the device group.
name: String
The friendly name for the device group.
include_custom_devices: Boolean
(Optional) Deprecated. Replaced by the filter parameter.
dynamic: Boolean
(Optional) Indicates whether the device group is dynamic.
field: String
Deprecated. Replaced by the filter parameter.

The following values are valid:

  • any
  • name
  • ip address
  • mac address
  • vendor
  • type
  • tag
  • vlan
  • activity
  • node
  • discover time
value: Object
(Optional) Deprecated. Replaced by the filter parameter.
filter: Object
(Optional) Specify the filter criteria for search results.
field: String
The name of the field to filter results on. The search compares the contents of the field parameter to the value of the operand parameter.

The following values are valid:

  • name
  • ipaddr
  • macaddr
  • vendor
  • tag
  • activity
  • node
  • vlan
  • discover_time
  • role
  • dns_name
  • dhcp_name
  • netbios_name
  • cdp_name
  • custom_name
  • software
  • model
  • is_critical
  • instance_id
  • instance_name
  • instance_type
  • cloud_account
  • vpc_id
  • subnet_id
operator: String
The compare method applied when matching the operand value against the field contents. All filter objects require an operator.

The following values are valid:

  • >
  • <
  • <=
  • >=
  • =
  • !=
  • startswith
  • and
  • or
  • not
  • exists
  • not_exists
  • ~
  • !~
operand: String or Number or Object
The value that the query attempts to match. The query compares the value of the operand to the contents of the field parameter and applies the compare method specified by the operator parameter. You can specify the operand as a string, integer, or object. For information about object values, see the REST API Guide.
rules: Array of Objects
An array of one or more filter objects, which can be embedded recursively. Only "and", "or", and "not" operators are allowed for this parameter.

Specify the body parameter in the following JSON format.

{
    "description": "string",
    "dynamic": true,
    "field": "string",
    "filter": {
        "field": "string",
        "operator": "string",
        "operand": "string",
        "rules": []
    },
    "include_custom_devices": true,
    "name": "string",
    "value": "string"
}
DELETE /devicegroups/{id}

Specify the following parameters.

id: Number
The unique identifier for the device group.
PATCH /devicegroups/{id}

Specify the following parameters.

body: Object
Apply the specified property value updates to a specific device group.
description: String
An optional description of the device group.
name: String
The friendly name for the device group.
include_custom_devices: Boolean
(Optional) Deprecated. Replaced by the filter parameter.
field: String
Deprecated. Replaced by the filter parameter.

The following values are valid:

  • any
  • name
  • ip address
  • mac address
  • vendor
  • type
  • tag
  • vlan
  • activity
  • node
  • discover time
value: Object
(Optional) Deprecated. Replaced by the filter parameter.
filter: Object
(Optional) Specify the filter criteria for search results.

Specify the body parameter in the following JSON format.

{
    "description": "string",
    "field": "string",
    "filter": {},
    "include_custom_devices": true,
    "name": "string",
    "value": "string"
}
id: Number
The unique identifier for the device group.
GET /devicegroups/{id}/alerts

Specify the following parameters.

id: Number
The unique identifier for the device group.
direct_assignments_only: Boolean
(Optional) Restrict results to only alerts that are directly assigned to the device group.
POST /devicegroups/{id}/alerts/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the alert.
id: Number
The unique identifier for the device group.
DELETE /devicegroups/{id}/alerts/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the alert.
id: Number
The unique identifier for the device group.
POST /devicegroups/{id}/alerts

Specify the following parameters.

body: Object
The list of unique identifiers for alerts that is assigned and unassigned to the device group.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the device group.
GET /devicegroups/{id}/triggers

Specify the following parameters.

id: Number
The unique identifier for the device group.
direct_assignments_only: Boolean
(Optional) Restrict results to only triggers that are directly assigned to the device group.
POST /devicegroups/{id}/triggers/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the trigger.
id: Number
The unique identifier for the device group.
DELETE /devicegroups/{id}/triggers/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the trigger.
id: Number
The unique identifier for the device group.
POST /devicegroups/{id}/triggers

Specify the following parameters.

body: Object
The list of unique identifiers for triggers that is assigned and unassigned to the device group.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the device group.
POST /devicegroups/{id}/devices/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for a device.
id: Number
The unique identifier for the device group.
DELETE /devicegroups/{id}/devices/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for a device.
id: Number
The unique identifier for the device group.
POST /devicegroups/{id}/devices

Specify the following parameters.

body: Object
The list of unique identifiers for devices that is assigned and unassigned to the device group.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the device group.
GET /devicegroups/{id}/devices

Specify the following parameters.

id: Number
The unique identifier for the device group.
active_from: Number
(Optional) The beginning timestamp for the request. Return only devices active after this time. Time is expressed in milliseconds since the epoch. 0 indicates the time of the request. A negative value is evaluated relative to the current time. The default unit for a negative value is milliseconds, but other units can be specified with a unit suffix. See the REST API Guide for supported time units and suffixes.
active_until: Number
(Optional) The ending timestamp for the request. Return only device active before this time. Follows the same time value guidelines as the active_from parameter.
limit: Number
(Optional) Limit the number of devices returned.
offset: Number
(Optional) Skip the first n device results. This parameter is often combined with the limit parameter.
GET /devicegroups/{id}/dashboards

Specify the following parameters.

id: Number
The unique identifier for the device group.

Device

Devices are objects on your network that have been identified and classified by your ExtraHop system. For more information, see Devices.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /devices Retrieve all devices that were active within a specific time period. For more information, see Extract the device list through the REST API.
Note:A device is considered inactive after five minutes of not sending or receiving packets. However, if a device resumes sending or receiving packets after a period of inactivity shorter than five days, the device is considered to have been active continuously, including during the period of inactivity.
POST /devices/search Retrieve all devices that match specific criteria. For more information, see Search for a device through the REST API.
Note:A device is considered inactive after five minutes of not sending or receiving packets. However, if a device resumes sending or receiving packets after a period of inactivity shorter than five days, the device is considered to have been active continuously, including during the period of inactivity.
GET /devices/{id} Retrieve a specific device.
PATCH /devices/{id} Update a specific device.
GET /devices/{id}/activity Retrieve all activity for a device.
GET /devices/{id}/alerts Retrieve all alerts that are assigned to a specific device.
POST /devices/{id}/alerts Assign and unassign a specific device to alerts.
DELETE /devices/{id}/alerts/{child-id} Unassign an alert from a specific device.
POST /devices/{id}/alerts/{child-id} Assign an alert to a specific device.
GET /devices/{id}/dashboards Retrieve all dashboards related to a specific device.
GET /devices/{id}/devicegroups Retrieve all device groups that are assigned to a specific device.
POST /devices/{id}/devicegroups Assign and unassign a specific device to device groups.
DELETE /devices/{id}/devicegroups/{child-id} Unassign a device group from a specific device.
POST /devices/{id}/devicegroups/{child-id} Assign a device group to a specific device.
GET /devices/{id}/dnsnames Retrieve all DNS names that are associated with a specific device.
GET /devices/{id}/ipaddrs Retrieve all IP addresses that were associated with a specific device within a given time period.
GET /devices/{id}/software Retrieve a list of software running on the specified device.
GET /devices/{id}/tags Retrieve all tags that are assigned to a specific device.
POST /devices/{id}/tags Assign and unassign a specific device to tags.
DELETE /devices/{id}/tags/{child-id} Unassign a tag from a specific device.
POST /devices/{id}/tags/{child-id} Assign a tag to a specific device.
GET /devices/{id}/triggers Retrieve all triggers that are assigned to a specific device.
POST /devices/{id}/triggers Assign and unassign a specific device to triggers.
DELETE /devices/{id}/triggers/{child-id} Unassign a trigger from a specific device.
POST /devices/{id}/triggers/{child-id} Assign a trigger to a specific device.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /devices

Specify the following parameters.

active_from: Number
(Optional) The beginning timestamp for the request. Return only devices active after this time. Time is expressed in milliseconds since the epoch. 0 indicates the time of the request. A negative value is evaluated relative to the current time. The default unit for a negative value is milliseconds, but other units can be specified with a unit suffix. See the REST API Guide for supported time units and suffixes.
active_until: Number
(Optional) The ending timestamp for the request. Return only device active before this time. Follows the same time value guidelines as the active_from parameter.
limit: Number
(Optional) Limit the number of devices returned to the specified maximum number.
offset: Number
(Optional) Skip the first n device results. This parameter is often combined with the limit parameter.
search_type: String
Indicates the field to search.

The following values are valid:

  • any
  • name
  • discovery_id
  • ip address
  • mac address
  • vendor
  • type
  • tag
  • activity
  • node
  • vlan
  • discover time
value: String
(Optional) Specifies the search criteria.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "activity": [],
    "analysis": "string",
    "analysis_level": 0,
    "auto_role": "string",
    "cdp_name": "string",
    "cloud_account": "string",
    "cloud_instance_id": "string",
    "cloud_instance_name": "string",
    "cloud_instance_type": "string",
    "critical": true,
    "custom_name": "string",
    "custom_type": "string",
    "default_name": "string",
    "description": "string",
    "device_class": "string",
    "dhcp_name": "string",
    "discover_time": 0,
    "discovery_id": "string",
    "display_name": "string",
    "dns_name": "string",
    "extrahop_id": "string",
    "id": 0,
    "ipaddr4": "string",
    "ipaddr6": "string",
    "is_l3": true,
    "last_seen_time": 0,
    "macaddr": "string",
    "mod_time": 0,
    "model": "string",
    "netbios_name": "string",
    "node_id": 0,
    "on_watchlist": true,
    "parent_id": 0,
    "role": "string",
    "subnet_id": "string",
    "user_mod_time": 0,
    "vendor": "string",
    "vlanid": 0,
    "vpc_id": "string"
}
POST /devices/search

Specify the following parameters.

body: Object
The device criteria.
active_from: Number
(Optional) The beginning timestamp for the request. Return only devices active after this time. Time is expressed in milliseconds since the epoch. 0 indicates the time of the request. A negative value is evaluated relative to the current time. The default unit for a negative value is milliseconds, but other units can be specified with a unit suffix. See the REST API Guide for supported time units and suffixes.
active_until: Number
(Optional) The ending timestamp for the request. Return only devices active before this time. Follows the same time value guidelines as the active_from parameter.
limit: Number
(Optional) Limit the number of devices returned to the specified maximum number.
offset: Number
(Optional) Skip the specified number of devices. This parameter is often combined with the limit parameter to paginate result sets.
filter: Object
(Optional) Specify the filter criteria for search results.
field: String
The name of the field to filter results on. The search compares the contents of the field parameter to the value of the operand parameter.

The following values are valid:

  • name
  • discovery_id
  • ipaddr
  • macaddr
  • vendor
  • tag
  • activity
  • node
  • vlan
  • discover_time
  • role
  • dns_name
  • dhcp_name
  • netbios_name
  • cdp_name
  • custom_name
  • software
  • model
  • is_critical
  • instance_id
  • instance_name
  • instance_type
  • cloud_account
  • vpc_id
  • subnet_id
operator: String
The compare method applied when matching the operand value against the field contents. All filter objects require an operator.

The following values are valid:

  • >
  • <
  • <=
  • >=
  • =
  • !=
  • startswith
  • and
  • or
  • not
  • exists
  • not_exists
  • ~
  • !~
operand: String or Number or Object
The value that the query attempts to match. The query compares the value of the operand to the contents of the field parameter and applies the compare method specified by the operator parameter. You can specify the operand as a string, integer, or object. For information about object values, see the REST API Guide.
rules: Array of Objects
An array of one or more filter objects, which can be embedded recursively. Only "and", "or", and "not" operators are allowed for this parameter.

Specify the body parameter in the following JSON format.

{
    "active_from": 0,
    "active_until": 0,
    "filter": {
        "field": "string",
        "operator": "string",
        "operand": "string",
        "rules": []
    },
    "limit": 0,
    "offset": 0
}
GET /devices/{id}

Specify the following parameters.

id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "activity": [],
    "analysis": "string",
    "analysis_level": 0,
    "auto_role": "string",
    "cdp_name": "string",
    "cloud_account": "string",
    "cloud_instance_id": "string",
    "cloud_instance_name": "string",
    "cloud_instance_type": "string",
    "critical": true,
    "custom_name": "string",
    "custom_type": "string",
    "default_name": "string",
    "description": "string",
    "device_class": "string",
    "dhcp_name": "string",
    "discover_time": 0,
    "discovery_id": "string",
    "display_name": "string",
    "dns_name": "string",
    "extrahop_id": "string",
    "id": 0,
    "ipaddr4": "string",
    "ipaddr6": "string",
    "is_l3": true,
    "last_seen_time": 0,
    "macaddr": "string",
    "mod_time": 0,
    "model": "string",
    "netbios_name": "string",
    "node_id": 0,
    "on_watchlist": true,
    "parent_id": 0,
    "role": "string",
    "subnet_id": "string",
    "user_mod_time": 0,
    "vendor": "string",
    "vlanid": 0,
    "vpc_id": "string"
}
PATCH /devices/{id}

Specify the following parameters.

body: Object
Apply the specified property value updates to the device.
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
GET /devices/{id}/activity

Specify the following parameters.

id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "device_id": 0,
    "from_time": 0,
    "id": 0,
    "mod_time": 0,
    "stat_name": "string",
    "until_time": 0
}
GET /devices/{id}/ipaddrs

Specify the following parameters.

id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
from: Number
(Optional) Retrieves IP addresses that were associated with the device after the specified date, expressed in milliseconds since the epoch.
until: Number
(Optional) Retrieves IP addresses that were associated with the device before the specified date, expressed in milliseconds since the epoch.
GET /devices/{id}/dnsnames

Specify the following parameters.

id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
from: Number
(Optional) Retrieves DNS names that were associated with the device after the specified date, expressed in milliseconds since the epoch.
until: Number
(Optional) Retrieves DNS names that were associated with the device before the specified date, expressed in milliseconds since the epoch.
GET /devices/{id}/triggers

Specify the following parameters.

id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
direct_assignments_only: Boolean
(Optional) Restrict results to only triggers that are directly assigned to the device.
POST /devices/{id}/triggers

Specify the following parameters.

body: Object
A list of unique identifiers for triggers that are assigned and unassigned to the device.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
POST /devices/{id}/triggers/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the trigger.
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
DELETE /devices/{id}/triggers/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the trigger.
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
GET /devices/{id}/dashboards

Specify the following parameters.

id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
GET /devices/{id}/devicegroups

Specify the following parameters.

id: Number
The unique identifier for the device.
active_from: Number
(Optional) The beginning timestamp for the request. Return only dynamic device groups that the device belonged to after this time. Time is expressed in milliseconds since the epoch. 0 indicates the time of the request. A negative value is evaluated relative to the current time. The default unit for a negative value is milliseconds, but other units can be specified with a unit suffix. See the REST API Guide for supported time units and suffixes.
active_until: Number
(Optional) The ending timestamp for the request. Return only dynamic device groups that the device belonged to before this time. Follows the same time value guidelines as the active_from parameter.
POST /devices/{id}/devicegroups

Specify the following parameters.

body: Object
The list of unique identifiers for device groups that are assigned and unassigned to the device.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
POST /devices/{id}/devicegroups/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device group.
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
DELETE /devices/{id}/devicegroups/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device group.
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
GET /devices/{id}/tags

Specify the following parameters.

id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
POST /devices/{id}/tags

Specify the following parameters.

body: Object
A list of unique identifiers for tags that are assigned and unassigned to the device.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
POST /devices/{id}/tags/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the tag.
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
DELETE /devices/{id}/tags/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the tag.
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
GET /devices/{id}/alerts

Specify the following parameters.

id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
direct_assignments_only: Boolean
(Optional) Restrict results to only alerts that are directly assigned to the device.
POST /devices/{id}/alerts

Specify the following parameters.

body: Object
The list of unique identifiers for alerts that are assigned and unassigned to the device.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
POST /devices/{id}/alerts/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the alert.
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
DELETE /devices/{id}/alerts/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the alert.
id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
GET /devices/{id}/software

Specify the following parameters.

id: Number
The unique identifier for the device, which is displayed as the API ID on the device page in the ExtraHop system.
from: Number
(Optional) Returns software that was observed on the device after the specified date, expressed in milliseconds since the epoch.
until: Number
(Optional) Returns software that was observed on the device before the specified date, expressed in milliseconds since the epoch.

Exclusion intervals

An exclusion interval can be created to set a time period to suppress an alert.

For example, if you do not want to be notified about alerts after hours or on the weekends, an exclusion interval can create a rule to suppress the alert during that time period. For more information, see Alerts.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /exclusionintervals Retrieve all exclusion intervals.
POST /exclusionintervals Create a new exclusion interval.
DELETE /exclusionintervals/{id} Delete a specific exclusion interval.
GET /exclusionintervals/{id} Retrieve a specific exclusion interval.
PATCH /exclusionintervals/{id} Apply updates to a specific exclusion interval.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /exclusionintervals

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "alert_apply_all": true,
    "author": "string",
    "description": "string",
    "end": 0,
    "id": 0,
    "interval_type": "string",
    "mod_time": 0,
    "name": "string",
    "start": 0,
    "trend_apply_all": true
}
POST /exclusionintervals

Specify the following parameters.

body: Object
Set the specified property values on the new exclusion interval.
name: String
The friendly name for the exclusion interval.
author: String
(Optional) The name of the creator of the exclusion interval.
description: String
(Optional) An optional description of the exclusion interval.
interval_type: String
The time window when the exclusion interval was evaluated.

The following values are valid:

  • onetime
  • weekly
  • daily
start: Number
The start of the exclusion interval time range, expressed in seconds. This value is relative to the epoch for onetime exclusions, relative to midnight for daily exclusions, and relative to Monday at midnight for weekly exclusions.
end: Number
The end of the exclusion interval time range, expressed in seconds. This value is relative to the epoch for onetime exclusions, relative to midnight for daily exclusions, and relative to Monday at midnight for weekly exclusions.
alert_apply_all: Boolean
Indicates whether this exclusion interval should be applied to all alerts.
trend_apply_all: Boolean
Indicates whether this exclusion interval should be applied to all trends.

Specify the body parameter in the following JSON format.

{
    "alert_apply_all": true,
    "author": "string",
    "description": "string",
    "end": 0,
    "interval_type": "string",
    "name": "string",
    "start": 0,
    "trend_apply_all": true
}
GET /exclusionintervals/{id}

Specify the following parameters.

id: Number
The unique identifier of the exclusion interval.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "alert_apply_all": true,
    "author": "string",
    "description": "string",
    "end": 0,
    "id": 0,
    "interval_type": "string",
    "mod_time": 0,
    "name": "string",
    "start": 0,
    "trend_apply_all": true
}
DELETE /exclusionintervals/{id}

Specify the following parameters.

id: Number
The unique identifier of the exclusion interval.
PATCH /exclusionintervals/{id}

Specify the following parameters.

body: Object
Apply the specified property value updates to the exclusion interval.
id: Number
The unique identifier for the exclusion interval.

Metrics

Metrics information is collected about every object identified by the ExtraHop system.

Note that metrics are retrieved through the POST method, which creates a query to collect the requested information through the API. For more information, see Extract metrics through the REST API.

The following table displays all of the operations you can perform on this resource:

Operation Description
POST /metrics Perform a metric query.
GET /metrics/next/{xid} If a previous metric query requested activity group metrics from a Command appliance, the GET /metrics/next/{xid} operation retrieves metrics for the activity group on a connected sensor (Discover appliance). Each time a request is sent to GET /metrics/next/{xid}, the operation returns metrics from a different sensor. After all metrics have been retrieved, the operation returns null.
POST /metrics/total Perform a metric query for total values.
POST /metrics/totalbyobject Perform a metric query for total values that are grouped by object.

For example, if you want to see all HTTP responses that occurred on the network in the last 30 minutes, enter the following request schema into the POST /metrics operation:

{
  "cycle": "auto",
  "from": -1800000,
  "metric_category": "http",
  "metric_specs": [
    {
      "name": "rsp"
    }
  ],
  "object_ids": [
    0
  ],
  "object_type": "application",
  "until": 0
}

The response body returns a list of HTTP responses and the time of each event, similar to the following output:

{   
  "stats": [     
    {       
      "oid": 0,
      "time": 1494539640000,
      "duration": 30000,
      "values": [
        354
      ]
    },
    {       
      "oid": 0,
      "time": 1494539640000,
      "duration": 30000,
      "values": [
        354
      ]
    },

    {       
      "oid": 0,
      "time": 1494539640000,
      "duration": 30000,
      "values": [
        354
      ]
    },
  ],
  "cycle": "30sec", 
  "node_id": 0,
  "clock": 1494541440000, 
  "from": 1494539640000,
  "until": 1494541440000 
}

Enter the same request schema into the POST /metrics/total operation to retrieve a count of all HTTP responses that occurred on the network in the last 30 seconds. The response body is similar to the following output:

{   
  "stats": [
    {
      "oid": -1,
      "time": 1494541380000,
      "duration": 1800000,
      "values": [
        33357
      ]
    }
  ],
  "cycle": "30sec", 
  "node_id": 0,
  "clock": 1494541440000, 
  "from": 1494539640000,
  "until": 1494541440000 
}

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

POST /metrics

Specify the following parameters.

body: Object
The description of the metric request.
from: Number
The beginning timestamp for the request. Return only metrics collected after this time. Time is expressed in milliseconds since the epoch. 0 indicates the time of the request. A negative value is evaluated relative to the current time. The default unit for a negative value is milliseconds, but other units can be specified with a unit suffix. See the REST API Guide for supported time units and suffixes.
until: Number
The ending timestamp for the request. Return only metrics collected before this time. Follows the same time value guidelines as the from parameter.
cycle: String
The aggregation period for metrics.

The following values are valid:

  • auto
  • 1sec
  • 30sec
  • 5min
  • 1hr
  • 24hr
object_type: String
Indicates the object type of unique identifiers specified in the object_ids property.

The following values are valid:

  • network
  • device
  • application
  • vlan
  • device_group
  • system
object_ids: Array of Numbers
The list of numeric values that represent unique identifiers. Unique identifiers can be retrieved through the /networks, /devices, /applications, /vlans, /devicegroups, /activitygroups, and /appliances resources. For system health metrics, specify the ID of the ExtraHop system and set the object_type parameter to "system".
metric_category: String
The group of metrics that are searchable in the metric catalog.
metric_specs: Array of Objects
An array of metric_specs that are defined in the Implementation Notes.
name: String
The field name for the metric. When filtering in the metric catalog on a metric_category, each result is a potential metric_spec name. When a result is selected from the catalog, the "Metric" field value is a valid option for this field.
key1: String
(Optional) Filter detail metrics. Detail metrics break down data through keys, which are strings or IP addresses. For example, the metric "HTTP Requests by Method" accepts a key1 value of "GET." Keys can also be regular expressions that are delimited with forward slashes ("/GET/").
key2: String
(Optional) Enable additional filtering on detail metrics.
calc_type: String
(Optional) The type of calculation to perform.

The following values are valid:

  • mean
  • percentiles
percentiles: Array of Numbers
(Optional) The list of percentiles, sorted in ascending order, which should be returned. This parameter is only required if the calc_type parameter is set to "percentiles". If the calc_type parameter is set to mean, the percentiles property cannot be set.

Specify the body parameter in the following JSON format.

{
    "cycle": "string",
    "from": 0,
    "metric_category": "string",
    "metric_specs": {
        "name": "string",
        "key1": "string",
        "key2": "string",
        "calc_type": "string",
        "percentiles": []
    },
    "object_ids": [],
    "object_type": "string",
    "until": 0
}
POST /metrics/total

Specify the following parameters.

body: Object
The description of the metric request.
from: Number
The beginning timestamp for the request. Return only metrics collected after this time. Time is expressed in milliseconds since the epoch. 0 indicates the time of the request. A negative value is evaluated relative to the current time. The default unit for a negative value is milliseconds, but other units can be specified with a unit suffix. See the REST API Guide for supported time units and suffixes.
until: Number
The ending timestamp for the request. Return only metrics collected before this time. Follows the same time value guidelines as the from parameter.
cycle: String
The aggregation period for metrics.

The following values are valid:

  • auto
  • 1sec
  • 30sec
  • 5min
  • 1hr
  • 24hr
object_type: String
Indicates the object type of unique identifiers specified in the object_ids property.

The following values are valid:

  • network
  • device
  • application
  • vlan
  • device_group
  • system
object_ids: Array of Numbers
The list of numeric values that represent unique identifiers. Unique identifiers can be retrieved through the /networks, /devices, /applications, /vlans, /devicegroups, /activitygroups, and /appliances resources. For system health metrics, specify the ID of the ExtraHop system and set the object_type parameter to "system".
metric_category: String
The group of metrics that are searchable in the metric catalog.
metric_specs: Array of Objects
An array of metric_specs that are defined in the Implementation Notes.
name: String
The field name for the metric. When filtering in the metric catalog on a metric_category, each result is a potential metric_spec name. When a result is selected from the catalog, the "Metric" field value is a valid option for this field.
key1: String
(Optional) Filter detail metrics. Detail metrics break down data through keys, which are strings or IP addresses. For example, the metric "HTTP Requests by Method" accepts a key1 value of "GET." Keys can also be regular expressions that are delimited with forward slashes ("/GET/").
key2: String
(Optional) Enable additional filtering on detail metrics.
calc_type: String
(Optional) The type of calculation to perform.

The following values are valid:

  • mean
  • percentiles
percentiles: Array of Numbers
(Optional) The list of percentiles, sorted in ascending order, which should be returned. This parameter is only required if the calc_type parameter is set to "percentiles". If the calc_type parameter is set to mean, the percentiles property cannot be set.

Specify the body parameter in the following JSON format.

{
    "cycle": "string",
    "from": 0,
    "metric_category": "string",
    "metric_specs": {
        "name": "string",
        "key1": "string",
        "key2": "string",
        "calc_type": "string",
        "percentiles": []
    },
    "object_ids": [],
    "object_type": "string",
    "until": 0
}
POST /metrics/totalbyobject

Specify the following parameters.

body: Object
The description of the metric request.
from: Number
The beginning timestamp for the request. Return only metrics collected after this time. Time is expressed in milliseconds since the epoch. 0 indicates the time of the request. A negative value is evaluated relative to the current time. The default unit for a negative value is milliseconds, but other units can be specified with a unit suffix. See the REST API Guide for supported time units and suffixes.
until: Number
The ending timestamp for the request. Return only metrics collected before this time. Follows the same time value guidelines as the from parameter.
cycle: String
The aggregation period for metrics.

The following values are valid:

  • auto
  • 1sec
  • 30sec
  • 5min
  • 1hr
  • 24hr
object_type: String
Indicates the object type of unique identifiers specified in the object_ids property.

The following values are valid:

  • network
  • device
  • application
  • vlan
  • device_group
  • system
object_ids: Array of Numbers
The list of numeric values that represent unique identifiers. Unique identifiers can be retrieved through the /networks, /devices, /applications, /vlans, /devicegroups, /activitygroups, and /appliances resources. For system health metrics, specify the ID of the ExtraHop system and set the object_type parameter to "system".
metric_category: String
The group of metrics that are searchable in the metric catalog.
metric_specs: Array of Objects
An array of metric_specs that are defined in the Implementation Notes.
name: String
The field name for the metric. When filtering in the metric catalog on a metric_category, each result is a potential metric_spec name. When a result is selected from the catalog, the "Metric" field value is a valid option for this field.
key1: String
(Optional) Filter detail metrics. Detail metrics break down data through keys, which are strings or IP addresses. For example, the metric "HTTP Requests by Method" accepts a key1 value of "GET." Keys can also be regular expressions that are delimited with forward slashes ("/GET/").
key2: String
(Optional) Enable additional filtering on detail metrics.
calc_type: String
(Optional) The type of calculation to perform.

The following values are valid:

  • mean
  • percentiles
percentiles: Array of Numbers
(Optional) The list of percentiles, sorted in ascending order, which should be returned. This parameter is only required if the calc_type parameter is set to "percentiles". If the calc_type parameter is set to mean, the percentiles property cannot be set.

Specify the body parameter in the following JSON format.

{
    "cycle": "string",
    "from": 0,
    "metric_category": "string",
    "metric_specs": {
        "name": "string",
        "key1": "string",
        "key2": "string",
        "calc_type": "string",
        "percentiles": []
    },
    "object_ids": [],
    "object_type": "string",
    "until": 0
}
GET /metrics/next/{xid}

Specify the following parameters.

xid: Number
The unique identifier returned by a metric query.

Network locality entry

You can manage a list that specifies the network locality of IP addresses.

For example, you can create an entry in the network locality list that specifies that an IP address or CIDR block is internal or external.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /networklocalities Retrieve all network locality entries.
POST /networklocalities Create a network locality entry.
DELETE /networklocalities/{id} Delete a network locality entry.
Note:This operation is not available if the sensor is connected to Reveal(x) 360.
GET /networklocalities/{id} Retrieve a specific network locality entry.
PATCH /networklocalities/{id} Apply updates to a specific network locality entry.
Note:This operation is not available if the sensor is connected to Reveal(x) 360.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /networklocalities

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "description": "string",
    "external": true,
    "id": 0,
    "mod_time": 0,
    "network": "string"
}
POST /networklocalities

Specify the following parameters.

body: Object
Apply the specified property values to the new network locality entry.
network: String
Network CIDR block or IP address.
external: Boolean
Is this network internal or external.
description: String
(Optional) An optional description of the network locality entry.

Specify the body parameter in the following JSON format.

{
    "description": "string",
    "external": true,
    "network": "string"
}
GET /networklocalities/{id}

Specify the following parameters.

id: Number
The unique identifier for the network locality entry.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "description": "string",
    "external": true,
    "id": 0,
    "mod_time": 0,
    "network": "string"
}
DELETE /networklocalities/{id}

Specify the following parameters.

id: Number
The unique identifier for the network locality entry.
PATCH /networklocalities/{id}

Specify the following parameters.

body: Object
Apply the specified property value updates to the network locality entry.
id: Number
The unique identifier for the network locality entry.

Network

Networks are correlated to the network interface card that receives input from all of the objects identified by the ExtraHop system.

On an ExtraHop Command appliance, each connected sensor (Discover appliance) is identified as a network capture. For more information, see Networks.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /networks Retrieve all networks.
GET /networks/{id} Retreive a specific network by ID.
PATCH /networks/{id} Update a specific network by ID.
GET /networks/{id}/alerts Retrieve all alerts that are assigned to a specific network.
POST /networks/{id}/alerts Assign and unassign alerts to a specific network.
DELETE /networks/{id}/alerts/{child-id} Unassign an alert from a specific network.
POST /networks/{id}/alerts/{child-id} Assign an alert to a specific network.
GET /networks/{id}/pages Retrieve all pages that are assigned to a specific network.
POST /networks/{id}/pages Assign and unassign pages to a specific network.
DELETE /networks/{id}/pages/{child-id} Unassign a page from a specific network.
POST /networks/{id}/pages/{child-id} Assign a page to a specific network.
GET /networks/{id}/vlans Retrieve all VLANS assigned to a specific network.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /networks

There are no parameters for this operation.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "appliance_uuid": "string",
    "description": "string",
    "id": 0,
    "idle": true,
    "mod_time": 0,
    "name": "string",
    "node_id": 0
}
PATCH /networks/{id}

Specify the following parameters.

body: Object
Property value updates to apply to the network.
id: Number
Unique identifier of the network.
GET /networks/{id}

Specify the following parameters.

id: Number
Unique identifier of the network.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "appliance_uuid": "string",
    "description": "string",
    "id": 0,
    "idle": true,
    "mod_time": 0,
    "name": "string",
    "node_id": 0
}
GET /networks/{id}/alerts

Specify the following parameters.

id: Number
Unique identifier of the network.
direct_assignments_only: Boolean
(Optional) Restrict results to only alerts directly assigned to the network.
POST /networks/{id}/alerts

Specify the following parameters.

body: Object
Lists of alert IDs to assign and/or unassign.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
Unique identifier of the network.
POST /networks/{id}/alerts/{child-id}

Specify the following parameters.

child-id: Number
Unique identifier of the alert.
id: Number
Unique identifier of the network.
DELETE /networks/{id}/alerts/{child-id}

Specify the following parameters.

child-id: Number
Unique identifier of the alert.
id: Number
Unique identifier of the network.
GET /networks/{id}/vlans

Specify the following parameters.

id: Number
Unique identifier of the network.

Observations

An observation associates the IP address of a device on the ExtraHop system with an IP address outside of your network. For example, you can track the activity of a VPN user by associating the IP address of the VPN client on your internal network with the external IP address assigned to the user on the public internet.

The following table displays all of the operations you can perform on this resource:

Operation Description
POST /observations/associatedipaddrs Add an observation to create an association between device IP addresses.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

POST /observations/associatedipaddrs

Specify the following parameters.

body: Object
The observation parameters.
observations: Array of Objects
An array of observations.
ipaddr: String
The device IP address observed by the ExtraHop system.
associated_ipaddr: String
The associated IP address.
timestamp: Number
The time that the observation was created by the source, expressed in milliseconds since the epoch.
source: String
The source of the observations.

Specify the body parameter in the following JSON format.

{
    "observations": {
        "ipaddr": "string",
        "associated_ipaddr": "string",
        "timestamp": 0
    },
    "source": "string"
}

You can search for and download packets stored on the ExtraHop system. The downloaded packets can then be analyzed through a third-party tool, such as Wireshark.

Note:This resource can only retrieve packets stored on ExtraHop Trace appliances. To retrieve packets stored on a Discover appliance, see the Packet Capture resource.

For more information about Packets, see Packets.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /packets/search Search for packets by specifying parameters in a URL.
POST /packets/search Search for packets by specifying parameters in a JSON string.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /packets/search

Specify the following parameters.

output: String
(Optional) The output format. * `pcap` - .pcap file * `keylog_txt` - A keylog.txt file that can be loaded in wireshark to decode ssl packets. * `zip` - A zip file containing both a packets.pcap and keylog.txt.

The following values are valid:

  • pcap
  • keylog_txt
  • zip
limit_bytes: String
(Optional) The maximum number of bytes to return.
limit_search_duration: String
(Optional) The maximum amount of time to run the packet search. The default unit is milliseconds, but other units can be specified with a unit suffix. See the REST API Guide for supported time units and suffixes.
always_return_body: Boolean
(Optional) If you set this parameter to true, and the search does not match any packets, the system returns an empty packet capture file and an HTTP status of 200. If you set this parameter to false, and the search does not match any packets, the system returns no packet capture file and an HTTP status of 204.
from: String
The beginning timestamp of the time range the search will include, expressed in milliseconds since the epoch. A negative value specifies that the search will begin with packets captured at a time in the past. For example, specify -10m to begin the search with packets captured 10 minutes before the time of the request. Negative values can be specified with a time unit other than milliseconds, such as seconds or hours. See the REST API Guide for supported time units and suffixes.
until: String
(Optional) The ending timestamp of the time range the search will include, expressed in milliseconds since the epoch. A 0 value specifies that the search will end with packets captured at the time of the search. A negative value specifies that the search will end with packets captured at a time in the past. For example, specify -5m to end the search with packets captured 5 minutes before the time of the request. Negative values can be specified with a time unit other than milliseconds, such as seconds or hours. See the REST API Guide for supported time units and suffixes.
bpf: String
(Optional) The Berkeley Packet Filter (BPF) syntax for the packet search. For more information about BPF syntax, see the REST API Guide.
ip1: String
(Optional) Returns packets sent to or received by the specified IP address.
port1: String
(Optional) Returns packets sent from or received on the specified port.
ip2: String
(Optional) Returns packets sent to or received by the specified IP address.
port2: String
(Optional) Returns packets sent from or received on the specified port.
POST /packets/search

Specify the following parameters.

body: Object
The parameters of the packet search.
output: String
(Optional) The output format.

The following values are valid:

  • pcap
  • keylog_txt
  • zip
limit_bytes: String
(Optional) The maximum number of bytes to return.
limit_search_duration: String
(Optional) The maximum amount of time to run the packet search. The default unit is milliseconds, but other units can be specified with a unit suffix. See the REST API Guide for supported time units and suffixes.
always_return_body: Boolean
(Optional) If you set this parameter to true, and the search does not match any packets, the system returns an empty packet capture file and an HTTP status of 200. If you set this parameter to false, and the search does not match any packets, the system returns no packet capture file and an HTTP status of 204.
from: String
The beginning timestamp of the time range the search will include, expressed in milliseconds since the epoch. A negative value specifies that the search will begin with packets captured at a time in the past. For example, specify -10m to begin the search with packets captured 10 minutes before the time of the request. Negative values can be specified with a time unit other than milliseconds, such as seconds or hours. See the REST API Guide for supported time units and suffixes.
until: String
(Optional) The ending timestamp of the time range the search will include, expressed in milliseconds since the epoch. A 0 value specifies that the search will end with packets captured at the time of the search. A negative value specifies that the search will end with packets captured at a time in the past. For example, specify -5m to end the search with packets captured 5 minutes before the time of the request. Negative values can be specified with a time unit other than milliseconds, such as seconds or hours. See the REST API Guide for supported time units and suffixes.
bpf: String
(Optional) The Berkeley Packet Filter (BPF) syntax for the packet search. For more information about BPF syntax, see Filter packets with Berkeley Packet Filter syntax.
ip1: String
(Optional) Returns packets sent to or received by the specified IP address.
port1: String
(Optional) Returns packets sent from or received on the specified port.
ip2: String
(Optional) Returns packets sent to or received by the specified IP address.
port2: String
(Optional) Returns packets sent from or received on the specified port.

Specify the body parameter in the following JSON format.

{
    "always_return_body": true,
    "bpf": "string",
    "from": "string",
    "ip1": "string",
    "ip2": "string",
    "limit_bytes": "string",
    "limit_search_duration": "string",
    "output": "string",
    "port1": "string",
    "port2": "string",
    "until": "string"
}

Pairing

This resource enables you to generate a token required to connect a sensor (Discover appliance) to a Command appliance or Reveal(x) 360.

The following table displays all of the operations you can perform on this resource:

Operation Description
POST /pairing/token Generate a token required to connect the sensor to a Command appliance or Reveal(x) 360.

Operation details

POST /pairing/token

There are no parameters for this operation.

Report

A report is a PDF file of a dashboard that you can schedule for email delivery to one or more recipients. You can specify how often the report email is delivered and the time interval for dashboard data included in the PDF file.

Important:You can only schedule reports from an ExtraHop Command appliance.

Here are some important considerations about scheduled reports:

  • You can only create a report for dashboards that you own or have been shared with you. Your ability to create a report is determined by your user privileges. Contact your ExtraHop administrator for help.
  • Each report can only link to one dashboard.
  • If you created a report for a dashboard that was later deleted or became inaccessible to you, the scheduled email will continue to be sent to recipients. However, the email will not include the PDF file and will instead notify recipients that the dashboard is unavailable to the report owner.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /reports Retrieve all reports.
POST /reports Create a report.
DELETE /reports/{id} Delete a specific report.
GET /reports/{id} Retrieve a specific report.
PATCH /reports/{id} Update a specific report.
GET /reports/{id}/contents Retrieve the contents of a specific report.
PUT /reports/{id}/contents Replace the contents of a specific report.
POST /reports/{id}/emailgroups Change the email group assigned to a specific scheduled report.
GET /reports/{id}/emailgroups Retrieve a list of email groups assigned to a specific scheduled report.
DELETE /reports/{id}emailgroups/{group-id} Remove an email group from a specific scheduled report.
POST /reports/{id}emailgroups/{group-id} Add an email group to a specific scheduled report.
POST /reports/{id}/queue Immediately generate and send a specific report.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /reports

There are no parameters for this operation.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "cc": [],
    "description": "string",
    "email_message": "string",
    "email_subject": "string",
    "enabled": true,
    "from": "string",
    "id": 0,
    "include_links": "string",
    "name": "string",
    "output": {},
    "owner": "string",
    "schedule": {},
    "until": "string"
}
POST /reports

Specify the following parameters.

body: Object
The contents of the report.
name: String
The name of the report.
description: String
(Optional) The description of the report.
owner: String
The username of the report owner.
cc: Array of Strings
The list of email addresses, not included in an email group, to receive reports.
enabled: Boolean
(Optional) Indicates whether the report is enabled.
from: String
The beginning timestamp of the time interval for the report contents, relative to the current time and expressed in milliseconds.
until: String
(Optional) The ending timestamp of the time interval for the report contents, relative to the current time and expressed in milliseconds.
email_subject: String
(Optional) The content of the subject line for the report email.
schedule: Object
(Optional) The object containing the parameters that specify the scheduled time range to generate and send the report. The parameters are defined in the schedule_type section below.
type: String
The type of delivery schedule for the report.

The following values are valid:

  • hourly
  • daily
  • weekly
at: Array of Objects
(Optional) The list of objects that specify the delivery parameters for the report. The parameters are defined in the at_type section below.
by_day: Array of Strings
(Optional) The days of the week to send the report.

The following values are valid:

  • mo
  • tu
  • we
  • th
  • fr
  • sa
  • su
tz: String
(Optional) The timezone in which to send the report.
hour: Number
(Optional) The hour at which to send the report.
minute: Number
(Optional) The minute at which to send the report.
output: Object
The object containing the parameters that specify the output format for the report. The parameters are defined in the format_type section below.
type: String
The output format for the report.

The following values are valid:

  • pdf
width: String
(Optional) The width option for the report output.

The following values are valid:

  • narrow
  • medium
  • wide
pagination: String
(Optional) The pagination scheme for the report output.

The following values are valid:

  • per_region
theme: String
(Optional) The display theme for the report output.

The following values are valid:

  • light
  • dark
  • space
  • contrast

Specify the body parameter in the following JSON format.

{
    "cc": [],
    "description": "string",
    "email_subject": "string",
    "enabled": true,
    "from": "string",
    "name": "string",
    "output": {
        "type": "string",
        "width": "string",
        "pagination": "string",
        "theme": "string"
    },
    "owner": "string",
    "schedule": {
        "type": "string",
        "at": {
            "by_day": [],
            "tz": "string",
            "hour": 0,
            "minute": 0
        }
    },
    "until": "string"
}
POST /reports/{id}/queue

Specify the following parameters.

id: Number
The unique identifier for the report.
PATCH /reports/{id}

Specify the following parameters.

id: Number
The unique identifier for the report.
body: Object
The contents of the report.
name: String
The name of the report.
description: String
(Optional) The description of the report.
owner: String
The username of the report owner.
cc: Array of Strings
The list of email addresses, not included in an email group, to receive reports.
enabled: Boolean
(Optional) Indicates whether the report is enabled.
from: String
The beginning timestamp of the time interval for the report contents, relative to the current time and expressed in milliseconds.
until: String
(Optional) The ending timestamp of the time interval for the report contents, relative to the current time and expressed in milliseconds.
email_subject: String
(Optional) The content of the subject line for the report email.
schedule: Object
(Optional) The object containing the parameters that specify the scheduled time range to generate and send the report. The parameters are defined in the schedule_type section below.
type: String
The type of delivery schedule for the report.

The following values are valid:

  • hourly
  • daily
  • weekly
at: Array of Objects
(Optional) The list of objects that specify the delivery parameters for the report. The parameters are defined in the at_type section below.
by_day: Array of Strings
(Optional) The days of the week to send the report.

The following values are valid:

  • mo
  • tu
  • we
  • th
  • fr
  • sa
  • su
tz: String
(Optional) The timezone in which to send the report.
hour: Number
(Optional) The hour at which to send the report.
minute: Number
(Optional) The minute at which to send the report.
output: Object
The object containing the parameters that specify the output format for the report. The parameters are defined in the format_type section below.
type: String
The output format for the report.

The following values are valid:

  • pdf
width: String
(Optional) The width option for the report output.

The following values are valid:

  • narrow
  • medium
  • wide
pagination: String
(Optional) The pagination scheme for the report output.

The following values are valid:

  • per_region
theme: String
(Optional) The display theme for the report output.

The following values are valid:

  • light
  • dark
  • space
  • contrast

Specify the body parameter in the following JSON format.

{
    "cc": [],
    "description": "string",
    "email_subject": "string",
    "enabled": true,
    "from": "string",
    "name": "string",
    "output": {
        "type": "string",
        "width": "string",
        "pagination": "string",
        "theme": "string"
    },
    "owner": "string",
    "schedule": {
        "type": "string",
        "at": {
            "by_day": [],
            "tz": "string",
            "hour": 0,
            "minute": 0
        }
    },
    "until": "string"
}
GET /reports/{id}

Specify the following parameters.

id: Number
The unique identifier for the report.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "cc": [],
    "description": "string",
    "email_message": "string",
    "email_subject": "string",
    "enabled": true,
    "from": "string",
    "id": 0,
    "include_links": "string",
    "name": "string",
    "output": {},
    "owner": "string",
    "schedule": {},
    "until": "string"
}
DELETE /reports/{id}

Specify the following parameters.

id: Number
The unique identifier for the report.
GET /reports/{id}/contents

Specify the following parameters.

id: Number
The unique identifier for the report.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "dashboard_id": 0,
    "params": {},
    "type": "string"
}
REPLACEALL /reports/{id}/contents

Specify the following parameters.

id: Number
The unique identifier for the report.
body: Object
The contents of the report.
POST /reports/{id}/emailgroups/{group-id}

Specify the following parameters.

id: Number
The unique identifier for the report.
group-id: Number
The unique identifier for the email group.
POST /reports/{id}/emailgroups

Specify the following parameters.

id: Number
The unique identifier for the report.
body: Object
The list of email group IDs to assign or unassign to the report.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
GET /reports/{id}/emailgroups

Specify the following parameters.

id: Number
The unique identifier for the report.
DELETE /reports/{id}/emailgroups/{group-id}

Specify the following parameters.

id: Number
The unique identifier for the report.
group-id: Number
The unique identifier for the email group.

Software

You can view a list of software that the ExtraHop system has observed on your network.

Operation Description
GET /software Retrieve software observed by the ExtraHop system.
GET /software/{id} Retrieve software observed by the ExtraHop system by ID.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /software

Specify the following parameters.

software_type: String
(Optional) The type of software.
name: String
(Optional) The name of the software.
version: String
(Optional) The version of the software.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "description": "string",
    "id": "string",
    "name": "string",
    "software_type": "string",
    "version": "string"
}
GET /software/{id}

Specify the following parameters.

id: String
The unique identifier for the software.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "description": "string",
    "id": "string",
    "name": "string",
    "software_type": "string",
    "version": "string"
}

Tag

Device tags enable you to associate a device or group of devices by some characteristic.

For example, you might tag all of your HTTP servers or tag all of the devices that are in a common subnet. For more information, see Tag a device through the REST API.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /tags Retrieve all tags.
POST /tags Create a a new tag.
DELETE /tags/{id} Delete a specific tag.
GET /tags/{id} Retrieve a specific tag.
PATCH /tags/{id} Apply updates to a specific tag.
GET /tags/{id}/devices Retrieve all devices that are assigned to a specific tag.
POST /tags/{id}/devices Assign and unassign a specific tag to devices.
DELETE /tags/{id}/devices/{child-id} Unassign a device from a specific tag.
POST /tags/{id}/devices/{child-id} Assign a device to a specific tag.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /tags

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "id": 0,
    "mod_time": 0,
    "name": "string"
}
POST /tags

Specify the following parameters.

body: Object
Apply the specified property values to the new tag.
name: String
The string value for the tag.

Specify the body parameter in the following JSON format.

{
    "name": "string"
}
GET /tags/{id}

Specify the following parameters.

id: Number
The unique identifier for the tag.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "id": 0,
    "mod_time": 0,
    "name": "string"
}
DELETE /tags/{id}

Specify the following parameters.

id: Number
The unique identifier for the tag.
PATCH /tags/{id}

Specify the following parameters.

body: Object
Apply the specified property value updates to the tag.
id: Number
The unique identifier for the tag.
GET /tags/{id}/devices

Specify the following parameters.

id: Number
The unique identifier for the tag.
POST /tags/{id}/devices

Specify the following parameters.

body: Object
Lists of unique identifies for device to assign and unassign.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the tag.
POST /tags/{id}/devices/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device.
id: Number
the unique identifier for the tag.
DELETE /tags/{id}/devices/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device.
id: Number
The unique identifier for the tag.

Threat Collection

The Threat Collection resource enables you to upload Structured Threat Information eXpression (STIX) files to threat collections in your Reveal(x) system. STIX files must be obtained from a TAXII server or threat intelligence platform in TAR or TAR.GZ format, and then uploaded to your Reveal(x) system.

Note:This topic applies only to ExtraHop Reveal(x) Premium and Ultra.

For information about uploading STIX files through the ExtraHop Web UI, see Upload STIX files through the REST API.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /threatcollections Retrieve all threat collections.
DELETE /threatcollections/{id} Delete a threat collection.
PUT /threatcollections/{id} Upload a new threat collection. ExtraHop currently supports STIX versions 1.0 - 1.2.
Note:If a threat collection with the same name already exists on the ExtraHop system, the existing threat collection is overwritten.
GET /threatcollections/{id}/observables Retrieve the number of STIX observables loaded from a threat collection, such as IP address, hostname, or URI.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /threatcollections

There are no parameters for this operation.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "id": 0,
    "last_updated": 0,
    "name": "string",
    "observables": 0,
    "user_key": "string"
}
POST /threatcollections

Specify the following parameters.

user_key: String
(Optional) The user-supplied identifier for the threat collection. If this parameter is not specified, the threat collection name is set for this value, without spaces or punctuation.
name: String
The name for the threat collection.
file: Filename
The filename for the threat collection.
PUT /threatcollections/~{userKey}

Specify the following parameters.

userKey: String
The user-supplied identifier for the threat collection.
name: String
(Optional) The name for the threat collection.
file: Filename
(Optional) The filename for the threat collection.
DELETE /threatcollections/{id}

Specify the following parameters.

id: String
The unique identifier for the threat collection.
GET /threatcollections/{id}/observables

Specify the following parameters.

id: String
The unique identifier for the threat collection.

Trigger

Triggers are custom scripts that perform an action upon a pre-defined event.

For example, you can write a trigger to record a custom metric every time an HTTP request occurs, or classify traffic for a particular server as an Application server. For more information, see the Trigger API Reference. For supplemental implementation notes about advanced options, see Advanced trigger options.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /triggers Retrieve all triggers.
POST /triggers Create a new trigger.
POST triggers​/externaldata Sends data to the Trigger API by running the EXTERNAL_DATA event. You can access the data through the ExternalData trigger class.
DELETE /triggers/{id} Delete a specific identifier.
GET /triggers/{id} Retrieve a specific trigger by unique identifier.
PATCH /triggers/{id} Update an existing trigger.
GET /triggers/{id}/devicegroups Retrieve all device groups that are assigned to a specific trigger.
POST /triggers/{id}/devicegroups Assign and unassign a specific trigger to device groups.
DELETE /triggers/{id}/devicegroups/{child-id} Unassign a device group from a specific trigger.
POST /triggers/{id}/devicegroups/{child-id} Assign a device group to a specific trigger.
GET /triggers/{id}/devices Retrieve all devices that are assigned to a specific trigger.
POST /triggers/{id}/devices Assign and unassign a specific trigger to devices.
DELETE /triggers/{id}/devices/{child-id} Unassign a device from a specific trigger.
POST /triggers/{id}/devices/{child-id} Assign a device to a specific trigger.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /triggers

There are no parameters for this operation.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "apply_all": true,
    "author": "string",
    "debug": true,
    "description": "string",
    "disabled": true,
    "event": "string",
    "events": [
        "string"
    ],
    "hints": {},
    "id": 0,
    "mod_time": 0,
    "name": "string",
    "script": "string"
}
DELETE /triggers/{id}

Specify the following parameters.

id: Number
The unique identifier for the trigger.
POST /triggers/externaldata

Specify the following parameters.

body: Object
The object containing the data to send to triggers through the EXTERNAL_DATA event.
type: String
A string identifier that describes the data contained in the body parameter. For example, you could specify 'phantom-data' for data sent from the Phantom SOAR platform.
body: Object
The data to send to triggers through the EXTERNAL_DATA event. This data can be accessed in the trigger with the 'ExternalData.body' property.

Specify the body parameter in the following JSON format.

{
    "body": {},
    "type": "string"
}
POST /triggers

Specify the following parameters.

body: Object
The property values for the new trigger.
name: String
The friendly name for the trigger.
description: String
(Optional) An optional description of the trigger.
author: String
The name of the creator of the trigger.
script: String
The JavaScript content of the trigger.
event: String
(Optional) Deprecated. Replaced by the events field.
events: Array of Strings
The list of events on which the trigger runs, expressed as a JSON array.
disabled: Boolean
Indicates whether the trigger can run.
debug: Boolean
Indicates whether debug statements are printed for the trigger.
apply_all: Boolean
Indicates whether the trigger applies to all relevant resources.
hints: Object
Options that are based on selected trigger events. For more information about the hints object, see the REST API Guide.

Specify the body parameter in the following JSON format.

{
    "apply_all": true,
    "author": "string",
    "debug": true,
    "description": "string",
    "disabled": true,
    "event": "string",
    "events": [
        "string"
    ],
    "hints": {},
    "name": "string",
    "script": "string"
}
PATCH /triggers/{id}

Specify the following parameters.

body: Object
The property value updates for the trigger.
id: Number
The unique identifier for the trigger.
GET /triggers/{id}

Specify the following parameters.

id: Number
The unique identifier for the trigger.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "apply_all": true,
    "author": "string",
    "debug": true,
    "description": "string",
    "disabled": true,
    "event": "string",
    "events": [
        "string"
    ],
    "hints": {},
    "id": 0,
    "mod_time": 0,
    "name": "string",
    "script": "string"
}
GET /triggers/{id}/devicegroups

Specify the following parameters.

id: Number
The unique identifier for the trigger.
POST /triggers/{id}/devicegroups

Specify the following parameters.

body: Object
A list of unique identifiers for device groups that are assigned and unassigned to a trigger.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the trigger.
POST /triggers/{id}/devicegroups/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device group.
id: Number
The unique identifier for the trigger.
DELETE /triggers/{id}/devicegroups/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device group.
id: Number
The unique identifier for the trigger.
GET /triggers/{id}/devices

Specify the following parameters.

id: Number
The unique identifier for the trigger.
POST /triggers/{id}/devices

Specify the following parameters.

body: Object
A list of unique identifiers for devices that are assigned and unassigned to a trigger.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the body parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
id: Number
The unique identifier for the trigger.
POST /triggers/{id}/devices/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device.
id: Number
The unique identifier for the trigger.
DELETE /triggers/{id}/devices/{child-id}

Specify the following parameters.

child-id: Number
The unique identifier for the device.
id: Number
The unique identifier for the trigger.

VLAN

Virtual LANs are logical groupings of traffic or devices on the network.

The following table displays all of the operations you can perform on this resource:

Operation Description
GET /vlans Retrieve all VLANs
GET /vlans/{id} Retrieve a specific VLAN.
PATCH /vlans/{id} Update a specific VLAN.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /vlans

There are no parameters for this operation.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "description": "string",
    "id": 0,
    "mod_time": 0,
    "name": "string",
    "network_id": 0,
    "node_id": 0,
    "vlanid": 0
}
GET /vlans/{id}

Specify the following parameters.

id: Number
The unique identifier for the VLAN.

If the request is successful, the ExtraHop system returns an object in the following format.

{
    "description": "string",
    "id": 0,
    "mod_time": 0,
    "name": "string",
    "network_id": 0,
    "node_id": 0,
    "vlanid": 0
}
PATCH /vlans/{id}

Specify the following parameters.

body: Object
Apply the specified property value updates to the VLAN.
id: Number
The unique identifier for the VLAN.

Watchlist

To guarantee that an asset, such as an important server, database, or laptop, is guaranteed Advanced Analysis, you can add that device to the watchlist.

Tip:If you want to add several devices to the watchlist, consider creating a device group and then prioritizing that group for Advanced Analysis.

Here are important considerations about the watchlist:

  • The watchlist only applies to Advanced Analysis.
  • The watchlist can contain as many devices as allowed by the Advanced Analysis capacity, which is determined by your license.
  • A device stays on the watchlist whether it is inactive or active. A device has to be active for the ExtraHop system to collect Advanced Analysis metrics.

For more information about Advanced Analysis, see Analysis levels.

The following table displays all of the operations you can perform on this resource:

Operation Description
DELETE /watchlist/device/{id} Remove a device from the watchlist.
POST /watchlist/device/{id} Add a device to the watchlist.
GET /watchlist/devices Retrieve all devices that are in the watchlist.
POST /watchlist/devices Add or remove devices from the watchlist.

Implementation information and instructions for each operation are documented in the REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Operation details

GET /watchlist/devices

There are no parameters for this operation.

POST /watchlist/device/{id}

Specify the following parameters.

id: Number
The unique identifier for the device.
DELETE /watchlist/device/{id}

Specify the following parameters.

id: Number
The unique identifier for the device.
POST /watchlist/devices

Specify the following parameters.

assignments: Object
A list of devices to add to or remove from the watchlist.
assign: String
IDs of resources to assign
unassign: String
IDs of resources to unassign

Specify the assignments parameter in the following JSON format.

{
    "assign": "string",
    "unassign": "string"
}
Published 2021-04-13 10:05