Forward Networks API

Forward Networks API v1.3 can help you automate tasks in the Forward Platform and integrate it with other tools. Use cases include:

  • Triggering network Snapshot collection
  • Automating Check and Alias creation/updates
  • Building custom dashboards and alerts
  • Exporting network Snapshots for sharing or archival purposes

If you have any questions or feedback, please contact us at We’d love to hear from you. Enjoy!

HTTP Verbs

This API strives to use appropriate HTTP verbs for each operation.

Verb Description
GET Used for retrieving resources.
HEAD Used for retrieving only the HTTP headers for resources.
POST Used for creating a resource.
PATCH Used for updating resources with partial JSON data. Only fields that have changed need be supplied.
PUT Used for replacing a resource or collection (creating if it doesn’t exist yet).
DELETE Used for deleting resources.


This API uses Basic Authentication. This means that a Base64-encoded username + password (or username + API token) is sent in the Authorization header of each request. For security reasons, we recommend always using HTTPS.

API tokens can be generated on the account settings page in the application. They work like passwords in API requests, but API tokens are different from passwords in a few key ways:

  1. API tokens can’t be used to log in.
  2. API tokens are randomly generated and thus harder for attackers to guess than many passwords.
  3. API tokens satisfy the two-factor authentication (2FA) requirement in organizations that use 2FA.
  4. API tokens keep working even if you change your password.
  5. API tokens can be deleted at any time.

If you write a program that uses the API with a fixed set of credentials, consider creating a dedicated user account for that purpose—one that has only the access permissions it needs.


In this API, a network is a model of a real network. To represent change over time, a network can have Snapshots, each associated with a specific moment in time. Snapshots are constructed by collecting the current configuration and state of every device in the network, inferring the network’s topology, then building a comprehensive behavioral model.

This section is just about listing, creating, renaming and deleting networks. Throughout the API, networks are referenced by their unique identifier, often called networkId. Some endpoints reference a network indirectly using just a unique Snapshot identifier, often called snapshotId.


Lists all networks



Creates a network



Renames a network



Deletes a network


Network Setup

The resources below are for defining a network’s device sources. A device source is fundamentally a hostname or IP address ("host") and port to which the network’s Collector can connect to gather the configuration and state information needed to model one or more network devices.

A device source can include a "type", a "loginCredentialId" for authentication, and optional settings for fine-tuning the collection process. The Collector will attempt to automatically determine the correct device type and login credentials (from those that have been defined) if those fields aren’t specified.

Define any required device credentials and jump servers first, then reference them by id in device sources. A jump server is an intermediate host through which the Collector can be configured to access device sources that it can’t access directly.

Note: Only a Collector stores and uses passwords and private keys. For this reason, device credential and jump server operations require the network’s Collector to be online.

DeviceCredential Types
Type Fields Referencing DeviceSource Field Purpose
LOGIN usernamepassword loginCredentialId SSH or Telnet
PRIVILEGED_MODE password privilegedModePasswordId Cisco or Cisco-like devices
SHELL usernamepassword shellCredentialId Avi controllers
KEY_STORE contentpassword keyStoreId SSL/TLS (currently for OpenFlow switches only)



Lists a network’s device credentials



Creates or replaces a network device credential



Updates a network device credential



Deletes a network device credential



Gets a network’s device sources



Creates or updates network device sources



Creates or replaces a network device source



Deletes a network device source



Lists a network’s jump servers



Creates or replaces a jump server



Updates a jump server



Deletes a jump server


Network Collection

Use these resources to query the state of a network’s Collector, to trigger a collection of configuration and state from a network’s devices, or to cancel an in-progress collection. The application offers additional Collector configuration options, such as defining a collection schedule.


Cancels an in-progress network collection



Gets the status of a network’s collector



Triggers a network collection


Network Snapshots

Once a network Snapshot has been collected, the Forward Platform processes it to build a model and to compute the results of any Checks defined in the network. Snapshot processing time is typically just a few seconds, but varies by network size and complexity and by available computing power.

The resources in this section are for listing Snapshots, exporting or importing a Snapshot as a .zip file, and deleting Snapshots.


Lists all Snapshots



Imports a Snapshot



Returns the latest processed Snapshot



Exports a Snapshot



Deletes a Snapshot


Network Snapshot Data Files

Sometimes it’s useful to access the raw data that the Forward Platform collected from a device. The resources in this section are for listing and downloading these data files.


Lists a device’s data files


Network Topology

