Environments

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

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",
    "ip_address": "192.168.10.15",
    "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.

Acknowledge a Finding

When your team has reviewed a CVE match and taken action:

curl -X POST \
  -H "Authorization: Bearer bs_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "compensating_control",
    "notes": "Network segment isolated, vendor patch scheduled for next maintenance window"
  }' \
  "https://breachspider.com/api/v1/environments/5/matches/1234/acknowledge"

Acknowledgment reasons: not_applicable, compensating_control, accepted_risk, false_match, escalated