Viewer v3.x - v5.x API

This API is not final and is subject to change.

This is the documentation for version 3.x - 5.x. Here is the the API for previous versions.

Arkime uses digest authentication for all API calls, so make sure you enable that in your library or curl command. The easiest way to learn how to make API calls is to open up your browser’s javascript console and observe the calls the Arkime UI is making, it uses all the same APIs.

Note: Many of the API endpoints require a db field name, which is not the same as what you would use in a search expression. The easiest way to see database field names is to click the owl within Arkime -> click the fields label on left -> click display the database fields.

/connections API

POST/GET - /api/connections

Builds an elasticsearch connections query. Gets a list of nodes and links and returns them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
srcField string "ip.src" The source database field name
dstField string "ip.dst:port" The destination database field name
baselineDate number 0 The baseline date range to compare connections against. Default is 0, disabled. Options include: 1x - 1 times query range. 2x - 2 times query range. 4x - 4 times query range. 6x - 6 times query range. 8x - 8 times query range. 10x - 10 times query range. 1 - 1 hour. 6 - 6 hours. 24 - 1 day. 48 - 2 days. 72 - 3 days. 168 - 1 week. 336 - 2 weeks. 720 - 1 month. 1440 - 2 months. 4380 - 6 months. 8760 - 1 year.
baselineVis string "all" Which connections to display when a baseline date range is applied. Default is all. Options include: ‘all’ - All Nodes: all nodes are visible. ‘actual’ - Actual Nodes: nodes present in the “current” timeframe query results are visible. ‘actualold’ - Baseline Nodes: nodes present in the “baseline” timeframe query results are visible. ‘new’ - New Nodes Only: nodes present in the “current” but NOT the “baseline” timeframe are visible. ‘old’ - Baseline Nodes Only: nodes present in the “baseline” but NOT the “current” timeframe are visible.

Returns:

Name Type Description
links array The list of links
nodes array The list of nodes

/connections/csv API

POST/GET - /api/connections/csv OR /api/connections.csv

Builds an elasticsearch connections query. Gets a list of nodes and links in csv format and returns them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
srcField string "ip.src" The source database field name
dstField string "ip.dst:port" The destination database field name

Returns:

Name Type Description
csv csv The csv with the connections requested

/crons API

GET - /api/crons

Retrieves periodic queries a user can view.

Returns:

Name Type Description
queries Array.<ArkimeQuery> A list of query objects.

/cron API

POST - /api/cron

Create a new periodic query.

Returns:

Name Type Description
success boolean Whether the create operation was successful.
text string The success/error message to (optionally) display to the user.
query ArkimeQuery The new query

/user/:key API

POST - /api/cron/:key

Update a periodic query.

Returns:

Name Type Description
success boolean Whether the update operation was successful.
text string The success/error message to (optionally) display to the user.
query ArkimeQuery The updated query object

/cron/:key API

DELETE - /api/cron/:key

Delete a periodic query.

Returns:

Name Type Description
success boolean Whether the delete operation was successful.
text string The success/error message to (optionally) display to the user.

/histories API

GET - /api/histories

Retrieves a list of histories, or user client requests to the APIs.

Parameters:

Param Type Default Description
date number 1 The number of hours of data to return (-1 means all data). Defaults to 1.
startTime number   If the date parameter is not set, this is the start time of data to return. Format is seconds since Unix EPOC.
stopTime number   If the date parameter is not set, this is the stop time of data to return. Format is seconds since Unix EPOC.
searchTerm string   The search text to filter the history list by.
length number 100 The number of items to return. Defaults to 1,000.
start number 0 The entry to start at. Defaults to 0.
sortField string "timestamp" The field to sort the results by.
desc string true Whether to sort the results descending or ascending. Default is descending.
userId string   The ID of a user to request history results for. Admin can retrieve all users. Normal users can only retrieve their own.

Returns:

Name Type Description
data Array.<History> The list of history results.
recordsTotal number The total number of history results stored.
recordsFiltered number The number of history items returned in this result.

/history/:id API

DELETE - /api/history/:id

Deletes a history entry (admin only).

Parameters:

Param Type Description
index string The OpenSearch/Elasticsearch index that the history item was stored in.

Returns:

Name Type Description
success boolean Whether the delete history operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt API

POST - /api/hunt

Creates a new hunt.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section
totalSessions number The number of sessions to search.
name string The name of the hunt (not unique).
size number The number of packets to search within each session.
src boolean Whether to search the source packets. Must search src or dst or both.
dst boolean Whether to search the destination packets. Must search src or dst or both.
type string Whether to search raw or reassembled packets.
search string The search text to search for within packets.
searchType string What type of search the text is. Options include: ascii - search for case insensitive ascii text. asciicase - search for case sensitive ascii text. hex - search for hex text. regex - search for text using safe regex. hexregex - search for text using safe hex regex.
notifier string The optional notifier name to fire when there is an error, or there are matches (every 10 minutes), or when the hunt is complete.
users string The comma separated list of users to be added to the hunt so they can view the results.

Returns:

Name Type Description
success boolean Whether the creation of the hunt was successful.
hunt Hunt The newly created hunt object.
invalidUsers array The list of users that could not be added to the hunt because they were invalid or nonexitent.

/hunts API

GET - /api/hunts

Retrieves a list of hunts.

Parameters:

Param Type Default Description
searchTerm string   The search text to search hunt results for.
length number 10000 The number of items to return. Defaults to 10000.
start number 0 The entry to start at. Defaults to 0
sortField string "created" The field to sort the hunt results by. Defaults to “created”.
desc string false Whether to sort the results in descending order. Default is ascending.
history string false Whether to return only finished hunts. Default is to return queued, paused, and running hunts.

Returns:

Name Type Description
runningJob Hunt If there is a hunt running, returns the currently running hunt object.
data Array.<Hunt> The list of hunts (either finished or queued/paused/running).
recordsTotal number The total number of hunts Arkime has.
recordsFiltered number The number of hunts returned in this result.

/hunt/:id API

DELETE - /api/hunt/:id

Delete a hunt.

Returns:

Name Type Description
success boolean Whether the delete hunt operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id/cancel API

PUT - /api/hunt/:id/cancel

Cancel a hunt. Finishes the hunt and puts it into the hunt history.

Returns:

Name Type Description
success boolean Whether the cancel hunt operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id/pause API

PUT - /api/hunt/:id/pause

Pause a hunt.

Returns:

Name Type Description
success boolean Whether the pause hunt operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id/play API

PUT - /api/hunt/:id/play

Play a hunt.

Returns:

Name Type Description
success boolean Whether the play hunt operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id/removefromsessions API

PUT - /api/hunt/:id/removefromsessions

Remove the hunt ID and name from matched sessions.

Returns:

Name Type Description
success boolean Whether the operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id API

PUT - /api/hunt/:id

Update a hunt - can only update description & roles

Parameters:

Param Type Description
hunt Hunt The new hunt data

Returns:

Name Type Description
success boolean Whether the operation was successful.
text string The success/error message to (optionally) display to the user.

/hunt/:id/users API

POST - /api/hunt/:id/users

Add user(s) to a hunt.

Parameters:

Param Type Description
users string Comma separated list of user ids to add to the hunt.

Returns:

Name Type Description
success boolean Whether the add users operation was successful.
users array The list of users that were added to the hunt.
invalidUsers array The list of users that could not be added to the hunt because they were invalid or nonexitent.

/hunt/:id/user/:user API

DELETE - /api/hunt/:id/user/:user

Remove user(s) from a hunt.

Returns:

Name Type Description
success boolean Whether the remove users operation was successful.
users array The list of users who have access to the hunt.
invalidUsers array The list of users that could not be removed from the hunt because they were invalid or nonexitent.

/fields API

GET - /api/fields

Gets available database field objects pertaining to sessions.

Parameters:

Param Type Default Description
array boolean false Whether to return an array of fields, otherwise returns a map

Returns:

Name Type Description
  array/map The map or list of database fields

/files API

GET - /api/files

Gets a list of PCAP files that Arkime knows about.

Parameters:

Param Type Default Description
length number 100 The number of items to return. Defaults to 500, Max is 10,000
start number 0 The entry to start at. Defaults to 0

Returns:

Name Type Description
data Array The list of files
recordsTotal number The total number of files Arkime knows about
recordsFiltered number The number of files returned in this result

/valueactions API

GET - /api/valueactions

Retrives the actions that can be preformed on meta data values.

Returns:

Name Type Description
  object The list of actions that can be preformed on data values.

/fieldactions API

GET - /api/fieldactions

Retrives the actions that can be preformed on fields.

Returns:

Name Type Description
  object The list of actions that can be preformed on fields.

/reversedns API

GET - /api/reversedns

Retrives the domain names associated with an IP address.

Parameters:

Param Type Description
ip string The IP to search domain names for.

Returns:

Name Type Description
domains string A comma separated string list of all the matching domain names.

/upload API

POST - /api/upload

Uploads PCAP files to Arkime. This API is really only useful for demo sites and very special cases. Instead you almost always should just run capture locally, which will be much more efficient and not duplicate the PCAP. See https://arkime.com/faq#how-do-i-import-existing-pcaps

Parameters:

Param Type Description
tags string A comma separated list of tags to add to each session created.

/clusters API

GET - /api/clusters

Retrieves a list of known configured Arkime clusters (if in Mulit Viewer mode).

Returns:

Name Type Description
active Array The active Arkime clusters.
inactive Array The inactive Arkime clusters.

/remoteclusters API

GET - /api/remoteclusters

Retrieves a list of known configured remote Arkime clusters.

Returns:

Name Type Description
remoteclusters Object Key/value pairs of remote Arkime clusters, the key being the name of the cluster

/appinfo API

GET - /api/appinfo

Retrieves information that the app uses on every page: eshealth, currentuser, views, remoteclusters, clusters, fields, fieldsmap, fieldshistory

Returns:

Name Type Description
eshealth ESHealth The OpenSearch/Elasticsearch cluster health status and information.
currentuser ArkimeUser The currently logged in user
views Array.<ArkimeView> A list of views accessible to the logged in user
remoteclusters Object A list of known remote Arkime clusters
clusters Array A list of known configured Arkime clusters (if in Mulit Viewer mode)
fields Array Available database field objects pertaining to sessions
fieldsmap Array Available database field objects pertaining to sessions
fieldshistory Object The user’s field history for the search expression input

/buildquery API

POST/GET - /api/buildquery

This API allows you to build the query that Arkime viewer would use so you can use yourself against OpenSearch/Elasticsearch.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Returns:

Name Type Description
query object The elasticsearch query
indices object The elasticsearch indices that contain sessions in this query

Example

Returns the OpenSearch/Elasticsearch query for all the sessions with the source IP of 1.2.3.4
  curl -v 'http://localhost:8005/api/buildquery?date=-1&expression=ip.src%3D%3D1.2.3.4'

/sessions API

POST/GET - /api/sessions OR /sessions.json

Return all the JSON formatted session data based on the query parameters.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Returns:

Name Type Description
map object The data to populate the sessions map
graph object The data to populate the sessions timeline graph
data array The list of sessions with the requested fields
recordsTotal number The total number of sessions Arkime knows about
recordsFiltered number The number of sessions matching query

Example

Returns all the sessions with the source IP of 1.2.3.4
  curl -v 'http://localhost:8005/api/sessions?date=-1&expression=ip.src%3D%3D1.2.3.4'

/sessions/csv API

POST/GET - /api/sessions/csv OR /sessions.csv

Return all the JSON formatted session data based on the query parameters.

Parameters:

Param Type Description
ids string Comma separated list of sessions to retrieve
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Returns:

Name Type Description
csv csv The csv with the sessions requested

Example

Returns all the sessions with the source IP of 1.2.3.4
  curl -v 'http://localhost:8005/api/sessions/csv?date=-1&expression=ip.src%3D%3D1.2.3.4'

/spiview API

POST/GET - /api/spiview

Builds an elasticsearch session query. Gets a list of field values with counts and returns them to the client.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section
spi string Comma separated list of db fields to return. Optionally can be followed by :{count} to specify the number of values returned for the field (defaults to 100).

