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