Understanding the Upcoming NQE API itemFormat Change

We wanted to call your attention to an upcoming NQE API change that was announced in the 25.12 release notes. This post provides additional detail and guidance to help you proactively update affected API integrations ahead of the change.

What’s Changing

In release 26.3, the default value of the itemFormat parameter for NQE API responses will change:

• Current default: LEGACY
• Future default: JSON

This applies to the following API endpoints:

• POST /api/nqe
• POST /api/nqe-diffs/{before}/{after}

Who Is Affected

Most NQE queries will not be impacted.

This change only affects queries that return complex columns — specifically:

• Columns whose values are records / objects
• Or collections of objects embedded as a single cell value

Simple scalar columns (strings, enums, numbers) and lists of simple values (e.g., IP addresses) are unchanged.

Example

Consider the following NQE query:

foreach device in network.devices
let findings = (foreach finding in device.cveFindings
                where finding.isVulnerable
                select { cveId: finding.cveId, basis: finding.basis })
select {
  device: device.name,
  os: device.platform.os,
  ips: device.platform.managementIps,
  findings: findings
}

• device → string
• os → enumerated value
• ips → list of strings
• findings → collection of objects ← this is the affected column

Current Behavior (itemFormat = LEGACY, default today)

When run via the API today, the findings column is returned as a stringified representation of the data:

{
  "device": "sj-dc-vcenter10_sj-dc-esxi-149.net3.org_DSwitch-en10-ext-uplink",
  "os": "ESXI",
  "ips": [
    "172.27.14.11"
  ],
  "findings": "[{cveId:CVE-2025-22224, basis:CveFindingBasis.PLATFORM}, {cveId:CVE-2025-22226, basis:CveFindingBasis.PLATFORM}, {cveId:CVE-2025-22225, basis:CveFindingBasis.PLATFORM}]"
}

New Behavior (itemFormat = JSON)

With itemFormat: "JSON", the same column is returned as structured JSON. All other columns in the result (device, os, ips) are unchanged:

{
  "device": "sj-dc-vcenter10_sj-dc-esxi-149.net3.org_DSwitch-en10-ext-uplink",
  "os": "ESXI",
  "ips": [
    "172.27.14.11"
  ],
  "findings": [
    {
      "cveId": "CVE-2025-22224",
      "basis": "PLATFORM"
    },
    {
      "cveId": "CVE-2025-22226",
      "basis": "PLATFORM"
    },
    {
      "cveId": "CVE-2025-22225",
      "basis": "PLATFORM"
    }
  ]
}

This format is more robust, machine-friendly, and consistent with modern API expectations — but it may break workflows that expect a string value.

Impact Assessment

Queries that return only simple scalar columns (strings, numbers, simple arrays) are completely unaffected by the itemFormat option. This change only impacts queries that include columns containing complex nested data structures, such as the findings column in the example above.

What You Should Do Now

If you have automations or scripts consuming NQE API results that contain complex nested data structures:

• Option 1 (Recommended)
  Update your API calls to explicitly set itemFormat:JSON and modify your client logic to handle structured JSON instead of strings

"itemFormat": "JSON"

• Option 2
  Set itemFormat:”LEGACY” to maintain the current stringified format while you plan your migration.    

"itemFormat": "LEGACY"

• If your queries only return simple scalar columns, no changes are needed.

Questions or Need Help?

If you have questions about how this change may impact your workflows, or would like help validating your usage:

• Reach out to your Customer Success Engineer, or
• Contact Forward Support through your usual support channels
  • https://support.forwardnetworks.com
  • support@forwardnetworks.com

For full release details, see:
https://fwd.app/release-notes/api/release.25.12.0/