A network’s topology influences the behavior of the network model and how automatic network layout works. The Forward Platform determines what device links to include in its network model using 1) automatic discovery using collected LLDP/CDP information, 2) automatic inference based on the MAC addresses devices have learned, and 3) any user-defined link overrides, which have the highest precedence.

The resources in this section are for listing all of a network’s device links and for listing and defining link overrides. An override is bidirectional and either "present" (the link exists) or "absent" (the link doesn’t exist).


Sets the topology overrides



Gets the network topology



Gets the topology overrides



Edits the topology overrides



Sets the topology overrides


Network Layout

The resources in this section are for accessing and updating the network layout, which is represented as (x, y) coordinates for all devices and their hosts. In the application, the layout coordinate system is oriented such that the positive x-axis points to the right and the positive y-axis points down. The location of the origin is unimportant. The distance unit should be roughly the length of the shortest link in the diagram. Scale is somewhat important, since it can affect how large the application renders network nodes and labels.


Gets the network layout



Updates the network layout



Gets the network layout



Updates the network layout


Path Search

These APIs take description(s) of packets at network ingress as input, trace the packets through the network and return the corresponding paths. Search results are computed in permit all mode, which traces traffic past any ACL drops to determine downstream behavior.


An Alias is a flexible way to group infrastructure elements (like network devices, interfaces, and end hosts) or packet header values (like VLAN IDs, IP addresses, and L4 ports). Aliases simplify the definition of policy checks and help when searching the network.

Here are some examples of Alias definitions in JSON.

Alias Type JSON Notes
  "name": "tor_switches",
  "type": "DEVICES",
  "values": ["dc?-tor*", "tor-*"]
The "values" are device names and/or name patterns containing glob wildcards (e.g. *?[abc][0‑9]).
  "name": "vlan_20_access",
  "type": "INTERFACES",
  "values": ["SF-ACC-0-8 et[12]"]
The "values" are device interface names and/or name patterns. Each name or pattern must contain exactly one space, which separates the device name part from the interface name part.
  "name": "vlan_20_to_29_access",
  "type": "INTERFACES",
  "vlanIds": ["20-29"],
  "vlanIntfTypes": ["ACCESS"]
It can be convenient to define a set of device interfaces using a set of VLAN IDs. "vlanIntfTypes" can be ["TRUNK"]["ACCESS"] or omitted (for both). If "values" is also present, it further restricts the set of matching interfaces.
  "name": "web_servers",
  "type": "HOSTS",
  "values": [""],
  "locations": ["tor_switches"]
