Thank you!
We will contact you soon to
ask how we can improve our documentation.We appreciate your feedback.

Was this topic helpful?

YesNo

Thank you for your feedback. Can we contact you to ask follow up questions?

*Please enter a valid email address

How can we improve?

ExtraHop REST API Guide

Introduction to ExtraHop REST API

The ExtraHop REST application programming interface (API) enables you to automate
administration and configuration tasks on your ExtraHop Discover and Command appliances. You can
send requests to the ExtraHop API through a Representational State Transfer (REST) interface,
which is accessed through resource URIs and standard HTTP methods.

You can automate administration tasks, such as configuring LDAP authentication, saving
customizations, applying SSL decrypt keys, and managing support packs. And, you can automate
configuration tasks, such as creating alerts, or writing triggers.

When a REST API request is sent over HTTPS to an ExtraHop appliance, that request is
authenticated and then authorized through an API key. After authentication, the request is
submitted to the ExtraHop system and the operation completes.

In addition, you can access the built in ExtraHop API Explorer tool through the Discover and
Command appliances, which enables you to view all of the available system resources, methods,
properties, and parameters. In addition, you can test out API calls directly on your ExtraHop
appliance.

Note:

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

ExtraHop API requirements

Before you can begin coding against the ExtraHop REST API or performing operations
through the ExtraHop API Explorer, you must meet the following requirements:

Your ExtraHop appliance must be configured to allow API key generation for the type of user
you are (remote or local).

You must have a user account with appropriate privileges set for the type of tasks you want
to perform.

You must have access to the ExtraHop appliance.

Get started

If you have a user account for your ExtraHop appliance, you can connect to the
ExtraHop API Explorer and begin browsing through the available resources.

From the ExtraHop Web UI, click the User icon, and then select API
Access.

Access and authenticate to the ExtraHop REST API

Administrators, or users with full system privileges, control whether users can generate
API keys. For example, you can prevent remote users from generating keys or you can disable API
key generation entirely. When this functionality is enabled, API keys are generated by users and
can be viewed only by the user who generated the key.

Note:

Administrators set up user accounts, and then users generate their own API key. Users can
delete API keys for their own account, and users with full system privileges can delete API keys
for any user. For more information, see the Users section in the ExtraHop Admin UI Guide.

After you generate an API key, you must append the key to your request headers. The following
example shows a request that would retrieve all of the alerts set on the ExtraHop system:

Generate an API key

After you log into the ExtraHop appliance, if API key generation is enabled, you can
generate an API key.

In the Access Settings section, click API
Access.

In the API Keys section, type a description for the key,
and then click Generate.

Copy the API key and paste the key into the REST API Explorer or append the key
to a request header.

Delete an API Key

You can delete an API key from the ExtraHop appliance.

In the Access Settings section, click API
Access.

In the Keys section, click the delete (X) icon next to the
API key you want to delete.

Click OK.

Enable CORS for the ExtraHop REST API

Cross-origin resource sharing (CORS) allows you to access the ExtraHop REST API from
specified web pages without requiring the request to travel through a proxy server, which provides
access to content across domain-boundaries.

You can configure one or more allowed origins or you can allow access to the ExtraHop REST API
from any origin. Only administrative users can view and edit CORS settings.

View CORS settings

You can view CORS settings from the ExtraHop Admin UI.

Log into the ExtraHop Admin UI through the following URL:
https://<hostname-or-IP-of-your-ExtraHop-appliance>/admin

In the Access Settings section, click API Access.

The CORS Settings section displays the following settings:

The list of URLs that can access the REST API.

The status of the Allow API requests from any
Origin option.

Add an allowed origin

You can configure one or more allowed origins or you can allow access to the ExtraHop
REST API from any origin.

Log into the ExtraHop Admin UI.

In the Access Settings section, click API Access.

In the CORS Settings section, specify one of the following access
configurations.

To add a specific URL, type an origin URL in the text box, and then
click the plus (+) icon or press ENTER.

The URL must include a scheme,
such as HTTP or HTTPS, and the exact domain name. You cannot append a
path; however, you can provide a port number.

To allow access from any URL, select the Allow API requests
from any Origin checkbox.

Note:

Allowing REST API access from
any origin is less secure than providing a list of explicit origins.

Click Save Settings.

Delete an allowed origin

You can delete a URL from the list of allowed origins or disable access from all
origins.

Log into the ExtraHop Admin UI.

In the Access Settings section, click API Access.

In the CORS Settings section, modify one of the following access configurations.

To delete a specific URL, click the delete (X) icon next to the origin you want to
delete.

To disable access from any URL, clear the Allow API requests from any
Origin checkbox.

Click Save Settings.

Learn about the ExtraHop REST API Explorer

The ExtraHop API Explorer is a web-based tool that enables you to view detailed
information about the ExtraHop REST API resources, methods, parameters, properties, and error
codes. Code samples are available in Python, cURL, and Ruby for each resource. You also can
perform operations directly through the tool, which are performed on your ExtraHop and return
information about your network.