Returns:

Name Type Description
map object The data to populate the sessions map
graph object The data to populate the sessions timeline graph
spi object The list of spi fields with values and counts
protocols object The list of protocols with counts
recordsTotal number The total number of sessions Arkime knows about
recordsFiltered number The number of sessions matching query

Example

Returns first 100 unique values for the destination.ip field for last 10 hours
  curl -v 'http://localhost:8005/api/spiview?spi=destination.ip:200&date=10

/spigraph API

POST/GET - /api/spigraph

Builds an elasticsearch session query. Gets a list of values for a field with counts and graph data and returns them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
exp string   The expression field to return data for. Either exp or field is required, field is given priority if both are present.
field string "node" The database field to return data for. Either exp or field is required, field is given priority if both are present.

Returns:

Name Type Description
map object The data to populate the main/aggregate spigraph sessions map
graph object The data to populate the main/aggregate spigraph sessions timeline graph
items array The list of field values with their corresponding timeline graph and map data
recordsTotal number The total number of sessions Arkime knows about
recordsFiltered number The number of sessions matching query

/spigraphhierarchy API

POST/GET - /api/spigraphhierarchy

Builds an elasticsearch session query. Gets a list of values for each field with counts and returns them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
exp string   Comma separated list of db fields to populate the graph/table.
strictly boolean false When set the entire session must be inside the date range to be observed, otherwise if it overlaps it is displayed. Overwrites the bounding parameter, sets bonding to ‘both’

Returns:

Name Type Description
hierarchicalResults object The nested data to populate the treemap or pie
tableResults array The list data to populate the table

/unique API

POST/GET - /api/unique

Builds an elasticsearch session query. Gets a list of unique field values (with or without counts) and sends them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
counts number 0 Whether to return counts with he list of unique field values. Defaults to 0. 0 = no counts, 1 - counts.
exp string   The expression field to return unique data for. Either exp or field is required, field is given priority if both are present.
field string   The database field to return unique data for. Either exp or field is required, field is given priority if both are present.

Returns:

Name Type Description
  string The list of unique fields (with counts if requested)

/multiunique API

POST/GET - /api/multiunique

Builds an elasticsearch session query. Gets an intersection of unique field values (with or without counts) and sends them to the client.

Parameters:

Param Type Default Description
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
counts number 0 Whether to return counts with he list of unique field values. Defaults to 0. 0 = no counts, 1 - counts.
exp string   Comma separated list of expression fields to return unique data for.

Returns:

Name Type Description
  string The list of an intersection of unique fields (with counts if requested)

/session/:nodeName/:id/detail API

GET - /api/session/:nodeName/:id/detail

Gets SPI data for a session.

Returns:

Name Type Description
  html The html to display as session detail

/session/:nodeName/:id/packets API

GET - /api/session/:nodeName/:id/packets

Gets packets for a session.

Returns:

Name Type Description
  html The html to display as session packets

/sessions/addtags API

POST - /api/sessions/addtags

Add tag(s) to individual session(s) by id or by query.

Parameters:

Param Type Default Description
tags string   Comma separated list of tags to add to session(s)
ids string   Comma separated list of sessions to add tag(s) to
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
segments string "no" Whether to add tags to linked session segments. Default is no. Options include: no - Don’t add tags to linked segments all - Add tags to all linked segments time - Add tags to segments occurring in the same time period

Returns:

Name Type Description
success boolean Whether the add tags operation was successful
text string The success/error message to (optionally) display to the user

/sessions/removetags API

POST - /api/sessions/removetags

Removes tag(s) from individual session(s) by id or by query.

Parameters:

Param Type Default Description
tags string   Comma separated list of tags to remove from session(s)
ids string   Comma separated list of sessions to remove tag(s) from
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
segments string "no" Whether to remove tags from linked session segments. Default is no. Options include: no - Don’t remove tags from linked segments all - Remove tags from all linked segments time - Remove tags from segments occurring in the same time period

Returns:

Name Type Description
success boolean Whether the remove tags operation was successful
text string The success/error message to (optionally) display to the user

/session/:nodeName/:id/body/:bodyType/:bodyNum/:bodyName API

GET - /api/session/:nodeName/:id/body/:bodyType/:bodyNum/:bodyName

Retrieves a file that was transferred in a session.

Returns:

Name Type Description
file file The file in the session

/session/:nodeName/:id/bodypng/:bodyType/:bodyNum/:bodyName API

GET - /api/session/:nodeName/:id/bodypng/:bodyType/:bodyNum/:bodyName

Retrieves a bitmap image representation of the bytes in a file.

Returns:

Name Type Description
image image/png The bitmap image.

/sessions/pcap API

GET - /api/sessions/pcap OR /api/sessions.pcap

Retrieve the raw session data in pcap format.

Parameters:

Param Type Default Description
ids string   The list of ids to return sessions for
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
segments boolean false When set return linked segments

Returns:

Name Type Description
  pcap A PCAP file with the sessions requested

Example

Returns pcap for sessions with the source IP of 1.2.3.4
  curl -v 'http://localhost:8005/api/sessions/pcap/anyfilename.pcap?date=-1&expression=ip.src%3D%3D1.2.3.4'

/sessions/pcapng API

GET - /api/sessions/pcapng OR /api/sessions.pcapng

Retrieve the raw session data in pcapng format.

Parameters:

Param Type Default Description
ids string   The list of ids to return sessions for
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
segments boolean false When set return linked segments

Returns:

Name Type Description
  pcap A PCAPNG file with the sessions requested

/session/entire/:nodeName/:id/pcap API

GET - /api/session/entire/:nodeName/:id/pcap OR /api/session/entire/:nodeName/:id.pcap

Retrieve the pcap for a session given the session id and node name.

Returns:

Name Type Description
  pcap A PCAP file with the session requested

/session/raw/:nodeName/:id/png API

GET - /api/session/raw/:nodeName/:id/png OR /api/session/raw/:nodeName/:id.png

Retrieve a bitmap image representation of packets in a session given the session id and node name.

Parameters:

Param Type Default Description
type string "src" Whether to retrieve the src (source) or dst (desintation) packets bitmap image. Defaults to src.

Returns:

Name Type Description
image image/png The bitmap image.

/session/raw/:nodeName/:id API

GET - /api/session/raw/:nodeName/:id

Retrieve raw packets for a session given the session id and node name.

Parameters:

Param Type Default Description
type string "src" Whether to retrieve the src (source) or dst (desintation) raw packets. Defaults to src.

Returns:

Name Type Description
  string The source or destination packet text.

/sessions/bodyhash/:hash API

GET - /api/sessions/bodyhash/:hash

Retrieve a file given a hash of that file.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Returns:

Name Type Description
file file The file that matches the hash

/session/:nodeName/:id/bodyhash/:hash API

GET - /api/session/:nodeName/:id/bodyhash/:hash

Retrieve a file from a specific node given a hash of that file.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Returns:

Name Type Description
file file The file that matches the hash

/delete API

GET - /api/delete

Delete SPI and/or scrub PCAP data (remove persmission required).

Parameters:

Param Type Default Description
ids string   Comma separated list of sessions to delete
See_List SessionsQuery   This API supports a common set of parameters documented in the SessionsQuery section
removeSpi string false Whether to remove the SPI data.
removePcap string true Whether to remove the PCAP data.

Returns:

Name Type Description
success boolean Whether the operation was successful
text string The success/error message to (optionally) display to the user

/shortcuts API

GET - /api/shortcuts

Retrieves a list of shortcuts.

Parameters:

Param Type Default Description
map string false Whether to return a list or a map. Default is list.
sort string "name" The field to sort the results by.
desc string true Whether to sort the results descending or ascending. Default is descending.
searchTerm string   The search text to filter the shortcut list by.
length number 50 The number of items to return. Defaults to 50.
start number 0 The entry to start at. Defaults to 0.
fieldType string   Filter the results by type (number, ip, or string).
fieldFormat string false Sends a help field with the shortcut with the description + the values of the shortcut.

Returns:

Name Type Description
data Array.<Shortcut> The list of shortcut results.
recordsTotal number The total number of shortcut results stored.
recordsFiltered number The number of shortcut items returned in this result.

/shortcut API

POST - /api/shortcut

Creates a new shortcut.

Parameters:

Param Type Description
name string The name of the new shortcut.
type string The type of the shortcut (number, ip, or string).
value string The shortcut value.
description string The optional description of this shortcut.
users string A comma separated list of users that can view this shortcut.
roles Array The roles that can view this shortcut.

Returns:

Name Type Description
shortcut Shortcut The new shortcut object.
success boolean Whether the create shortcut operation was successful.

/shortcut/:id API

PUT - /api/shortcut/:id

Updates a shortcut.

Parameters:

Param Type Description
name string The name of the shortcut.
type string The type of the shortcut (number, ip, or string).
value string The shortcut value.
description string The optional description of this shortcut.
users string A comma separated list of users that can view this shortcut.
roles Array The roles that can view this shortcut.
editRoles Array The roles that can edit this shortcut.

Returns:

Name Type Description
shortcut Shortcut The updated shortcut object.
success boolean Whether the update operation was successful.
text string The success/error message to (optionally) display to the user.

/shortcut/:id API

DELETE - /api/shortcut/:id

Deletes a shortcut.

Returns:

Name Type Description
success boolean Whether the delete shortcut operation was successful.
text string The success/error message to (optionally) display to the user.

/eshealth API

GET - /api/eshealth

Retrieve OpenSearch/Elasticsearch health and stats There is no auth necessary to retrieve eshealth

Returns:

Name Type Description
health ESHealth The elasticsearch cluster health status and info

/stats API

GET - /api/stats

Fetches a list of stats for each node in the cluster.

Parameters:

Param Type Default Description
filter string   Search text to filter the list of nodes by.
length number 500 The number of nodes to return. Defaults to 500.
start number 0 The entry to start at. Defaults to 0.
sortField string "nodeName" The field to sort the node list by.
desc string false Whether to return the results in descending order. Defaults to “false”.
hide string   Which nodes to exclude from the results. Options include: none - show all nodes. old - hide out of date nodes (nodes whose current time is behind by at least 5 minutes). nosession - hide nodes without sessions. both - hide out of date nodes and nodes without sessions.

Returns:

Name Type Description
data array List of nodes with their corresponding stats.
recordsTotal number The total number of nodes.
recordsFiltered number The number of nodes returned in this result.

/dstats API

GET - /api/dstats

Fetches a list of detailed stats for different fields pertaining to a node to populate a cubism graph. Cubism GitHub

Parameters:

Param Type Default Description
nodeName string   The name of the node to get the detailed stats for.
name string   The name of the field to get the detailed stats for.
start number   The start time of data to return. Format is seconds since Unix EPOC.
stop number   The stop time of data to return. Format is seconds since Unix EPOC.
step number   The context step of the cubism graph in milliseconds.
interval number 60 The time interval to search for.
size number 1440 The size of the cubism graph. Defaults to 1440.

Returns:

Name Type Description
  array List of values to populate the cubism graph.

/esstats API

GET - /api/esstats

Fetches a list of stats for each OpenSearch/Elasticsearch cluster.

Parameters:

Param Type Default Description
filter string   Search text to filter the list of OpenSearch/Elasticsearch clusters by.
sortField string "nodeName" The field to sort the OpenSearch/Elasticsearch clusters list by.
desc string false Whether to return the results in descending order. Defaults to “false”.

Returns:

Name Type Description
data array List of ES clusters with their corresponding stats.
recordsTotal number The total number of ES clusters.
recordsFiltered number The number of ES clusters returned in this result.

/esindices API

GET - /api/esindices

Fetches a list of OpenSearch/Elasticsearch indices.

Parameters:

Param Type Default Description
filter string   Search text to filter the list of OpenSearch/Elasticsearch indices by.
sortField string "index" The field to sort the OpenSearch/Elasticsearch indices list by.
desc string false Whether to return the results in descending order. Defaults to “false”.

Returns:

Name Type Description
data array List of ES indices with their corresponding stats.
recordsTotal number The total number of ES indices.
recordsFiltered number The number of ES indices returned in this result.

/esindices/:index API

DELETE - /api/esindices/:index

Deletes an OpenSearch/Elasticsearch index (admin and remove access only).

Returns:

Name Type Description
success boolean Whether the delete index operation was successful.
text string The success/error message to (optionally) display to the user.

/esindices/:index/optimize API

POST - /api/esindices/:index/optimize

Optimizes an OpenSearch/Elasticsearch index (admin only).

Returns:

Name Type Description
success boolean Always true, the optimizeIndex function might block. Check the logs for errors.

/esindices/:index/close API

POST - /api/esindices/:index/close

Closes an OpenSearch/Elasticsearch index (admin only).

Returns:

Name Type Description
success boolean Whether the close index operation was successful.
text string The success/error message to (optionally) display to the user.

/esindices/:index/open API

POST - /api/esindices/:index/open

Opens an OpenSearch/Elasticsearch index (admin only).

Returns:

Name Type Description
success boolean Always true, the openIndex function might block. Check the logs for errors.

/esindices/:index/shrink API

POST - /api/esindices/:index/shrink

Shrinks an OpenSearch/Elasticsearch index (admin only).

Parameters:

Param Type Description
target string The index name to shrink the index to.
numShards number The number of shards to shrink the index to.

Returns:

Name Type Description
success boolean Whether the close shrink operation was successful.
text string The success/error message to (optionally) display to the user.

/estasks API

GET - /api/estasks

Fetches OpenSearch/Elasticsearch tasks.

Parameters:

Param Type Default Description
filter string   Search text to filter the list of ES tasks by.
cancellable string false Whether to return only cancellable tasks. Default is “false”.
sortField string "action" The field to sort the ES task list by.
desc string false Whether to return the results in descending order. Defaults to “false”.
size number 1000 The number of ES tasks to return. Defaults to 1000.

Returns:

Name Type Description
data array List of ES tasks with their corresponding stats.
recordsTotal number The total number of ES tasks.
recordsFiltered number The number of ES tasks returned in this result.

/estasks/:id/cancel API

POST - /api/estasks/:id/cancel

Cancels an OpenSearch/Elasticsearch task (admin only).

Returns:

Name Type Description
success boolean Whether the cancel task operation was successful.
text string The success/error message to (optionally) display to the user.

/estasks/:id/cancelwith API

POST - /api/estasks/:id/cancelwith

Cancels an OpenSearch/Elasticsearch task by opaque id. Used to cancel running tasks that a user has created allowing a user to cancel their own tasks.

Returns:

Name Type Description
success boolean Whether the cancel task operation was successful.
text string The success/error message to (optionally) display to the user.

/estasks/cancelall API

POST - /api/estasks/cancelall

Cancels all running OpenSearch/Elasticsearch tasks (admin only).

Returns:

Name Type Description
success boolean Whether the cancel all tasks operation was successful.
text string The success/error message to (optionally) display to the user.

/esadmin API

GET - /api/esadmin

Fetches all OpenSearch/Elasticsearch settings that a user can change (es admin only - set in config with esAdminUsers).

Returns:

Name Type Description
settings array List of ES settings that a user can change

/esadmin/set API

POST - /api/esadmin/set

Sets OpenSearch/Elasticsearch settings (es admin only - set in config with esAdminUsers).

Returns:

Name Type Description
success boolean Whether saving the settings was successful.
text string The success/error message to (optionally) display to the user.

/esadmin/reroute API

POST - /api/esadmin/reroute

Try to restart any shard migrations that have failed or paused (es admin only - set in config with esAdminUsers).

Returns:

Name Type Description
success boolean Whether the reroute was successful.
text string The success/error message to (optionally) display to the user.

/esadmin/flush API

POST - /api/esadmin/flush

Flush and refresh any data waiting in OpenSearch/Elasticsearch to disk (es admin only - set in config with esAdminUsers).

Returns:

Name Type Description
success boolean Always true
text string The success message to (optionally) display to the user.

/esadmin/unflood API

POST - /api/esadmin/unflood

Try and clear any indices marked as flooded (es admin only - set in config with esAdminUsers).

Returns:

Name Type Description
success boolean Always true
text string The success message to (optionally) display to the user.

/esadmin/clearcache API

POST - /api/esadmin/clearcache

Try and clear the cache for all indices (es admin only - set in config with esAdminUsers).

Returns:

Name Type Description
success boolean Whether clearing the cache was successful.
text string The success/error message to (optionally) display to the user.

/esshards API

GET - /api/esshards

Fetches all OpenSearch/Elasticsearch shards

Parameters:

Param Type Default Description
filter string   Search text to filter the list of OpenSearch/Elasticsearch shards by.
show string "all" Which types of shard to show. Options include: all - show all shards. notstarted - show unstarted shards. INITIALIZING - show initializing shards. RELOCATING - show relocating shards. UNASSIGNED - show unassigned shards.
desc string false Whether to return the results in descending order. Defaults to “false”.

Returns:

Name Type Description
nodes array List of ES data nodes.
indices array List of ES indices.
nodeExcludes array List of node names that disallow the allocation of shards.
ipExcludes array List of node ips that disallow the allocation of shards.

/esshards/:type/:value/exclude API

POST - /api/esshards/:type/:value/exclude

Exclude OpenSearch/Elasticsearch node by ip or name (admin only).

Returns:

Name Type Description
success boolean Whether exclude node operation was successful.
text string The success/error message to (optionally) display to the user.

/esshards/:type/:value/include API

POST - /api/esshards/:type/:value/include

Include OpenSearch/Elasticsearch node by ip or name (admin only).

Returns:

Name Type Description
success boolean Whether include node operation was successful.
text string The success/error message to (optionally) display to the user.

/esshards/:index/:shard/delete API

POST - /api/esshards/:index/:shard/delete

Delete OpenSearch/Elasticsearch (admin only).

Returns:

Name Type Description
success boolean Whether include node operation was successful.
text string The success/error message to (optionally) display to the user.

/esrecovery API

GET - /api/esrecovery