The "values" are host names, IP subnets and/or MAC addresses. The "locations" are device or interface names or aliases. At least one of "locations" and "values" must be specified.
Header Values
  "name": "VOIP",
  "type": "HEADERS",
  "values": {
    "eth_type": ["0x800"],
    "ip_proto": ["UDP"],
    "tp_port": ["10000", "20000"]
Supported header types are:

  • mac_addr – MAC addresses
  • eth_type – Ethernet types
  • vlan_vid – VLAN IDs/ranges
  • ip_addr – IP addresses/blocks
  • ip_proto – IP protocols
  • tp_port – L4 ports/ranges

At least one type must be specified.

The resources below are for reading, creating, updating and deleting the Aliases associated with a network Snapshot. Changes to a Snapshot’s Aliases propagate forward to later Snapshots, including future Snapshots.


Checks verify network policy and behavior. They cover security, reachability, fault tolerance, and compliance and can help network operators prevent regressions and confirm that desired end-to-end behavior holds as the network evolves.

There are 5 main types of checks:

  • Existence verifies that specific traffic is allowed between one or more points within the network.
  • Isolation verifies that specific traffic is prohibited between one or more points within the network.
  • Reachability verifies that specific traffic gets delivered to its intended destination.
  • Predefined checks are a library of common checks which apply to typical network designs.
  • NQEBETA (Network Query Engine) checks are custom queries for consistency or policy violations.

Here are some examples of check definitions in JSON.

Type Check JSON Notes

Traffic matches:

from web_servers
status dropped
  "checkType": "Existential",
  "filters": {
    "from": {
      "location": {
        "type": "HostAliasFilter",
        "value": "web_servers"
    "flowTypes": ["DROPPED"]
  "noiseTypes": []
Supported flowTypes values are:

  • VALID – delivered
  • LOOP – ended in a loop
  • BLACKHOLE – dropped, no matching rule
  • DROPPED – dropped by a rule
  • INADMISSIBLE – dropped at edge of network
  • UNREACHABLE – failed ARP resolution

If present, the flowTypes array must contain exactly one value.

The noiseTypes field is required.

Traffic matches:

from admin_servers
with L4 Dest Porthttp
and IP Dest10.1.0.0/16
and notVLAN ID3007
through BB-1
ingress 1-FWALL-1
with L4 Dest Porthttp
to web_servers
status delivered
  "checkType": "Existential",
  "filters": {
    "from": {
      "location": {
        "type": "SubnetLocationFilter",
        "value": ""
      "headers": [
          "type": "PacketFilter",
          "values": {
            "ipv4_dst": [""]
          "type": "NotFilter",
          "clause": {
            "type": "PacketFilter",
            "values": {
              "vlan_vid": ["3007"]
    "chain": [
        "transitType": "ingress",
        "location": {
          "type": "InterfaceFilter",
          "values": ["BB-1 ge-0/0/3"]
        "transitType": "through",
        "location": {
          "type": "DeviceFilter",
          "values": ["1-FWALL-1"]
        "headers": [
            "type": "PacketAliasFilter",
            "value": "http",
            "direction": "dst"
    "to": {
      "location": {
        "type": "HostAliasFilter",
        "value": "web_servers"
    "flowTypes": ["VALID"]
  "noiseTypes": []
The location filter types are:

  • SubnetLocationFilter
    – value: an IP address or subnet
  • HostFilter
    – values: an array containing one host or Edge Node name, IP address, subnet, or MAC address
  • DeviceFilter
    – values: an array containing one device name
  • InterfaceFilter
    – values: an array containing one interface name, qualified with its device name
  • VrfFilter
    – values: an array containing one VRF name, optionally qualified with a device name
  • HostAliasFilter
    – value: a HOSTS Alias name
  • DeviceAliasFilter
    – value: a DEVICES Alias name
  • InterfaceAliasFilter
    – value: an INTERFACES Alias name

The header filter types are:

  • PacketFilter
    – values: an object mapping one header field type to an array containing one header value
  • PacketAliasFilter
    – value: a HEADERS Alias name
    – direction: either src or dst

The most common header field types are:

  • ipv4_src / ipv4_dst
  • ipv6_src / ipv6_dst
  • mac_src / mac_dst
  • tp_src / tp_dst
  • eth_type
  • vlan_vid
  • ip_proto

NotFilter can wrap a filter to negate it.

Each object in chain must specify a transitType of throughingress, or egress.

SubnetLocationFilterHostFilter, and HostAliasFilter are not permitted in the chain array.


No traffic matches:

from internet
to db_servers
status delivered
  "checkType": "Isolation",
  "filters": {
    "from": {
      "location": {
        "type": "InterfaceAliasFilter",
        "value": "internet"
    "to": {
      "location": {
        "type": "HostAliasFilter",
        "value": "db_servers"
    "flowTypes": ["VALID"]
  "noiseTypes": []
Isolation check JSON has the same shape and constraints as Existence check JSON.

All traffic is delivered
to destination:

from web_servers
with L4 Dest PortMySQL
to db_servers
  "checkType": "Reachability",
  "filters": {
    "from": {
      "location": {
        "type": "HostAliasFilter",
        "value": "web_servers"
      "headers": [
          "type": "PacketAliasFilter",
          "value": "MySQL",
          "direction": "dst"
    "to": {
      "location": {
        "type": "HostAliasFilter",
        "value": "db_servers"
  "noiseTypes": []
Reachability check JSON differs from Existence check JSON in a few ways:

  1. from is required.
  2. to is optional and cannot specify header values.
  3. chain is not permitted.
  4. flowTypes is not permitted.
  5. NotFilter is not permitted.

If to is specified, the check verifies that all traffic matching the rest of the query get delivered to the location(s) in the to clause.

If to is not specified, the check verifies that all traffic matching the query gets delivered out of any edge port; none gets dropped or blackholed or enters into a forwarding loop.


VLAN Consistency

VLANs should be
consistently defined on
interfaces on either side
of each link in the network.

  "checkType": "Predefined",
  "predefinedCheckType": "VLAN_CONSISTENCY"
A Predefined check is either on or off for a Snapshot, so a Snapshot should never have more than one check with the same predefinedCheckType.

VLAN Existence

Edge trunk interfaces
must carry all specified

  "checkType": "Predefined",
  "predefinedCheckType": "VLAN_EXISTENCE",
  "params": {
    "interfaces": [
      "SF-ACC-0-0 et3",
      "SF-ACC-0-0 et4",
      "SF-ACC-0-1 et3",
      "SF-ACC-0-1 et4"
    "vlans": ["20-24", "31"]
Each Predefined check type accepts different parameters in the params object. A table below lists them all.

Find every interface whose admin status is up but operational status is not up.

  "checkType": "NQE",
  "name": "interface status consistency",
  "query": "
    foreach device in network.devices
    foreach i in device.interfaces
    where i.adminStatus == AdminStatus.UP
       && i.operStatus != OperStatus.UP
    select {
      adminStatus: i.adminStatus,
      operStatus: i.operStatus
This check iterates through all interfaces on all devices and returns the device name and interface name for each interface whose admin status is UP but operational status is not UP. The check passes if the network has no such interfaces.

For more information about NQE checks and help writing queries, see the Documentation, Data Model, and Examples panes in the application’s NQE check editor.

The table below describes the parameters of each Predefined check type.

Predefined Check Type Parameters
NO_LOOP "noiseTypes": string[]
HOSTNAME_UNIQUENESS "ignoredKeys": string[]
BGP_ROUTE_CONSISTENCY "ignoredDevicePairs": [string, string][]
BGP_NEXT_HOP_REACHABILITY "ignoredKeys": string[]
BGP_NEIGHBOR_ADJACENCY "ignoredKeys": string[]
BGP_ROUTER_ID "ignoredKeys": string[]
EBGP_SELECTION_OVER_IBGP "ignoredKeys": string[]
FHRP_PEERING "ignoredKeys": string[]
DUPLEX_CONSISTENCY "ignoredLinks": string[][]
IP_UNIQUENESS "ignoredIpAddresses": string[]
LINK_SPEED_CONSISTENCY "ignoredLinks": string[][]
MTU_CONSISTENCY "ignoredLinks": string[][]
PORT_CHANNEL_CONSISTENCY "ignoreDownInterfaces": boolean
"internalPortsOnly": boolean
"ignoredLinks": string[][]
"ignoredPortChannels": string[]
SHORTEST_PATH "deviceGroups": string[][]
"noiseTypes": string[]
TRUNK_INTERFACE_WHITELIST "interfaces": string[]
"ignoredKeys": string[]
VLAN_EXISTENCE "interfaces": string[]
"vlans": string[]
"ignoredKeys": string[]
VLAN_CONSISTENCY "checkNativeVlans": boolean
"ignoredLinks": string[][]
"ignoreCommunityLists": boolean
"ignoredKeys": string[]
BGP_COMMUNITY_LIST "patterns": [string, string][]
"ignoredKeys": string[]
LEARNED_MAC_CONSISTENCY "ignoredKeys": string[]
HOSTNAME_CONSISTENCY "pattern": string
"ignoredDevices": string[]
SOFTWARE_VERSION_CONSISTENCY "checkDiscoveredPeers": boolean
"deviceGroups": string[]
"ignoredDeviceGroups": string[]
"ignoredDeviceSets": string[][]
VPC_PARAMETER_CONSISTENCY "ignoredDevicePairs": [string, string][]
VPC_INTERFACE_PARAMETER_CONSISTENCY "ignoredDevicePairs": [string, string][]
VPC_MST_REGION_CONSISTENCY "ignoredDevicePairs": [string, string][]
VPC_DEDICATED_KEEPALIVE_LINK "checkDedicatedVrf": boolean
"ignoredDevicePairs": [string, string][]
VPC_ROLE_PRIORITY "primaryPriority": integer
"secondaryPriority": integer
"ignoredDevicePairs": [string, string][]
VPC_STP_PRIORITY "ignoredDevicePairs": [string, string][]
SSH_RSA_KEY_LENGTH "minKeyLength": integer
"ignoredDevices": string[]

When a new check is added to a Snapshot, its result is immediately evaluated for that Snapshot. Check creation and deletion propagate forward to later Snapshots of the network, just like Aliases.


Gets all checks (with status)



Name Description
snapshotId *


Code Description
    "creationDateMillis": "2020-04-21T22:45:02.126Z",
    "definition": {
      "checkType": "Isolation"
    "description": "string",
    "id": "string",
    "name": "string",
    "status": "NONE"

The system is currently processing this Snapshot.

Note: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the latest Snapshot is done or to identify an alternate Snapshot that has already been processed.

  "apiUrl": "string",
  "httpMethod": "GET",
  "message": "string",
  "reason": {}


Adds a check



Deactivates all checks



Gets a check (with status)



Deactivates a check



Gets available predefined checks