Note:

Be cautious when clicking the Try it out! button, because the
operation is performed on your ExtraHop appliance.

View resource information

Click on any resource group in the ExtraHop REST API Explorer to view information about
the available methods and the expected URL syntax for the resource.

The following options enable you to manage the information displayed on the main page.

Show/Hide:
Expands and collapses information about the resource.

List Operations:
Expands information about the resource operations.

Expand Operations:
Expands information about all of the resource operations. Clicking the method or path of the
expanded operation will collapse the additional information.

View operation information

Click on any operation to view additional configuration information for the resource.
The following table provides information about the sections available for resources in the
ExtraHop API Explorer. Section availability varies by HTTP method; not all methods have all of
the sections listed in the table.

Section

Description

Implementation Notes

Provides all of the fields for the request body and supported values for each
field.

Response Class

Provides the response code and type for successful requests.

Parameters

Provides information about the available query parameters.

Response Messages

Provides additional information about the possible HTTP status codes for the
resource.

GET requests

GET requests retrieve information about the objects in the associated resource. You can
request information about all of the objects in a resource or you can specify an object ID to
retrieve detailed information about only that object.

GET example: Retrieve a list of devices

Retrieve a list of devices on the ExtraHop system through the ExtraHop API
Explorer.

Click Device, and then click GET
/devices.

In the Parameters section, modify the fields to build your
query. For example, the default limit parameter restricts the number of devices
returned to 100.

Click the Try it out! button. A successful GET request
returns a response body with the number of devices specified in the limit
parameter. A failed GET request returns the response body with an error.

GET example: Retrieve specific device information

Retrieve information only about a specific device. You must have a device ID, which
you can retrieve from the previous example.

Click Device, and then click GET
/devices/{id}.

In the Parameters section, in the
id field, type the device ID.

Click the Try it out! button. A successful GET request
returns a response body with information about the specified device. A failed
GET request returns the response body with an error.

POST requests

POST requests create objects and queries for the associated resource.

POST example: Create a custom dynamic FTP device group

Create a custom dynamic FTP device group on the ExtraHop system through the ExtraHop
API Explorer.

Click Device Group, and then click POST
/devicegroups.

Click on Model to see descriptions for optional and
required fields.

Click on Model Schema, and then click in the box to
automatically add the schema to the body parameter.

Edit the JSON fields. In the following example, the
dynamic parameter is set to true, the
field parameter is set to type and the
value parameter is set to
/^extrahop.device.ftp_servers$/.

Patch requests

PATCH example: Modify a device group

Modify a custom dynamic FTP device group on the ExtraHop system through the ExtraHop
API Explorer.

Click Device Group and then click PATCH
/devicegroups/{id}.

In the id parameter, type the ID for the device group.
From the POST example above, the device group ID is 151.

Add and modify only the fields that you want to change to the body parameter.
For example, to add a name for the device group that was created in the example
above, type:

{
"name": "FTP Servers"
}

Click Try it out!

DELETE requests

DELETE requests remove objects from the system. You must have an object ID to perform a
DELETE operation.

DELETE example: Delete a device group

Delete a custom dynamic FTP device group on the ExtraHop system through the ExtraHop
API Explorer.

Click Device Group, and then click DELETE
/devicegroups/{id}.

In the id parameter, type the ID of the device group you
want to delete. In the POST example above, the device group ID is 151.

Click Try it out!

The device group is deleted from your ExtraHop appliance. A status code of 204 is
returned upon success.

PUT requests

For limited operations, you can erase and replace the content in a resource with a PUT
request.

PUT example: Overwrite a product key

Erase and replace the license product key on the ExtraHop system through the ExtraHop
API Explorer.

Click Licenses and then click PUT
/licenses/productkey.

Click in the Model Schema box to add the schema to the
product_key parameter.

Replace the string with your product key.

Click Try it out!

A status code of 204 is returned upon success.

Learn about the ExtraHop REST API

The ExtraHop REST API enables you to automate tasks for the ExtraHop Web UI and Admin
UI. In addition, you can view and try all of the available resources through the ExtraHop REST API
Explorer and perform operations directly on your ExtraHop appliance.

ExtraHop API resources

You can perform operations on the following resources through the ExtraHop REST API. You
also can view more detailed information about these resources, such as available HTTP methods,
query parameters, and object properties in the ExtraHop REST API Explorer.

Activity group

Activity groups classify devices automatically based on their network traffic.

You can retrieve IDs for all activity groups and then perform additional operations on a group
that is associated with a single ID.

For example, activity group IDs can be added to Metric queries to retrieve metrics
simultaneously for a group of devices.

Alert

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

Threshold alerts can be set to alert you if a metric crosses the value defined in the alert.
Trend alerts cannot be configured through the REST API.

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.

Audit log

The audit log displays a record of all recorded system administration and configuration
activity.

