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.