Returns information about ongoing and completed shard recoveries for indices.

Parameters:

Param Type Default Description
filter string   Search text to filter the list of indices by.
sortField string "index" The field to sort the indices by.
desc string false Whether to return the results in descending order. Defaults to “false”.
show string "active" Whether to show “all” or “active” recovering indices.

Returns:

Name Type Description
data array List of indices with their corresponding stats.
recordsTotal number The total number of indices.
recordsFiltered number The number of indices returned in this result.

/parliament API

GET - /api/parliament

Returns information all the Arkime clusters configured in your Parliament. See the parliament definition here (subject to change).

Returns:

Name Type Description
data array List of fields that describe the cluster stats.
recordsTotal number The total number of stats.
recordsFiltered number The number of stats returned in this result.

/user/css API

GET - /api/user/css OR /api/user.css

Retrieves custom user css for the user’s custom theme.

Returns:

Name Type Description
css css The css file that includes user configured styles.

/user/settings API

GET - /api/user/settings

Retrieves an Arkime user’s settings.

Returns:

Name Type Description
settings ArkimeSettings The user’s configured settings

/user/settings API

POST - /api/user/settings

Updates an Arkime user’s settings.

Returns:

Name Type Description
success boolean Whether the update user settings operation was successful.
text string The success/error message to (optionally) display to the user.

/user/layouts/:type API

GET - /api/user/layouts/:type

Retrieves a user configured layouts. Valid layouts are: sessionstable, sessionsinfofields, spiview

Returns:

Name Type Description
layout Array The user configured layout

/user/layouts/:type API

POST - /api/user/layouts/:type

Creates a new user configured layout. Valid layouts are: sessionstable, sessionsinfofields, spiview

Returns:

Name Type Description
success boolean Whether the operation was successful.
text string The success/error message to (optionally) display to the user.
layout object The new layout configuration.

/user/layouts/:type API

PUT - /api/user/layouts/:type

Updates a user configured layout. Valid layouts are: sessionstable, sessionsinfofields, spiview

Returns:

Name Type Description
success boolean Whether the update layout operation was successful.
text string The success/error message to (optionally) display to the user.
layout object The updated layout configuration.

/user/layouts/:type/:name API

DELETE - /api/user/layouts/:type/:name

Deletes a user configured layout. Valid layouts are: sessionstable, sessionsinfofields, spiview

Returns:

Name Type Description
success boolean Whether the delete layout operation was successful.
text string The success/error message to (optionally) display to the user.

/user/:userId/acknowledge API

PUT - /api/user/:userId/acknowledge

Acknowledges a UI message for a user. Used to display help popups.

Returns:

Name Type Description
success boolean Whether the operation was successful.
text string The success/error message to (optionally) display to the user.

/user/state/:name API

GET - /api/user/state/:name

Retrieves a user table state object. These are used to save the states of tables within the UI (sessions, files, stats, etc).

Returns:

Name Type Description
tableState object The table state requested.

/user/state/:name API

POST - /api/user/state/:name

Updates or creates a user table state object. These are used to save the states of tables within the UI (sessions, files, stats, etc).

Returns:

Name Type Description
success boolean Whether the operation was successful.
text string The success/error message to (optionally) display to the user.

/user/config/:page API

GET - /api/user/config/:page

Fetches the configuration/layout information for a UI page for a user.

Returns:

Name Type Description
  object config The configuration data for the page

/views API

GET - /api/views

Retrieves an Arkime views that a user can view.

Returns:

Name Type Description
views Array.<ArkimeView> A list of views a user has configured or has been shared.

/view API

POST - /api/view

Creates an Arkime view.

Returns:

Name Type Description
success boolean Whether the create view operation was successful.
text string The success/error message to (optionally) display to the user.
viewName string The name of the new view.
view ArkimeView The new view data.

/view/:id API

DELETE - /api/view/:id

Deletes an Arkime view.

Returns:

Name Type Description
success boolean Whether the delete view operation was successful.
text string The success/error message to (optionally) display to the user.

/view/:id API

PUT - /api/view/:id

Updates an Arkime view.

Returns:

Name Type Description
success boolean Whether the update view operation was successful.
text string The success/error message to (optionally) display to the user.

ArkimeQuery Type

A query to be run periodically that can perform actions on sessions that match the queries. The query runs against sessions delayed by 90 seconds to make sure all updates have been completed for that session.

Parameters:

Param Type Default Description
name string   The name of the query
enabled boolean   Whether the query is enabled. If enabled, the query will run every 90 seconds.
lpValue number   The last packet timestamp that was searched. Used to query for the next group of sessions to search. Format is seconds since Unix EPOC.
lastRun number   The time that the query was last run. Format is seconds since Unix EPOC.
count number   The count of total sessions that have matched this query.
lastCount number   The count of sessions that have matched this query during its last run.
query string   The search expression to apply when searching for sessions.
action string "tag" The action to perform when sessions have matched. “tag” or “forward:clusterName”.
creator string   The id of the user that created this query.
tags string   A comma separated list of tags to add to each session that matches this query.
notifier string   The name of the notifier to alert when there are matches for this query.
lastNotified number   The time that this query last sent a notification to the notifier. Only notifies every 10 minutes. Format is seconds since Unix EPOC.
lastNotifiedCount number   The count of sessions that matched since the last notification was sent.
description string   The description of this query.
created number   The time that this query was created. Format is seconds since Unix EPOC.
lastToggled number   The time that this query was enabled or disabled. Format is seconds since Unix EPOC.
lastToggledBy string   The user who last enabled or disabled this query.
users string   The list of userIds who have access to use this query.
roles string   The list of roles who have access to use this query.
editRoles string   The list of roles who have access to edit this query.

History Type

The history object to describe user client requests.

Parameters:

Param Type Description
uiPage string The client application page that the user accessed to make the request.
userId string The ID of the user that made the request.
method string The HTTP method that the request used.
api string The API endpoint of the request.
expression string The sessions search expression used in the request.
view ArkimeView The view applied to the request.
timestamp number The time that the request was made. Format is seconds since Unix EPOC.
range number The date range of the request. Range is described in hours, -1 means all.
query string The query parameters of the request.
queryTime number The time it took for the response to be returned after the request was issued.
recordsTotal number The total number of items in the data set.
recordsFiltered number The number of items returned from searching the dataset (before paging).
recordsReturned number The number of items returned in the response (after paging).
body object The request body.
forcedExpression string The expression applied to the search as a result of a users forced expression. Only visible to admins, normal users cannot see their forced expressions.

Hunt Type

A packet search job that allows users to search within session packets for text.

Parameters:

Param Type Description
See_List SessionsQuery This API supports a common set of parameters documented in the SessionsQuery section

Properties

Name Type Description
userId string The ID of the user that created the hunt.
status string The status of the hunt. Options include: queued - The hunt is queued to search packets once the currently running hunt has finished. running - The hunt is currently searching packets. paused - The hunt is paused, either by a user or by error. finished - The hunt has searched all requested sessions.
name string The name of the hunt (not unique).
size number The number of packets to search within each session.
search string The search text to search for within packets.
searchType string What type of search the text is. Options include: ascii - search for case insensitive ascii text. asciicase - search for case sensitive ascii text. hex - search for hex text. regex - search for text using safe regex. hexregex - search for text using safe hex regex.
src boolean Whether to search the source packets. Must search src or dst or both.
dst boolean Whether to search the destination packets. Must search src or dst or both.
type string Whether to search raw or reassembled packets.
matchedSessions number How many sessions contain packets that match the search text.
searchedSessions number How many sessions have had their packets searched.
totalSessions number The number of sessions to search.
lastPacketTime number The date of the first packet of the last searched session. Used to query for the next chunk of sessions to search. Format is seconds since Unix EPOC.
created number The time that the hunt was created. Format is seconds since Unix EPOC.
lastUpdated number The time that the hunt was last updated in the DB. Used to only update every 2 seconds. Format is seconds since Unix EPOC.
started number The time that the hunt was started (put into running state). Format is seconds since Unix EPOC.
errors array The list of errors that a hunt encountered. A hunt error includes: value - The error text to display to the user. time - The time the error was encountered. node - The Arkime node that the hunt was searching sessions for when the error occurred.
notifier string The otional notifier name to fire when there is an error, or there are matches (every 10 minutes), or when the hunt is complete.
unrunnable boolean Whether an error has rendered the hunt unrunnable.
failedSessionIds array The list of sessions that have failed to be searched. Used to run the search against them again once the rest of the hunt is complete.
users array The list of users to be added to the hunt so they can view the results.
removed boolean Whether the hunt name and ID fields have been removed from the matched sessions.

SessionsQuery Parameter List

Many Arkime Session requests support a standard set of query parameters. These parameters can be used to filter and sort the returned data. For large queries, prefer the POST method to avoid URL length limits, which allows you to include parameters in the request body (these override any URL duplicates). Ensure parameters with special characters are URL encoded when placed in the URL.

Parameters:

Param Type Default Description
date number 1 Perform the search from a specified number of hours ago until the present moment, where ‘-1’ indicates searching all available data.
expression string   The search expression string, ensure URL encoded
facets number 0 1 = include the aggregation information for maps and timeline graphs.
length number 100 The number of items to return, beginning at start parameter, max is 2,000,000
start number 0 The entry to start at for pagination purposes.
startTime number   If the date parameter is not set, this is the start time of data to return. Format is seconds since Unix EPOC.
stopTime number   If the date parameter is not set, this is the stop time of data to return. Format is seconds since Unix EPOC.
view string   The Arkime view name to apply before the expression.
order string   Comma separated list of db field names to sort on. Data is sorted in order of the list supplied. Optionally can be followed by :asc or :desc for ascending or descending sorting.
fields string   Comma separated list of db field names to return. Default is ipProtocol, rootId, totDataBytes, client.bytes, server.bytes, firstPacket, lastPacket, source.ip, source.port, destination.ip, destination.port, network.packets, source.packets, destination.packets, network.bytes, source.bytes, destination.bytes, node, http.uri, source.geo.country_iso_code, destination.geo.country_iso_code, email.subject, email.src, email.dst, email.filename, dns.host, cert, irc.channel, http.xffGEO
bounding string "last" Query sessions based on different aspects of a session’s time. Options include: ‘first’ - First Packet: the timestamp of the first packet received for the session. ‘last’ - Last Packet: The timestamp of the last packet received for the session. ‘both’ - Bounded: Both the first and last packet timestamps for the session must be inside the time window. ‘either’ - Session Overlaps: The timestamp of the first packet must be before the end of the time window AND the timestamp of the last packet must be after the start of the time window. ‘database’ - Database: The timestamp the session was written to the database. This can be up to several minutes AFTER the last packet was received.
strictly boolean false When set the entire session must be inside the date range to be observed, otherwise if it overlaps it is displayed. Overwrites the bounding parameter, sets bounding to ‘both’

Shortcut Type

The shortcut object to store lists of values that can be used in search queries.

Parameters:

Param Type Default Description
userId string   The ID of the user that created the shortcut.
name string   The name of the shortcut.
description string   The description of the shortcut to display to users.
number Array.<number>   A list of number values to use as the shortcut value. A shortcut must contain a list of numbers, strings, or ips.
ip Array.<string>   A list of ip values to use as the shortcut value. A shortcut must contain a list of numbers, strings, or ips.
string Array.<string>   A list of string values to use as the shortcut value. A shortcut must contain a list of numbers, strings, or ips.
users string   A list of userIds that have access to this shortcut.
roles Array.<string>   A list of Arkime roles that have access to this shortcut.
editRoles Array.<string>   A list of Arkime roles that have edit access to this shortcut.
locked boolean false Whether the shortcut is locked and must be updated using the db.pl script (can’t be updated in the web application user interface).

ESHealth Type

The OpenSearch/Elasticsearch cluster health status and information.

Properties

