Windows Patch Level (API v2)

API version 2.0 (2026-09-26). Implements the Windows Build and KB Data Contract v0.1.

1. Purpose

API v2 takes the Windows build and update facts you collect from each host and returns, per CVE, whether the host is confirmed open, cleared (patched) or needs review, using Microsoft's own fixed builds and update (KB) data. Without a build, BreachSpider can only say a CVE applies to the Windows release; with a build, it can say whether this host is still exposed.

• Cumulative Windows (Windows 10, Windows 11, Server 2016 and later): the host's os_build is compared with Microsoft's fixed build for that CVE on that product. At or above means cleared; below means confirmed open.
• Legacy Windows (Windows 7, Server 2008 R2, Server 2012 R2): the host's installed_kbs are checked against the fix KB. A later monthly rollup, or a KB that Microsoft lists as replacing the fix, also counts. For CVEs published after end of support, esu_enrolled decides the outcome.
• Build and KB list disagree: the result is needs review. It is never guessed.
• No os_build, or a bare "Windows": the host is not patch-resolved. It stays product-level, as in API v1.

API v1, including POST /api/v1/assets/correlate-cves, is unchanged.

2. Authentication

Send an API key in the Authorization header:

Authorization: Bearer bs_live_...

Each key belongs to one BreachSpider organization and only sees that organization's environments.

Rate limits, per key: 60 requests per minute and 5,000 hosts per minute. Each call accepts at most 200 hosts. For your initial bulk load, we can raise the limits on your key for a set period. The raised limits lapse automatically at the agreed end time.

Logging: we log each request's time, key, path, HTTP status, host count and duration. We never log request or response bodies.

3. Endpoints

Base URL: https://breachspider.com

4. Host fields

These are the contract fields, with the same names in JSON and CSV. An empty value means unknown.

KB list states: - installed_kbs has values: the KB list was collected. - installed_kbs is empty and kb_source is filled: collected, none found. - Both are empty, or both are omitted: not collected.

Legacy Windows hosts need a collected KB list to be patch-resolved.

Installed software (optional, stored only for now). Send it in the installed_software array (JSON) or a second CSV. Fields: asset_id, name, publisher, version. List each host in windows_hosts before sending its software.

Never send: hostnames, domain names, IP or MAC addresses, user names, serial numbers, license keys, install paths, or anything naming a site or customer. A field with one of these names is refused with an error, and nothing in that host record is stored.

5. Validation rules

We validate each host on its own. A refused host does not stop the other hosts in the call.

Warning (the host is accepted):

6. Results

For each accepted host:

Set options.include_cleared (JSON) or include_cleared (CSV form) to false to leave cleared CVEs out of cves[]. They still appear in counts.

Ordering, filters and paging (JSON options, CSV form fields, or /results query parameters, all optional):

Sorting and filters are applied before paging; counts always reports every CVE.

Fix actions for Windows. - Cumulative-servicing Windows (Server 2016 and later, Windows 10/11): every open CVE with a fixed build is grouped under the product's latest cumulative update, whose build is at or above every fixed build, so one install clears them all. The per-CVE KBs it supersedes are listed in kbs_covered. - Legacy servicing (for example Server 2012 R2): Monthly Rollup and Security Only fixes are grouped under the newest monthly rollup the host can install; servicing-stack and standalone security updates keep their own KB. A KB already in the host's installed_kbs is never recommended. - End-of-life hosts not enrolled in ESU: fixes released after end of support are Extended Security Updates, grouped as ESU required (or upgrade the OS), with the ESU KB named in each CVE's priority_reason. They rank below directly installable fixes of the same exploit tier.

data.fix_summary[] lists the top 10 fix actions across every host in the call (rank, fix, product, asset_ids, counts, highest_score). meta.sort and meta.filters echo what was applied.

meta.microsoft_data_as_of is the revision date of the newest Microsoft document behind the results. Microsoft data is refreshed daily, and in full after each monthly release.

End of life. A host is labelled end of life when its Windows version or edition is past Microsoft's end of support. With esu_enrolled: yes, the label applies only after the Extended Security Updates period has ended too.

7. Errors

Errors use BreachSpider's standard error envelope. error.code is the general code (for example RATE_LIMITED). For the v2 errors below, error.detail holds the specific error code, a message and any extra fields such as retry_after. See the example in section 8.

If some hosts are accepted and others refused, the call returns 200 with the refused hosts in data.rejected.

8. Example

Request: two hosts, plus a third that carries a hostname and is refused. Cleared CVEs are left out, and the list is cut to two CVEs per host here.

POST /api/v2/assets/correlate
Authorization: Bearer bs_live_...
Content-Type: application/json

