Skip to main content

Network diagnostics API

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to Device Configuration APIs.

Overview​

The VAPIX® Network diagnostics API allows you to interact with various diagnostic tools for troubleshooting network issues.

Authentication​

For detailed information on how to authenticate requests to this API, please refer to Authentication.

Use Cases​

Get sampling interval​

Use the network-diagnostics.v1.netstats.samplingInterval to find the interval at which the retransmissions are sampled.

Example:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/network-diagnostics/v1/netstats/samplingInterval
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": 300
}

Get TCP retransmissions information​

Use the trigger network-diagnostics.v1.netstats.tcpRetransmissions to get the number of TCP retransmissions in the last number of specified hours. Specifying 0 returns the total amount of retransmissions recorded on the device. The device buffers a limited number of retransmissions samples and overwrites older data after a few days.

Example:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/network-diagnostics/v1/netstats/tcpRetransmissions
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": 1515
}

Use the trigger network-diagnostics.v1.netstats.tcpRetransmissionSpikes to get the last number of specified spikes. Specifying 0 returns all buffered spikes. The device stores up to 1024 spikes. When the limit is reached, the oldest spikes are replaced by new ones.

Example:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/network-diagnostics/v1/netstats/tcpRetransmissionSpikes
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        {
            "retransmissions": 807,
            "timestamp": "2026-02-19T11:00:08Z"
        },
        {
            "retransmissions": 103,
            "timestamp": "2026-02-19T11:26:58Z"
        },
        {
            "retransmissions": 375,
            "timestamp": "2026-02-19T11:26:31Z"
        },
        {
            "retransmissions": 511,
            "timestamp": "2026-02-19T11:26:28Z"
        }
    ]
}

Check if an address is reachable​

Use the trigger network-diagnostics.v1.connectivity.pingTest to test if an address is reachable via ICMP ping. The request takes a PingRequest object with the target IP address.

The response is a boolean indicating whether the device responded.

Example, test passed:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/network-diagnostics.v1.connectivity.pingTest
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "success": true
    }
}

Example, test failed:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/network-diagnostics.v1.connectivity.pingTest
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "success": false
    }
}

Test TCP connectivity​

Use the trigger network-diagnostics.v1.connectivity.tcpTest to test whether a service is reachable by performing a TCP connection request. The request takes a TcpTestRequest object with the target IP address, port number, and optional timeout and network interface parameters. Omitting it or specifying 0 as the timeout uses the default of 1 second. If network interface is omitted, the operating system routing table selects the outgoing interface automatically.

The response is a boolean indicating whether the TCP request succeeded.

Example with no network interface or timeout specified:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/network-diagnostics.v1.connectivity.tcpTest
POST /config/rest/network-diagnostics.v1.connectivity.tcpTest
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": true
}

Example with a specific network interface and timeout, test failed:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/network-diagnostics.v1.connectivity.tcpTest
POST /config/rest/network-diagnostics.v1.connectivity.tcpTest
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": false
}

Get active network connections​

Use the network-diagnostics.v1.connectivity.connectionList trigger to get the list of active network connections on the device. The request takes an empty ConnectionListRequest object.

The response is an array of connection entries, each containing the protocol, address, port, service name ('unknown' if the port has no registered service name), connection state, and owned process information.

Example:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/network-diagnostics.v1.connectivity.connectionList
POST /config/rest/network-diagnostics.v1.connectivity.connectionList
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        {
            "protocol": "UDP",
            "address": "0.0.0.0",
            "port": 49152,
            "state": "STATELESS",
            "service": "unknown",
            "pid": 5678,
            "process": "myapp"
        },
        {
            "protocol": "TCP",
            "address": "192.168.0.100",
            "port": 443,
            "state": "ESTABLISHED",
            "service": "https",
            "pid": 1234,
            "process": "nginx"
        }
    ]
}

API definition​

Structure​

network-diagnostics.v1 (Root Entity)
    ├── connectivity (Entity)
        ├── connectionList (Action)
        ├── pingTest (Action)
        ├── tcpTest (Action)
    ├── netstats (Entity)
        ├── samplingInterval (Property)
        ├── tcpRetransmissionSpikes (Action)
        ├── tcpRetransmissions (Action)

Entities​

network-diagnostics.v1​

  • Description: Tools used to diagnose network issues.
  • Type: Singleton
  • Operations
    • Get
  • Attributes
    • Dynamic Support: No
Properties​

This entity has no properties.

Actions​

This entity has no actions.

network-diagnostics.v1.connectivity​

  • Description: Interface for network connectivity tests.
  • Type: Singleton
  • Operations
    • Get
  • Attributes
    • Dynamic Support: No
Properties​

This entity has no properties.

Actions​
connectionList​
  • Description: Get a list of active network connections.
  • Request Datatype: ConnectionListRequest
  • Response Datatype: ConnectionList
  • Trigger Permissions: admin
  • Attributes
    • Dynamic Support: No
pingTest​
  • Description: Ping a target IP address.
  • Request Datatype: PingRequest
  • Response Datatype: TestResult
  • Trigger Permissions: admin
  • Attributes
    • Dynamic Support: No
