API Reference

BLACKOUT provides a REST API for programmatic access to scanning, findings, and evidence packs.

Base URL

https://app.deployblackout.com/api

Authentication

All API requests require authentication via API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.deployblackout.com/api/sites

Generate API keys in Settings > API Keys.

Sites

List Sites

GET /api/sites

Response:

{
  "sites": [
    {
      "id": 1,
      "hostname": "example.com",
      "name": "Example Site",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Create Site

POST /api/sites
Content-Type: application/json
 
{
  "hostname": "example.com",
  "name": "Example Site"
}

Get Site

GET /api/sites/{siteId}

Scans

Initiate Scan

POST /api/scan-lite
Content-Type: application/json
 
{
  "url": "https://example.com",
  "depth": "quick"
}

Parameters:

Field	Type	Description
`url`	string	Target URL to scan
`depth`	string	`quick`, `full`, or `deep`

Response:

{
  "scan_id": "abc123",
  "status": "queued"
}

Get Scan Status

GET /api/intel/scan/{scanId}

Response:

{
  "id": "abc123",
  "status": "completed",
  "hostname": "example.com",
  "vendor_count": 15,
  "started_at": "2024-01-15T10:00:00Z",
  "completed_at": "2024-01-15T10:01:30Z"
}

Download Scan Pack

GET /api/intel/scan/{scanId}/pack

Returns ZIP file with evidence pack.

Response Headers:

Header	Description
`Content-Type`	`application/zip`
`Content-Disposition`	`attachment; filename="scan_pack_{id}_{date}.zip"`
`X-Bundle-Hash`	SHA-256 deterministic hash for verification
`X-Artifact-Count`	Number of artifacts in pack

Findings

List Findings

GET /api/findings

Query Parameters:

Param	Type	Description
`site_id`	number	Filter by site
`status`	string	`new`, `known`, `changed`, `resolved`
`recommendation`	string	`kill`, `contain`, `watch`, `safe`
`limit`	number	Max results (default 50)
`offset`	number	Pagination offset

Response:

{
  "findings": [
    {
      "id": 123,
      "vendor_id": "rb2b",
      "vendor_name": "RB2B",
      "bti_categories": ["visitor_identification"],
      "btss_score": 25,
      "baseline_status": "new",
      "recommendation": null,
      "first_seen": "2024-01-15T10:00:00Z",
      "last_seen": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 47
}

Get Finding

GET /api/findings/{findingId}

Classify Finding

PATCH /api/findings/{findingId}
Content-Type: application/json
 
{
  "recommendation": "kill",
  "rationale": "Unauthorized data collection"
}

Download Finding Pack

GET /api/findings/{findingId}/pack

Returns ZIP file with evidence pack for this finding.

Response Headers:

Header	Description
`Content-Type`	`application/zip`
`Content-Disposition`	`attachment; filename="finding_pack_{id}_{date}.zip"`
`X-Bundle-Hash`	SHA-256 deterministic hash for verification
`X-Artifact-Count`	Number of artifacts in pack

Drift

List Drift Events

GET /api/sites/{siteId}/drift

Query Parameters:

Param	Type	Description
`acknowledged`	boolean	Filter by acknowledgment status
`severity`	string	`info`, `low`, `medium`, `high`, `critical`
`since`	ISO date	Events after this time

Acknowledge Drift

POST /api/drift/{driftId}/acknowledge

Baseline

Get Current Baseline

GET /api/sites/{siteId}/baseline

Refresh Baseline

POST /api/sites/{siteId}/baseline/refresh

Creates new baseline from latest scan.

Reports

Weekly Brief PDF

GET /api/reports/weekly-brief
GET /api/reports/weekly-brief?site_id={siteId}
GET /api/reports/weekly-brief?weeks_ago=1
GET /api/reports/weekly-brief?format=json

Returns executive risk brief PDF (2 pages).

Query Parameters:

Param	Type	Description
`site_id`	number	Filter to specific site
`weeks_ago`	number	0 = current week (default), 1 = last week
`format`	string	`pdf` (default) or `json` for raw data

Response Headers:

Header	Description
`Content-Type`	`application/pdf`
`Content-Disposition`	`attachment; filename="weekly_brief_{site}_{date}.pdf"`
`X-Report-ID`	Unique report identifier (WB-2025-W50-XXXX)
`X-Period-Start`	Report period start date
`X-Period-End`	Report period end date

Report Contents:

Page 1: Executive summary, BTSS risk score, findings table, drift activity
Page 2: Remediation status, priority action items, analyst recommendations

Webhooks

Configure webhooks in Settings > Integrations > Webhooks.

Event Types

Event	Payload
`scan.completed`	Scan result summary
`drift.detected`	Drift event details
`finding.created`	New finding data
`finding.classified`	Classification update

Webhook Payload

{
  "event": "drift.detected",
  "timestamp": "2024-01-15T10:00:00Z",
  "data": {
    "drift_id": 456,
    "site_id": 1,
    "drift_type": "vendor_added",
    "severity": "high",
    "vendor_id": "unknown_tracker"
  }
}

Rate Limits

Endpoint	Limit
Scans	10/hour
Findings	100/minute
Downloads	50/hour

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

Errors

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retry_after": 60
  }
}

Code	HTTP Status	Meaning
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource doesn't exist
`RATE_LIMITED`	429	Too many requests
`SERVER_ERROR`	500	Internal error

Design System Control Library