The log displays the time of the activity, the user who performed the activity, the operation,
operation details, and system component.

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 appliance,
or save the bundle as a backup. Bundles can also be downloaded from ExtraHop
Solution Bundles and applied through the REST API.

Custom device

You can create a custom device by defining a set of rules.

For example, you can create a custom device that has an IP address on a specified VLAN. By
default, all IP addresses outside of the locally-monitored broadcast domains are aggregated
behind a router. To identify devices that are behind that router, you can create a custom device,
and then collect metrics from the device.

Customization

Similar to Bundles, customizations enable you to save ExtraHop configurations for
backup. Unlike with Bundles, however, you cannot select the information that is contained in a
Customization.

All of the major system changes are saved as a JSON-formatted document and can be uploaded to a
restored or new ExtraHop appliance. Customizations are accessible only to users with Full System
Permissions.

Dashboards

Device

Devices are objects on your network that have been identified and classified by your
ExtraHop appliance.

Device group (or custom group)

Device groups can be either static or dynamic.

A static device group is user-defined; you create a custom 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 custom group and then set a rule to classify all devices within a
certain IP address range to be added to that group automatically.

Email group

You can add individual or group email addresses to an email group and assign them to a
system alert. When that alert is triggered, the system sends an email to all of the addresses in
the email group.

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.

ExtraHop

This resource provides metadata about the ExtraHop appliance, such as the firmware
version or if the appliance is a Command appliance.

Flex Grid

A Flex Grid provides a table view of metrics information about devices.

Geomap

Geomaps display metrics across a global map, which indicates where metrics activity has
occurred.

License

This resource enables you to retrieve and set product keys or to retrieve and set a
license.

Metrics

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

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

You can identify all of the required fields and supported values in the Implementation
Notes.

Network

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

On an ExtraHop Command appliance, each node is identified as a network capture that is looking
at the traffic for each ExtraHop Discover node that is connected to the Command cluster.

Node

A node is defined by its relationship to an ExtraHop Command appliance. The environment
which contains Discover nodes and a Command appliance is called a Command cluster.

Packet capture

Packet captures store packets from a network traffic flow.

You must write a trigger to identify the information you want to generate. For example, you can
write a trigger to collect all of the packets going to a particular device that is generating a
high volume of errors. Then, you can download or delete that information.

Pages

Pages provide a template for creating a customized view of built-in metrics or metrics
collected from triggers.

Record Log

Records are structured flow and transaction information about events on your network.
After you link an ExtraHop Discover appliance to an ExtraHop Explore appliance, you can generate
and send record information to the Explore appliance for storage, and you can query records to
retrieve stored information about any object on your network.

Running config

The running config is a JSON document that contains core system configuration
information for the ExtraHop appliance.

SSL decrypt key

This resource enables you to add a decryption key for your network traffic.

Support pack

A support pack is a file that contains configuration adjustments provided by ExtraHop
Support.

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.

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.

User

This resource enables you to create and manage the list of users who have access to the
ExtraHop appliance and their permission levels.

VLAN

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

Whitelist

A whitelist prioritizes devices that are added after the device limit is reached.
When the device limit is reached, any new devices that are added are placed in limited
analysis mode.

If you want to prioritize a device, you can add that device to the whitelist. Devices
are removed from the ExtraHop device list based on seniority; the latest devices are
removed first.

Identify objects on the ExtraHop system

Objects on the ExtraHop system can be identified by any unique value, such as the IP
address, MAC address, name, or system ID. To perform API operations on a specific object, you must
locate the object ID.

You can locate an object ID through the following methods:

The object ID is provided in the headers returned from a POST request. For example, if you
send a POST request to create a page, the response headers display a location URL, such
as:

The
location for the newly created page is /api/v1/pages/221 and the ID for the page is
221.

The object ID is provided for all objects returned from a GET request. For example, if you
perform a GET request on all devices, the response body contains information for each device,
including the ID.

The following response body displays an entry for a single device, with an
ID of
10212:

To
perform further requests on a specific device, add the ID in the request for that
device.

The object ID is provided in the URL for most objects. For example, in the ExtraHop Web UI,
click on Metrics, and then Devices. Select any device. The URL for that device page displays an
OIDD=< number>, such
as:

You
can also find the short_code in Dashboard Properties in the command menu from any
dashboard.

View ExtraHop REST API implementation notes

This section contains supplemental implementation notes to the ExtraHop REST API. These
notes provide additional conceptual or reference information to help you configure certain
parameters or options.

Advanced trigger options

Advanced trigger options are configuration options that you can set depending on the
system events associated with the trigger. For example, you can configure the number of payload
bytes to buffer on HTTP request events.

Advanced options are contained in the hints object of the trigger resource
as shown in the following example:

Example 4: Create, retrieve, and delete an object

This example shows how you can create and successfully retrieve information about a
device tag. Then, after the device tags are deleted, the example shows how an attempt to
retrieve information subsequently fails.

The following example shows how to create a device tag called my_test_tag.