{
  "environment_id": 12,
  "windows_hosts": [
    {
      "asset_id": "A-0417",
      "os_product": "Windows Server 2019 Standard",
      "edition_id": "ServerStandard",
      "display_version": "1809",
      "os_build": "10.0.17763.7792",
      "architecture": "x64",
      "installation_type": "Server",
      "collected_at": "2026-09-25T14:02:00Z"
    },
    {
      "asset_id": "A-0533",
      "os_product": "Windows Server 2012 R2 Standard",
      "edition_id": "ServerStandard",
      "os_build": "6.3.9600.21620",
      "architecture": "x64",
      "installation_type": "Server",
      "installed_kbs": [
        "KB5031419"
      ],
      "kb_source": "WMI QuickFixEngineering",
      "esu_enrolled": "no",
      "collected_at": "2026-09-25T14:02:00Z"
    },
    {
      "asset_id": "A-0600",
      "hostname": "plc-eng-ws",
      "os_product": "Windows 10 Enterprise LTSC 2021",
      "edition_id": "EnterpriseS",
      "os_build": "10.0.19044.6332",
      "architecture": "x64",
      "installation_type": "Client",
      "collected_at": "2026-09-25T14:02:00Z"
    }
  ],
  "options": {
    "include_cleared": false
  }
}

Response (200):

{
  "data": {
    "assets": [
      {
        "asset_id": "A-0417",
        "microsoft_product": "Windows Server 2019",
        "candidate_products": null,
        "patch_resolved": true,
        "end_of_life": false,
        "labels": [],
        "map_note": null,
        "counts": {
          "confirmed_open": 1653,
          "cleared": 3949,
          "needs_review": 3
        },
        "cves": [
          {
            "cve_id": "CVE-2016-9535",
            "status": "confirmed open",
            "fixed_build": "10.0.17763.7919",
            "kb": "KB5066586",
            "source": "https://api.msrc.microsoft.com/cvrf/v3.0/cvrf/2025-Oct",
            "severity": "Critical",
            "known_exploited": false,
            "note": null
          },
          {
            "cve_id": "CVE-2020-17103",
            "status": "confirmed open",
            "fixed_build": "10.0.17763.8880",
            "kb": "KB5094123",
            "source": "https://api.msrc.microsoft.com/cvrf/v3.0/cvrf/2020-Dec",
            "severity": "Important",
            "known_exploited": false,
            "note": null
          }
        ],
        "warnings": []
      },
      {
        "asset_id": "A-0533",
        "microsoft_product": "Windows Server 2012 R2",
        "candidate_products": null,
        "patch_resolved": true,
        "end_of_life": true,
        "labels": [
          "end of life"
        ],
        "map_note": null,
        "counts": {
          "confirmed_open": 1937,
          "cleared": 2074,
          "needs_review": 9
        },
        "cves": [
          {
            "cve_id": "CVE-2016-9535",
            "status": "confirmed open",
            "fixed_build": "6.3.9600.22824",
            "kb": "KB5066873",
            "source": "https://api.msrc.microsoft.com/cvrf/v3.0/cvrf/2025-Oct",
            "severity": "Critical",
            "known_exploited": false,
            "note": null
          },
          {
            "cve_id": "CVE-2022-0001",
            "status": "confirmed open",
            "fixed_build": "6.3.9600.21924",
            "kb": "KB5036960",
            "source": "https://api.msrc.microsoft.com/cvrf/v3.0/cvrf/2024-Apr",
            "severity": "Important",
            "known_exploited": false,
            "note": null
          }
        ],
        "warnings": []
      }
    ],
    "rejected": [
      {
        "asset_id": "A-0600",
        "errors": [
          {
            "code": "forbidden_field",
            "field": "hostname",
            "message": "Field 'hostname' is not accepted: identifying data must not be sent. The field was not stored."
          }
        ]
      }
    ],
    "software_stored": 0,
    "software_rejected": []
  },
  "meta": {
    "api_version": "2",
    "microsoft_data_as_of": "2026-09-25T07:00:00+00:00",
    "took_ms": 1793
  }
}

A-0417 is a Server 2019 host about a year behind: 1,653 CVEs are confirmed open and 3,949 are cleared by its build. A-0533 is Server 2012 R2 without ESU, past end of support: CVEs Microsoft published after 10 October 2023 are open because no ESU fix can be installed, and older CVEs are checked against its October 2023 monthly rollup. A-0600 was refused and nothing from it was stored. The other hosts in the call were still processed.

Error example (429):

{
  "api": {"version": "1.0.0", "request_id": "bs-req-...", "timestamp": "2026-09-26T02:45:49Z"},
  "error": {
    "code": "RATE_LIMITED",
    "message": "Per-key limit is 60 requests and 5000 hosts per minute.",
    "detail": {"error": "rate_limited", "message": "Per-key limit is 60 requests and 5000 hosts per minute.", "retry_after": 10}
  }
}

9. CSV equivalent

POST /api/v2/assets/correlate-csv takes a multipart form with these parts:

asset_id,os_product,edition_id,display_version,os_build,architecture,installation_type,installed_kbs,kb_source,esu_enrolled,collected_at
A-0417,Windows Server 2019 Standard,ServerStandard,1809,10.0.17763.7792,x64,Server,,,,2026-09-25T14:02:00Z
A-0533,Windows Server 2012 R2 Standard,ServerStandard,,6.3.9600.21620,x64,Server,KB5031419,WMI QuickFixEngineering,no,2026-09-25T14:02:00Z

curl -X POST https://breachspider.com/api/v2/assets/correlate-csv \
  -H "Authorization: Bearer bs_live_..." \
  -F environment_id=12 -F [email protected] -F [email protected]

The CSV upload runs the same validation and the same processing as the JSON call, and returns the same response. The same hosts give identical results either way; and our tests check this on every release.