tcpTest​
  • Description: Send a TCP request to an IP address.
  • Request Datatype: TcpTestRequest
  • Response Datatype: TestResult
  • Trigger Permissions: admin
  • Attributes
    • Dynamic Support: No

network-diagnostics.v1.netstats​

  • Description: Interface that retrieves network statistics
  • Type: Singleton
  • Operations
    • Get
  • Attributes
    • Dynamic Support: No
Properties​
samplingInterval​
  • Description: The interval at which retransmissions and spikes are sampled in seconds.
  • Datatype: integer
  • Operations
    • Get (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​
tcpRetransmissionSpikes​
  • Description: Get an array of the last N TCP retransmission spikes. Specifying 0 spikes gets all recorded spikes.
  • Request Datatype: PositiveInteger
  • Response Datatype: TcpRetransmissionSpikes
  • Trigger Permissions: admin
  • Attributes
    • Dynamic Support: No
tcpRetransmissions​
  • Description: Get number of TCP retransmissions in the last N hours. Specifying 0 hours gets all retransmissions recorded.
  • Request Datatype: PositiveInteger
  • Response Datatype: PositiveInteger
  • Trigger Permissions: admin
  • Attributes
    • Dynamic Support: No

Data types​

ConnectionEntry​

  • Description: A single network connection entry
  • Type: complex
  • Fields
    • address
      • Description: Local bound or remote peer IP address of the connection
      • Type: IpAddress
      • Nullable: No / Gettable: Yes
    • pid
      • Description: Process ID of the owning process
      • Type: PositiveInteger
      • Nullable: No / Gettable: Yes
    • port
      • Description: Port number of the connection
      • Type: PortNumber
      • Nullable: No / Gettable: Yes
    • process
      • Description: Name of the owning process
      • Type: string
      • Nullable: No / Gettable: Yes
    • protocol
      • Description: Network protocol used by the connection
      • Type: Protocol
      • Nullable: No / Gettable: Yes
    • service
      • Description: IANA service name associated with the port number, e.g. http, https or ssh; empty if the port has no registered service name
      • Type: string
      • Nullable: No / Gettable: Yes
    • state
      • Description: Current state of the connection
      • Type: ConnectionState
      • Nullable: Yes / Gettable: Yes

ConnectionList​

  • Description: A list of active network connections
  • Type: array
  • Element type: ConnectionEntry
  • Null Value: No

ConnectionListRequest​

  • Description: Empty request
  • Type: complex

ConnectionState​

  • Description: Connection state; UDP connections use STATELESS
  • Type: string
  • Enum Values: "LISTEN", "ESTABLISHED", "TIME_WAIT", "STATELESS"

IpAddress​

  • Description: IPv4 or IPv6 address type
  • Type: string

IsoTimestamp​

  • Description: Timestamp of the spike in ISO 8601 RFC3339 format
  • Type: string
  • Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$

PingRequest​

  • Description: Parameters for a ping request
  • Type: complex
  • Fields
    • address
      • Description: The IP address to ping
      • Type: IpAddress
      • Nullable: No / Gettable: Yes

PortNumber​

  • Description: A valid TCP or UDP port number
  • Type: integer
  • Minimum Value: 1
  • Maximum Value: 65535

PositiveInteger​

  • Description: An integer which is either zero or greater than zero
  • Type: integer
  • Minimum Value: 0

Protocol​

  • Description: Network protocol identifier
  • Type: string
  • Enum Values: "TCP", "UDP"

TcpRetransmissionSpike​

  • Description: Representation of a TCP retransmission spike
  • Type: complex
  • Fields
    • retransmissions
      • Description: Magnitude of the spike
      • Type: PositiveInteger
      • Nullable: No / Gettable: Yes
    • timestamp
      • Description: Timestamp of the spike
      • Type: IsoTimestamp
      • Nullable: No / Gettable: Yes

TcpRetransmissionSpikes​

  • Description: A list of retransmission spikes
  • Type: array
  • Element type: TcpRetransmissionSpike
  • Null Value: No

TcpTestRequest​

  • Description: Data to be used in TCP connection request
  • Type: complex
  • Fields
    • address
      • Description: The IP address to send TCP connection request to
      • Type: IpAddress
      • Nullable: No / Gettable: Yes
    • interface
      • Description: The local network interface to bind the connection to, such as eth0. If omitted, the operating system routing table will select the outgoing interface automatically
      • Type: string
      • Nullable: Yes / Gettable: Yes
    • port
      • Description: The port number to be used for TCP connection request
      • Type: PortNumber
      • Nullable: No / Gettable: Yes
    • timeout
      • Description: Optional timeout in seconds for TCP connection request. If omitted or set to 0, default 1 second-timeout is used
      • Type: PositiveInteger
      • Nullable: Yes / Gettable: Yes

TestResult​

  • Description: Connectivity test result
  • Type: complex
  • Fields
    • success
      • Description: Device or service reachability test result
      • Type: boolean
      • Nullable: No / Gettable: Yes