3. RESTful API v1 Specification
3.1. Authentication
The HTTP/HTTPS authentication should be used, for example with curl
it is possible to specify username and password with
-u <user>:<password>
Using HTTPS is recommended for security. See this post to enable HTTPS.
3.2. Request Format
Parameters can be provided both using GET with a query string or POST using JSON (in this case please make sure the correct Content Type is provided). For example, to download data for a host you can use the below curl command line using GET:
curl -s -u admin:admin "http://192.168.1.1:3000/lua/rest/v1/get/host/data.lua?ifid=1&host=192.168.1.2"
or the below curl command line using POST:
curl -s -u admin:admin -H "Content-Type: application/json" -d '{"ifid": "1", "host": "192.168.1.2"}' "http://192.168.1.1:3000/lua/rest/v1/get/host/data.lua"
Please check the Examples section for more examples.
3.3. Response Format
An API response is usually represented by a JSON message matching a standard structure. This JSON message consists of an envelope containing:
a return code rc
a human-readable string rc_str describing the return code
the actual response in rsp
Example:
{
"rc": 0
"rc_str": "OK",
"rsp": {
...
}
}
3.4. API
3.4.1. Interfaces
GET /lua/rest/v1/get/interface/data.lua
Get interface data
Description: Interface data is returned
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
Responses
0 - OK
-2 - INVALID_INTERFACE
-6 - INTERNAL_ERROR
GET /lua/rest/v1/get/interface/bcast_domains.lua
Get interface broadcast domains
Description: Interface broadcast domains as detected from ARP traffic and broadcast traffic are returned
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
Responses
0 - OK
-2 - INVALID_INTERFACE
-6 - INTERNAL_ERROR
GET /lua/rest/v1/get/interface/address.lua
Get interface IP addresses
Description: List of interface IP addresses is returned
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
Responses
0 - OK
-2 - INVALID_INTERFACE
-6 - INTERNAL_ERROR
GET /lua/rest/v1/get/interface/l7/stats.lua
Get L7 statistics for an interface
Description: nDPI statistics
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
ndpistats_mode |
query |
Stats mode: ‘sinceStartup’ or ‘count’ |
string |
breed |
query |
Show breed |
boolean |
ndpi_category |
query |
Show nDPI category |
boolean |
Responses
0 - OK
-2 - INVALID_INTERFACE
-5 - INVALID_ARGUMENTS
-6 - INTERNAL_ERROR
GET /lua/rest/v1/get/interface/dscp/stats.lua
Get IP DSCP statistics for an interface
Description: DSCP statistics
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
Responses
0 - OK
-2 - INVALID_INTERFACE
-5 - INVALID_ARGUMENTS
-6 - INTERNAL_ERROR
GET /lua/rest/v1/get/ntopng/interfaces.lua
Get ntopng actively monitored interfaces names and ids
Description: Interface name and integer interface id for each actively monitored ntopng interface
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
3.4.2. Hosts
GET /lua/rest/v1/get/host/active.lua
Get active hosts
Description: List of active hosts
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
currentPage |
query |
Pagination: page (optional) |
integer |
perPage |
query |
Pagination: items per page (optional) |
integer |
sortColumn |
query |
Pagination: column for sorting (e.g. ip, name, since, last, alerts, country, vlan, num_flows, traffic, thpt) (optional) |
string |
sortOrder |
query |
Pagination: sorting order: ‘asc’ or ‘desc’ (optional) |
string |
all |
query |
Get all hosts (optional) |
boolean |
mode |
query |
Mode filter: all, local, remote, broadcast_domain, filtered, blacklisted, dhcp (optional) |
string |
Responses
0 - OK
-1 - NOT_FOUND
-2 - INVALID_INTERFACE
-6 - INTERNAL_ERROR
GET /lua/rest/v1/get/host/interfaces.lua
Get host interfaces
Description: All interface ids of a given host are returned
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
host |
query |
Host address |
string |
Responses
0 - OK
-5 - INVALID_ARGUMENTS
GET /lua/rest/v1/get/host/data.lua
Get host data
Description: Host data is returned
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
host |
query |
Host address |
string |
Responses
0 - OK
-1 - NOT_FOUND
-2 - INVALID_INTERFACE
-3 - NOT_GRANTED
-4 - INVALID_HOST
-5 - INVALID_ARGUMENTS
-6 - INTERNAL_ERROR
-7 - BAD_FORMAT
-8 - BAD_CONTENT
GET /lua/rest/v1/get/host/custom_data.lua
Get host custom data
Description: Custom data is returned for one or all hosts
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
host |
query |
Host address |
string |
field_alias |
query |
Field alias |
string |
Responses
0 - OK
-1 - NOT_FOUND
-2 - INVALID_INTERFACE
-3 - NOT_GRANTED
-4 - INVALID_HOST
-5 - INVALID_ARGUMENTS
-6 - INTERNAL_ERROR
-7 - BAD_FORMAT
-8 - BAD_CONTENT
GET /lua/rest/v1/get/host/l7/stats.lua
Get L7 statistics for a host
Description: nDPI statistics
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
host |
query |
Host address |
string |
vlan |
query |
VLAN ID |
integer |
breed |
query |
Show breed |
boolean |
ndpi_category |
query |
Show nDPI category |
boolean |
Responses
0 - OK
-2 - INVALID_INTERFACE
-5 - INVALID_ARGUMENTS
-6 - INTERNAL_ERROR
GET /lua/rest/v1/get/host/dscp/stats.lua
Get IP DSCP statistics for a host
Description: DSCP statistics
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
host |
query |
Host address |
string |
vlan |
query |
VLAN ID |
integer |
direction |
query |
Select direction: ‘sent’ or ‘recvd’ (default) |
boolean |
Responses
0 - OK
-2 - INVALID_INTERFACE
-5 - INVALID_ARGUMENTS
-6 - INTERNAL_ERROR
POST /lua/rest/v1/set/host/alias.lua
Set host alias
Description: Set hsot custom name
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
host |
formData |
Host address |
string |
custom_name |
formData |
Custom name |
string |
Responses
0 - OK
-5 - INVALID_ARGUMENTS
GET lua/pro/rest/v1/get/interface/top/local/talkers.lua
Get Top local talkers
Description: Get the Top 10 local talkers
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface ID |
number |
Responses
0 - OK
-2 - INVALID_INTERFACE
GET lua/pro/rest/v1/get/interface/top/remote/talkers.lua
Get Top remote talkers
Description: Get the Top 10 remote talkers
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface ID |
number |
Responses
0 - OK
-2 - INVALID_INTERFACE
3.4.3. Alerts
GET /lua/rest/v1/get/alert/data.lua
Get alerts data
Description: Alerts are returned
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
status |
query |
Status filter (historical, historical-flows, engaged) |
string |
epoch_begin |
query |
Start time (epoch) (optional) |
integer |
epoch_end |
query |
Start time (epoch) (optional) |
integer |
alert_type |
query |
Alert Type (optional) |
integer |
alert_severity |
query |
Alert Severity (optional) |
integer |
Responses
0 - OK
-1 - NOT_FOUND
-2 - INVALID_INTERFACE
-3 - NOT_GRANTED
-4 - INVALID_HOST
-5 - INVALID_ARGUMENTS
-6 - INTERNAL_ERROR
-7 - BAD_FORMAT
-8 - BAD_CONTENT
GET /lua/rest/v1/get/alert/ts.lua
Get alerts timeseries
Description: Number of alerts per hour divided by day are returned
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
status |
query |
Status filter (historical, historical-flows) |
string |
epoch_begin |
query |
Start time (epoch) |
integer |
epoch_end |
query |
Start time (epoch) |
integer |
alert_type |
query |
Alert Type (optional) |
integer |
alert_severity |
query |
Alert Severity (optional) |
integer |
Responses
0 - OK
-2 - INVALID_INTERFACE
-5 - INVALID_ARGUMENTS
-6 - INTERNAL_ERROR
GET /lua/rest/v1/get/alert/type/consts.lua
Get alert type constants
Description: Alert type string and integer alert key for each defined alert
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
GET /lua/rest/v1/get/alert/severity/consts.lua
Get alert severity constants
Description: Alert severity string and integer severity id for each defined severity
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
GET /lua/rest/v2/get/alert/type/counters.lua
Get alert counters by type
Description: Alert type counters indescending order
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
status |
query |
Status filter (historical, historical-flows) |
string |
epoch_begin |
query |
Start time (epoch) |
integer |
epoch_end |
query |
Start time (epoch) |
integer |
Responses
0 - OK
-2 - INVALID_INTERFACE
-3 - NOT_GRANTED
GET /lua/rest/v2/get/alert/severity/counters.lua
Get alert counters by severity
Description: Alert severity counters in descending order
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
status |
query |
Status filter (historical, historical-flows) |
string |
epoch_begin |
query |
Start time (epoch) |
integer |
epoch_end |
query |
Start time (epoch) |
integer |
Responses
0 - OK
-2 - INVALID_INTERFACE
-3 - NOT_GRANTED
3.4.4. Flows
GET /lua/rest/v1/get/flow/active.lua
Get active flows
Description: List of active flows
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
currentPage |
query |
Pagination: page (optional) |
integer |
perPage |
query |
Pagination: items per page (optional) |
integer |
sortColumn |
query |
Pagination: column for sorting (e.g. ‘score’) (optional) |
string |
sortOrder |
query |
Pagination: sorting order: ‘asc’ or ‘desc’ (optional) |
string |
host |
query |
Host address filter (optional) |
string |
vlan |
query |
VLAN ID filter (optional) |
integer |
l4proto |
query |
L4 protocol filter (optional) |
string |
application |
query |
Application protocol filter (optional) |
string |
verbose |
query |
Add more details including TCP stats (optional) |
boolean |
Responses
0 - OK
-1 - NOT_FOUND
-2 - INVALID_INTERFACE
-6 - INTERNAL_ERROR
GET /lua/rest/v1/get/flow/l4/counters.lua
Get flow counters for L4 protocols
Description: Number of active flows per L4 protocol
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
Responses
0 - OK
-2 - INVALID_INTERFACE
-6 - INTERNAL_ERROR
GET /lua/rest/v1/get/flow/l7/counters.lua
Get flow counters for L7 protocols
Description: Number of active flows per L7 application protocol
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
Responses
0 - OK
-2 - INVALID_INTERFACE
-6 - INTERNAL_ERROR
GET /lua/pro/rest/v1/get/db/flows.lua
Get flows data. Columns include (but are not limited to) IP_PROTOCOL_VERSION, FLOW_TIME, FIRST_SEEN, LAST_SEEN, VLAN_ID, PACKETS, TOTAL_BYTES, SRC2DST_BYTES, DST2SRC_BYTES, IPV4_SRC_ADDR, IPV4_DST_ADDR, IPV6_SRC_ADDR, IPV6_DST_ADDR, PROTOCOL, L7_PROTO.
Description: Executes a query to the flows database
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
begin_time_clause |
query |
Start time (epoch) |
integer |
end_time_clause |
query |
Start time (epoch) |
integer |
select_clause |
query |
Select clause (default: *) |
string |
where_clause |
query |
Where clause (default: none) |
string |
maxhits_clause |
query |
Max hits (default: 10) |
integer |
Responses
0 - OK
-1 - NOT_FOUND
-2 - INVALID_INTERFACE
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-6 - INTERNAL_ERROR
GET /lua/pro/rest/v1/get/db/topk_flows.lua
Get Top-K flows data. Columns include (but are not limited to) IP_PROTOCOL_VERSION, FLOW_TIME, FIRST_SEEN, LAST_SEEN, VLAN_ID, PACKETS, TOTAL_BYTES, SRC2DST_BYTES, DST2SRC_BYTES, IPV4_SRC_ADDR, IPV4_DST_ADDR, IPV6_SRC_ADDR, IPV6_DST_ADDR, PROTOCOL, L7_PROTO
Description: Executes a top-k query to the flows database
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
begin_time_clause |
query |
Start time (epoch) |
integer |
end_time_clause |
query |
Start time (epoch) |
integer |
select_keys_clause |
query |
Select comma-separated keys list (default: IPV4_SRC_ADDR,IPV4_DST_ADDR,L7_PROTO) |
string |
select_values_clause |
query |
Select value (default: BYTES) |
string |
where_clause |
query |
Where clause (default: none) |
string |
topk_clause |
query |
Top-K clause (default: SUM) |
string |
approx_search |
query |
Approximate search (default: true) |
string |
maxhits_clause |
query |
Max hits (default: 10) |
integer |
Responses
0 - OK
-1 - NOT_FOUND
-2 - INVALID_INTERFACE
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-6 - INTERNAL_ERROR
3.4.5. PCAP
GET /lua/rest/v1/get/pcap/live_extraction.lua
Live PCAP traffic extraction
Description: Raw PCAP data is returned
Produces: [‘application/vnd.tcpdump.pcap’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
ifid |
query |
Interface identifier |
integer |
epoch_begin |
query |
Start time (epoch) |
integer |
epoch_end |
query |
Start time (epoch) |
integer |
bpf_filter |
query |
BPF filter |
string |
Responses
FILE - OK
-1 - NOT_FOUND
-2 - INVALID_INTERFACE
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-6 - INTERNAL_ERROR
-7 - BAD_FORMAT
3.4.6. Users
3.4.7. Infrastructures
3.4.8. L4 Protocols
GET /lua/rest/v1/get/l4/protocol/consts.lua
Get L4 protocol constants
Description: L4 protocol names and integer identifiers
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
3.4.9. L7 Application Protocols
GET /lua/rest/v1/get/l7/application/consts.lua
Get L7 application protocol constants
Description: L7 application protocol names and integer identifiers
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
3.4.10. L7 Application Categories
GET /lua/rest/v1/get/l7/category/consts.lua
Get L7 application category constants
Description: L7 application category names and integer identifiers
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
3.4.11. SNMP
GET lua/pro/rest/v1/add/snmp/device.lua
Add SNMP devices
Description: Add devices to the monitored SNMP devices
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
snmp_host |
query |
IP address or symbolic name of and an SNMP device |
string |
snmp_read_community |
query |
The SNMP read community to use (SNMP v1/v2c only) |
string |
snmp_write_community |
query |
The SNMP write community to use (SNMP v1/v2c only) |
string |
snmp_version |
query |
The SNMP version to use: 2 (SNMP v3), 1 (v2c) or 0 (v1) |
string |
snmp_level |
query |
Used only with SNMP v3: noAuthNoPriv, authNoPriv, or authPriv) |
string |
snmp_auth_protocol |
query |
Used only with SNMP v3 and level not set to noAuthNoPriv: MD5 or SHA |
string |
snmp_auth_passphrase |
query |
Used only with SNMP v3 and level not set to noAuthNoPriv: 8 chars+ passphrase |
string |
snmp_privacy_protocol |
query |
Used only with SNMP v3 and level set to autPriv: DES or AES |
string |
snmp_privacy_passphrase |
query |
Used only with SNMP v3 and level set to autPriv: 8 chars+ passphrase |
string |
cidr |
query |
Either 24 or 32. If 32, snmp_host is treated as single host. If 24 snmp_host is treated as as CIDR address |
string |
Responses
-3 - NOT_GRANTED
-4 - INVALID_HOST
-5 - INVALID_ARGUMENTS
-9 - NAME_RESOLUTION_FAILED
-10 - SNMP_DEVICE_ALREADY_ADDED
-11 - SNMP_DEVICE_UNREACHABLE
-12 - NO_SNMP_DEVICE_DISCOVERED
GET lua/pro/rest/v1/edit/snmp/device/device.lua
Edit a SNMP device
Description: Edit an existing monitored SNMP device
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
snmp_host |
query |
IP address or symbolic name of and an SNMP device |
string |
snmp_read_community |
query |
The SNMP read community to use (SNMP v1/v2c only) |
string |
snmp_write_community |
query |
The SNMP write community to use (SNMP v1/v2c only) |
string |
snmp_version |
query |
The SNMP version to use: 2 (SNMP v3), 1 (v2c) or 0 (v1) |
string |
snmp_level |
query |
Used only with SNMP v3: noAuthNoPriv, authNoPriv, or authPriv) |
string |
snmp_auth_protocol |
query |
Used only with SNMP v3 and level not set to noAuthNoPriv: MD5 or SHA |
string |
snmp_auth_passphrase |
query |
Used only with SNMP v3 and level not set to noAuthNoPriv: 8 chars+ passphrase |
string |
snmp_privacy_protocol |
query |
Used only with SNMP v3 and level set to autPriv: DES or AES |
string |
snmp_privacy_passphrase |
query |
Used only with SNMP v3 and level set to autPriv: 8 chars+ passphrase |
string |
Responses
-3 - NOT_GRANTED
-4 - INVALID_HOST
-5 - INVALID_ARGUMENTS
-9 - NAME_RESOLUTION_FAILED
-10 - SNMP_DEVICE_ALREADY_ADDED
-11 - SNMP_DEVICE_UNREACHABLE
-12 - NO_SNMP_DEVICE_DISCOVERED
-22 - SNMP_UNKNOWN_DEVICE
GET lua/pro/rest/v1/change/snmp/device/interface/status.lua
Change SNMP device interface status
Description: Change the status of an SNMP device in terface to up or down
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
host |
query |
IP address of an SNMP device |
string |
snmp_admin_status |
query |
The new admin status, either ‘up’ or ‘down’ |
string |
snmp_port_idx |
query |
The index of the SNMP device interface |
string |
Responses
0 - OK
-3 - NOT_GRANTED
-4 - INVALID_HOST
-5 - INVALID_ARGUMENTS
-26 - SNMP_DEVICE_INTERFACE_STATUS_CHANGE_FAILED
3.4.12. Pools
GET /lua/rest/v1/add/host/pool.lua
Add an host pool
Description: Add an host pool with members and configuration
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-13 - ADD_POOL_FAILED
GET /lua/rest/v1/add/network/pool.lua
Add a local network pool
Description: Add a local network pool with members and configuration
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-13 - ADD_POOL_FAILED
GET /lua/rest/v1/edit/host/pool.lua
Edit an host pool
Description: Edit an host pool with members and configuration
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-14 - EDIT_POOL_FAILED
GET /lua/rest/v1/edit/network/pool.lua
Edit a local network pool
Description: Edit a local network pool with members and configuration
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-14 - EDIT_POOL_FAILED
GET /lua/rest/v1/edit/host_pool/pool.lua
Edit an host pool pool
Description: Edit an host pool pool (only recipients edit is allowed)
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-14 - EDIT_POOL_FAILED
GET /lua/rest/v1/delete/host/pool.lua
Delete an host pool
Description: Delete an host pool
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-16 - POOL_NOT_FOUND
GET /lua/rest/v1/delete/network/pool.lua
Delete a local network pool
Description: Delete a local network pool
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-16 - POOL_NOT_FOUND
GET /lua/rest/v1/delete/pools.lua
Delete all pools for any available pool type
Description: Delete all pools for any available pool type
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
GET /lua/rest/v1/get/host/pools.lua
Get one or all host pools
Description: Get one or all host pools
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-16 - POOL_NOT_FOUND
GET /lua/rest/v1/get/network/pools.lua
Get one or all local network pools
Description: Get one or all local network pools
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-16 - POOL_NOT_FOUND
GET /lua/rest/v1/get/pools.lua
Get all pools of any type
Description: Get all pools defined for any available pool type
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
GET /lua/rest/v1/recipient/pools.lua
Get all pools of any type for a given recipient id
Description: Get all pools defined for any available pool type for a given recipient id
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
recipient_id |
query |
A recipient id |
int16 |
Responses
0 - OK
GET /lua/rest/v1/get/host/pool/members.lua
Get all host pool members
Description: Get all the members of a given host pool
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-16 - POOL_NOT_FOUND
GET /lua/rest/v1/bind/host/pool/member.lua
Bind a member to an host pool
Description: Bind a member to an host pool
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-17 - BIND_POOL_MEMBER_FAILED
GET /lua/rest/v1/get/host/pool_by_member.lua
Get an host pool given a member
Description: Get an host pool given a member
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Responses
0 - OK
-5 - INVALID_ARGUMENTS
POST lua/rest/v1/export/pool/config.lua
Export the pools configuration as a JSON file
Description: Export the configuration of all pools and dependencies (notifications, SNMP, active monitoring, checks
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
download |
query |
Download as file (no REST envelope) |
boolean |
Responses
0 - OK
-3 - NOT_GRANTED
3.4.13. Notification Recipients
GET /lua/rest/v1/delete/recipients.lua
Delete all defined recipients and reset them to factory-defaults
Description: Delete all defined recipients and reset them to factory-defaults
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
3.4.14. Notification Endpoints
GET /lua/rest/v1/delete/endpoints.lua
Delete all defined notification endpoints and reset them to factory-defaults
Description: Delete all defined notification endpoints and reset them to factory-defaults
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
3.4.15. All
GET /lua/rest/v1/get/system/stats.lua
Get system stats
Description: Get statistics of the system on top of which ntopng is running
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
POST lua/rest/v1/export/all/config.lua
Export all configurations as a JSON file
Description: Export all configurations including Pools, Active Monitoring, Notifications (Endpoints and Recipients), Checks, SNMP devices
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
download |
query |
Download as file (no REST envelope) |
boolean |
Responses
0 - OK
-3 - NOT_GRANTED
3.4.16. Active Monitoring
POST lua/rest/v1/export/active_monitoring/config.lua
Export the active monitoring configuration as a JSON file
Description: Export the active monitoring configuration
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
download |
query |
Download as file (no REST envelope) |
boolean |
Responses
0 - OK
-3 - NOT_GRANTED
3.4.17. Notifications
POST lua/rest/v1/export/notifications/config.lua
Export the notifications configuration as a JSON file
Description: Export the configuration for endpoints and recipients
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
download |
query |
Download as file (no REST envelope) |
boolean |
Responses
0 - OK
-3 - NOT_GRANTED
3.4.18.
POST lua/rest/v1/export/scripts/config.lua
Export the Checks configuration as a JSON file
Description: Export the configuration for all checks
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
download |
query |
Download as file (no REST envelope) |
boolean |
Responses
0 - OK
-3 - NOT_GRANTED
POST lua/rest/v1/export/snmp/config.lua
Export the SNMP configuration as a JSON file
Description: Export the configuration for the SNMP devices
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
download |
query |
Download as file (no REST envelope) |
boolean |
Responses
0 - OK
-3 - NOT_GRANTED
POST lua/rest/v1/import/all/config.lua
Import all configurations providing a JSON file
Description: Import all configurations including Pools, Active Monitoring, Notifications (Endpoints and Recipients), Checks, SNMP devices
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-27 - CONFIGURATION_FILE_MISMATCH
-28 - PARTIAL_IMPORT
POST lua/rest/v1/import/active_monitoring/config.lua
Import the active monitoring configuration providing a JSON file
Description: Import the active monitoring configuration
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-27 - CONFIGURATION_FILE_MISMATCH
-28 - PARTIAL_IMPORT
POST lua/rest/v1/import/notifications/config.lua
Import the notifications configuration providing a JSON file
Description: Import the configuration for endpoints and recipients
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-27 - CONFIGURATION_FILE_MISMATCH
-28 - PARTIAL_IMPORT
POST lua/rest/v1/import/pool/config.lua
Import the pools configuration providing a JSON file
Description: Import the configuration of all pools and dependencies (notifications, SNMP, active monitoring, checks
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-27 - CONFIGURATION_FILE_MISMATCH
-28 - PARTIAL_IMPORT
POST lua/rest/v1/import/scripts/config.lua
Import the Checks configuration providing a JSON file
Description: Import the configuration for all checks
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-27 - CONFIGURATION_FILE_MISMATCH
-28 - PARTIAL_IMPORT
POST lua/rest/v1/import/snmp/config.lua
Import the SNMP configuration providing a JSON file
Description: Import the configuration for the SNMP devices
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-27 - CONFIGURATION_FILE_MISMATCH
-28 - PARTIAL_IMPORT
POST lua/rest/v1/reset/all/config.lua
Reset all configurations
Description: Reset all configurations
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
-3 - NOT_GRANTED
POST /lua/pro/rest/v1/check/infrastructure/config.lua
Test an infrastructure configuration
Description: Uses an url and token to connect to the REST API of an ntopng in the infrastructure
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
url |
query |
The URL of the ntopng in the infrastructure |
string |
token |
query |
The REST API Token for the authentication |
string |
Responses
0 - OK
-42 - INFRASTRUCTURE_INSTANCE_ALREADY_EXISTING
-43 - INFRASTRUCTURE_INSTANCE_CHECK_FAILED
-44 - INFRASTRUCTURE_INSTANCE_CHECK_NOT_FOUND
-45 - INFRASTRUCTURE_INSTANCE_CHECK_INVALID_RESPONSE
-46 - INFRASTRUCTURE_INSTANCE_CHECK_AUTH_FAILED
POST lua/rest/v1/get/ntopng/users.lua
Read all configured ntopng users
Description: Read all configured ntopng users
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
-3 - NOT_GRANTED
POST lua/rest/v1/add/ntopng/user.lua
Add ntopng user
Description: Add a ntopng user
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
username |
formData |
Username |
string |
full_name |
formData |
Full name |
string |
password |
formData |
Password |
string |
confirm_password |
formData |
Confirmed password |
string |
user_role |
formData |
User role (unprivileged / administrator) |
string |
allowed_networks |
formData |
Allowed networks (e.g. 0.0.0.0/0,::/0) |
string |
allowed_interface |
formData |
Allowed interfaces (empty for all) |
string |
user_language |
formData |
Language (en, it, de, jp, pt, cz) |
string |
allow_pcap_download |
formData |
Allow PCAPs download (1 to allow) |
string |
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-19 - PASSWORD_MISMATCH
-20 - ADD_USER_FAILED
-23 - USER_ALREADY_EXISTING
POST lua/rest/v1/delete/ntopng/user.lua
Delete ntopng user
Description: Delete a ntopng user
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
username |
formData |
Username |
string |
Responses
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-21 - DELETE_USER_FAILED
POST lua/rest/v1/edit/ntopng/user.lua
Edit a ntopng user
Description: Edit an existing ntopng user
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
username |
formData |
Username |
string |
user_role |
formData |
User role (unprivileged / administrator) |
string |
allowed_networks |
formData |
Allowed networks (e.g. 0.0.0.0/0,::/0) |
string |
allowed_interface |
formData |
Allowed interfaces (empty for all) |
string |
user_language |
formData |
Language (en, it, de, jp, pt, cz) |
string |
allow_pcap_download |
formData |
Allow PCAPs download (1 to allow) |
string |
Responses
-5 - INVALID_ARGUMENTS
-21 - DELETE_USER_FAILED
-23 - USER_DOES_NOT_EXIST
-24 - EDIT_USER_FAILED
POST lua/rest/v1/create/ntopng/session.lua
Create a new ntopng user session Cookie
Description: Generate a new user session to be used as session Cookie
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
username |
formData |
Username |
string |
auth_session_duration |
formData |
Session duration (seconds). Default: 0 (no expiration). |
integer |
Responses
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
POST lua/rest/v1/get/ntopng/session.lua
Create a new ntopng user session Cookie (same as create/ntopng/session.lua)
Description: Generate a new user session to be used as session Cookie
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
username |
formData |
Username |
string |
auth_session_duration |
formData |
Session duration (seconds). Default: 0 (no expiration). |
integer |
Responses
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
GET /lua/pro/rest/v1/get/infrastructure/instance.lua
Get one or all infrastructure configs
Description: Get one or all infrastructure configs
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
Add statistics collected by the active monitoring module |
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-32 - INFRASTRUCTURE_INSTANCE_NOT_FOUND
POST /lua/pro/rest/v1/add/infrastructure/instance.lua
Add a new infrastructure configuration
Description: Add a new infrastructure configuration
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
url |
The URL of the ntopng in the infrastructure |
string |
|
alias |
An alias for the infrastructure |
string |
|
token |
The REST API Token for the authentication |
string |
|
rtt_threshold |
RTT threshold used by the active monitoring |
int32 |
|
bandwidth_threshold |
Bandwidth threshold used by the active monitoring |
int32 |
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-34 - INFRASTRUCTURE_INSTANCE_EMPTY_ALIAS
-35 - INFRASTRUCTURE_INSTANCE_EMPTY_URL
-36 - INFRASTRUCTURE_INSTANCE_EMPTY_TOKEN
-37 - INFRASTRUCTURE_INSTANCE_EMPTY_RTT_THRESHOLD
-39 - INFRASTRUCTURE_INSTANCE_SAME_ALIAS
-40 - INFRASTRUCTURE_INSTANCE_SAME_URL
-41 - INFRASTRUCTURE_INSTANCE_SAME_TOKEN
-42 - INFRASTRUCTURE_INSTANCE_ALREADY_EXISTING
-47 - INFRASTRUCTURE_INSTANCE_EMPTY_BANDWIDTH_THRESHOLD
POST /lua/pro/rest/v1/edit/infrastructure/instance.lua
Edit an existing infrastructure configuration
Description: Edit an existing infrastructure configuration
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
instance_id |
The ID of the infrastructure configuration to edit |
string |
|
url |
The URL of the ntopng in the infrastructure |
string |
|
alias |
An alias for the infrastructure |
string |
|
token |
The REST API Token for the authentication |
string |
|
rtt_threshold |
RTT threshold used by the active monitoring |
int32 |
|
bandwidth_threshold |
Bandwidth threshold used by the active monitoring |
int32 |
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-32 - INFRASTRUCTURE_INSTANCE_NOT_FOUND
-33 - INFRASTRUCTURE_INSTANCE_EMPTY_ID
-34 - INFRASTRUCTURE_INSTANCE_EMPTY_ALIAS
-35 - INFRASTRUCTURE_INSTANCE_EMPTY_URL
-36 - INFRASTRUCTURE_INSTANCE_EMPTY_TOKEN
-37 - INFRASTRUCTURE_INSTANCE_EMPTY_RTT_THRESHOLD
-39 - INFRASTRUCTURE_INSTANCE_SAME_ALIAS
-40 - INFRASTRUCTURE_INSTANCE_SAME_URL
-41 - INFRASTRUCTURE_INSTANCE_SAME_TOKEN
-47 - INFRASTRUCTURE_INSTANCE_EMPTY_BANDWIDTH_THRESHOLD
POST /lua/pro/rest/v1/delete/infrastructure/instance.lua
Delete an existing infrastructure configuration
Description: Delete an existing infrastructure configuration
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
instance_id |
The ID of the infrastructure to delete |
string |
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-32 - INFRASTRUCTURE_INSTANCE_NOT_FOUND
-33 - INFRASTRUCTURE_INSTANCE_EMPTY_ID
POST lua/rest/v1/import/infrastructure/config.lua
Import the Infrastructure configuration providing a JSON file
Description: Import the configuration for all infrastructure configurations
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
-3 - NOT_GRANTED
-5 - INVALID_ARGUMENTS
-27 - CONFIGURATION_FILE_MISMATCH
-28 - PARTIAL_IMPORT
POST lua/rest/v1/export/infrastructure/config.lua
Export the Infrastructure configurations as a JSON file
Description: Export the configuration for the infrastructure configurations
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|---|---|---|
download |
query |
Download as file (no REST envelope) |
boolean |
Responses
0 - OK
-3 - NOT_GRANTED
POST lua/rest/v1/reset/infrastructure/config.lua
Reset all infrastructure configurations
Description: Reset all infrastructure configurations
Produces: [‘application/json’]
Parameters
Name |
Position |
Description |
Type |
|---|
Responses
0 - OK
-3 - NOT_GRANTED