Skip to content

API overview

The BreachSpider API is a small, stable set of calls for checking devices and Windows hosts against the vulnerabilities that affect their exact versions, looking up CVEs and the product catalog, and (optionally) keeping your inventory in sync from your own systems. It is what the Python SDK, the MCP servers and partner integrations are built on.

https://breachspider.com/api/v1
https://breachspider.com/api/v2   (Windows hosts and the v2 device calls)

What the API covers

Check devices and hosts

Call Use it to
Correlate CVEs POST /api/v1/assets/correlate-cves Check up to 200 devices (vendor, product, version) in one call. Nothing is stored
Check for changes POST /api/v1/assets/correlate-cves/check A cheap repeat check: has anything changed for results you already hold?
Windows hosts POST /api/v2/assets/check-windows Check Windows hosts by build and installed updates
Batch jobs POST /api/v1/batches, POST /api/v2/batches Up to 5,000 devices or 1,000 hosts per job, in the background

Look things up

Call Use it to
CVEs GET /api/v1/cves, /cves/{id}, /cves/search Search CVEs and read one CVE with its affected products and sources
Known-exploited catalog GET /api/v1/cves/kev The CVEs on the known-exploited catalog
Catalog GET /api/v1/catalog/vendors, /catalog/products Find the vendor and product names BreachSpider recognizes
Lifecycle and firmware Vendor support status and firmware currency, as returned with each device check
Health GET /api/v1/health/ping Service status

Keep your inventory in BreachSpider (optional)

Call Use it to
Inventory sync /api/v1/environments Create sites, add, update and remove devices, import a CSV, read a Windows host's patch view

What is not in the API

The web app's own screens (Overview, Fix first, Assets, Maintenance, QR and identifiers, Backups and integrity, reports, settings, billing, training, the assistant and the MSSP pages) run on internal routes that need a signed-in browser session. They are not part of the API, are not documented here, and can change in any release. If you need something the web app shows and the API does not, tell us: we add it to the API on purpose, with a version and notice.

Authentication

Every call above takes an API key: Authorization: Bearer bs_live_.... Create and revoke keys in the web app (Integrations > API keys). The CVE reads and /health/ping also answer without a key, with smaller pages. See Authentication and access and API keys.

Responses, errors and limits

Every call returns the BreachSpider envelope (Response format); errors carry a code and retry_guidance (Errors and retry guidance); limits per key are in Rate limits and usage.

Versioning

Everything under /api/v1/ is stable: fields are never renamed, retyped or removed in place. A breaking change ships under a new version path, and the earlier version keeps running alongside it. New fields, objects, warning codes and enum values can appear at any time, so ignore what you do not recognize. v2 success responses report meta.api_version: "2". Change notes are on Correlate CVEs and Windows hosts.