Name Type Description
active_primary_shards number The number of active primary shards.
active_shards number The total number of active primary and replica shards.
active_shards_percent_as_number number The ratio of active shards in the cluster expressed as a percentage.
cluster_name string The name of the arkime cluster
delayed_unassigned_shards number The number of shards whose allocation has been delayed by the timeout settings.
initializing_shards number The number of shards that are under initialization.
molochDbVersion number The arkime database version
number_of_data_nodes number The number of nodes that are dedicated data nodes.
number_of_in_flight_fetch number The number of unfinished fetches.
number_of_nodes number The number of nodes within the cluster.
number_of_pending_tasks number The number of cluster-level changes that have not yet been executed.
relocating_shards number The number of shards that are under relocation.
status string Health status of the cluster, based on the state of its primary and replica shards. Statuses are: “green” - All shards are assigned. “yellow” - All primary shards are assigned, but one or more replica shards are unassigned. If a node in the cluster fails, some data could be unavailable until that node is repaired. “red” - One or more primary shards are unassigned, so some data is unavailable. This can occur briefly during cluster startup as primary shards are assigned.
task_max_waiting_in_queue_millis number The time expressed in milliseconds since the earliest initiated task is waiting for being performed.
timed_out boolean If false the response returned within the period of time that is specified by the timeout parameter (30s by default).
unassigned_shards number The number of shards that are not allocated.
version string the elasticsearch version number
_timeStamp number timestamps in ms from unix epoc

ArkimeRole Type

An Arkime Role

Roles are assigned to users to give them access to Arkime content
Default roles include:
arkimeAdmin - has administrative access to Arkime (can configure and update Arkime)
arkimeUser - has access to Arkime
cont3xtAdmin - has administrative access to Cont3xt (can configure and update Cont3xt)
cont3xtUser - has access to Cont3xt
parliamentAdmin - has administrative access to Parliament (can configure and update Parliament)
parliamentUser - has access to Parliament (can view and interact with Parliament Issues)
superAdmin - has access to all the applications and can configure anything
usersAdmin - has access to configure users
wiseAdmin - has administrative access to WISE (can configure and update WISE)
wiseUser - has access to WISE

ArkimeUser Type

The user object.

Parameters:

Param Type Default Description
userId string   The ID of the user.
userName string   The name of the user (to be displayed in the UI).
enabled boolean true Whether the user is enabled (or disabled). Disabled users cannot access the UI or APIs.
webEnabled boolean true Can access the web interface. When off only APIs can be used.
headerAuthEnabled boolean false Can login using the web auth header. This setting doesn’t disable the password so it should be scrambled.
emailSearch boolean false Can perform searches for fields relating to email.
removeEnabled boolean false Can delete tags or delete/scrub pcap data and other deletion operations.
packetSearch boolean true Can create a packet search job (hunt).
hideStats boolean false Hide the Stats page from this user.
hideFiles boolean false Hide the Files page from this user.
hidePcap boolean false Hide PCAP (and only show metadata/session detail) for this user when they open a Session.
disablePcapDownload boolean false Do not allow this user to download PCAP files.
expression string   An Arkime search expression that is silently added to all queries. Useful to limit what data a user can access (e.g. which nodes or IPs).
settings ArkimeSettings   The Arkime app settings.
notifiers object   A list of notifiers that the user can use.
columnConfigs object   A list of sessions table column configurations that a user has created.
spiviewFieldConfigs object   A list of SPIView page field configurations that a user has created.
tableStates object   A list of table states used to render Arkime tables as the user has configured them.
welcomeMsgNum number 0 The message number that a user is on. Gets incremented when a user dismisses a message.
lastUsed number   The date that the user last used Arkime. Format is milliseconds since Unix EPOC.
timeLimit number   Limits the time range a user can query for.
roles array   The list of Arkime roles assigned to this user.
roleAssigners array   The list of userIds that can manage who has this (ROLE)

ArkimeSettings Type

The settings object.

Parameters:

Param Type Default Description
timezone string "local" The timezone applied to timestamps within the UI.
detailFormat string "last" The format to display the session packets. Options include: last used, natural, ascii, utf-8, hex.
showTimestamps string "last" Whether to display timestamps at the top of each packet.
sortColumn string "firstPacket" Which column to sort the sessions table by default. Default is start time.
sortDirection string "desc" Whether to sort the sessions table ascending or descending.
spiGraph string "node" The default field to show spigraph data for.
connSrcField string "source.ip" The default connections graph source node field.
connDstField string "ip.dst:port" The default connections graph destination node field.
numPackets string "last" The number of packets to show in the session packet area.
theme string "default-theme" The color theme to apply to the UI. Can be a name of a predefined field or a list of color codes if using a custom theme.
manualQuery boolean false Whether to load the sessions data by default or wait for a user to hit search manually.
timelineDataFilters array ['network.packets','network.bytes','totDataBytes' The filters to display on the sessions timeline graph to change the graphs data.
hideTags string "\"\"" A comma separated list of tags to hide from sessions
logo string   The optionally configurable logo to show in the top navbar.

ArkimeColumnLayout Type

A sessions table view that can be applied.

Parameters:

Param Type Default Description
name string   The name of the column configuration.
order Array.<Array> [["firstPacket","desc"] What to sort the Sessions table by. The table is sorted by the first item in the array first, then the second, and so on. Each element in the array includes first the sort field followed by whether to sort descending ([“firstPacket”, “desc”]).
visibleHeaders Array ["firstPacket","lastPacket","src","source.port","dst","destination.port","network.packets","dbby","node" The list of Sessions table columns.

ArkimeInfoColumnLayout Type

A sessions info view that can be applied.

Parameters:

Param Type Default Description
name string   The name of the info column configuration.
fields Array ["firstPacket","lastPacket","src","source.port","dst","destination.port","network.packets","dbby","node" The list of Sessions table columns.

ArkimeView Type

A database view that can be applied to any search.

Parameters:

Param Type Description
name string The name of the view.
expression string The search expression to filter sessions.
sessionsColConfig ArkimeColumnConfig The Sessions column configuration to apply to the Sessions table when applying the view.
user string The user ID of the user who created the view.
users string The list of userIds who have access to use this view.
roles Array.<string> The list of roles who have access to use this view.
editRoles Array.<string> The list of roles who have access to edit this view.
Arkime Logo