Inventory sync (sites and devices)¶
For customers who keep their device list in BreachSpider and want their own asset system (a CMDB or an OT inventory tool) to keep it up to date. If you only want answers for devices you hold yourself, use the stateless Correlate CVEs call instead: nothing is stored. Findings, acknowledgements, tickets and reports are managed in the web app.
Environments represent physical or logical sites in your OT/ICS infrastructure. Each environment contains assets, which are matched against the CVE corpus to produce findings.
Endpoints¶
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/environments | List all environments |
| POST | /api/v1/environments | Create environment |
| GET | /api/v1/environments/{env_id} | Get environment detail |
| PUT | /api/v1/environments/{env_id} | Update environment |
| DELETE | /api/v1/environments/{env_id} | Delete environment (see Deleting) |
| GET | /api/v1/environments/{env_id}/summary | Risk summary |
| GET | /api/v1/environments/{env_id}/assets | List assets |
| POST | /api/v1/environments/{env_id}/assets | Add asset |
| PUT | /api/v1/environments/{env_id}/assets/{asset_id} | Update asset |
| DELETE | /api/v1/environments/{env_id}/assets/{asset_id} | Remove asset (deactivates it; its Windows host data is deleted) |
| POST | /api/v1/environments/{env_id}/assets/csv-preview | Preview CSV import |
| POST | /api/v1/environments/{env_id}/assets/csv-commit | Commit CSV import |
| GET | /api/v1/environments/template/csv | Download CSV template |
Create an Environment¶
curl -X POST \
-H "Authorization: Bearer bs_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Water Treatment Plant Alpha",
"description": "Primary treatment facility",
"site_type": "water-treatment",
"criticality": "high"
}' \
"https://breachspider.com/api/v1/environments"
Add Assets¶
curl -X POST \
-H "Authorization: Bearer bs_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "SCADA Workstation 01",
"vendor": "Siemens",
"product": "SIMATIC S7-1500",
"version": "2.9.4",
"asset_type": "PLC",
"layer": "OT"
}' \
"https://breachspider.com/api/v1/environments/5/assets"
CSV Bulk Import¶
Download the template, fill it in, preview then commit.
# Step 1 - get template
curl -H "Authorization: Bearer bs_live_..." \
"https://breachspider.com/api/v1/environments/template/csv" \
-o asset_template.csv
# Step 2 - preview (dry run, no changes)
curl -X POST \
-H "Authorization: Bearer bs_live_..." \
-F "[email protected]" \
"https://breachspider.com/api/v1/environments/5/assets/csv-preview"
# Step 3 - commit if preview looks correct
curl -X POST \
-H "Authorization: Bearer bs_live_..." \
-F "[email protected]" \
"https://breachspider.com/api/v1/environments/5/assets/csv-commit"
Plan Limits and Cap Errors¶
Creating environments, adding assets (single and CSV import), and inviting team members are all subject to per-plan caps. The defaults are 1 environment, 50 assets and 2 members on Standard; 10 environments, 1,000 assets and 5 members on Professional; and 25 environments, 5,000 assets and 25 members on Enterprise. These defaults are the floor, not a hard universal ceiling: a per-org override can raise any limit for a custom plan, so the effective limit may be higher.
When a request would exceed the effective cap, the endpoint returns HTTP 403 with a structured cap_exceeded body so you can handle it precisely:
{
"error": {
"code": "FORBIDDEN",
"message": "You have reached your plan limit of 50 assets. Contact sales to raise your limit.",
"detail": {
"error": "cap_exceeded",
"resource": "assets",
"limit": 50,
"current": 50,
"tier": "standard",
"contact_sales": "/contact"
}
}
}
resource is one of environments, assets, or members. limit is the effective cap (after any override), and current is your usage at the time of the request. Existing items above a cap are never removed or disabled; only creating new ones past the limit is blocked. CSV import is all or nothing: if the batch would push you over the asset cap, the whole import is rejected with this same error and nothing is added.
Deleting¶
DELETE /api/v1/environments/{env_id} deactivates the environment and its assets, permanently deletes their findings and any Windows host data (host facts, per-CVE patch status, installed software), and records ENV_DELETED in the audit log. DELETE .../assets/{asset_id} does the same for one asset. Deactivated records are removed for good when the account is deleted (in the web app, Settings).