API reference

Authentication

Two authentication methods are supported. Many endpoints are public and require no authentication.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

X-API-Key: vs_live_xxxxxxxxxxxxxxxxxxxx
# or
Authorization: Bearer vs_live_xxxxxxxxxxxxxxxxxxxx

Exceeded limits return 429 Too Many Requests.

Errors

All errors follow a consistent format with a machine-readable code and human-readable message.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "report not found",
    "details": null
  }
}

Response envelope

All responses are wrapped in a standard envelope. Exactly one of data or error is present. List endpoints include a meta object with pagination info.

// Success (single item)
{ "data": { ... } }

// Success (paginated list)
{ "data": [ ... ], "meta": { "page": 1, "per_page": 25, "total": 100 } }

// Error
{ "error": { "code": "...", "message": "...", "details": null } }

Register, login, and manage JWT tokens. Use the access token as a Bearer token for authenticated endpoints, or generate API keys for programmatic access.

Submit, search, and retrieve IOC (Indicator of Compromise) reports. Public endpoints require no authentication; authenticated endpoints provide full report data.

Operator-first lookup for domains, ASNs, and exact IPv4 / IPv6 hosts, plus hash-based lookup when you already have a canonical SHA-256 artifact hash.

Community bounty board for requesting specific IOC investigations. Users can create requests, and others can fulfill them by submitting matching reports.

Find related reports by shared infrastructure — IP address, domain, or nameserver.

Check whether an IPv4 or IPv6 address matches the vspam.org IP reputation blocklist. Returns the raw matched entry plus optional scoring-V2 read overlays so operators can distinguish a direct match from the effective enforcement decision.

Community voting on IOC reports. Votes affect confidence scores and can promote reports to the DNSBL blocklist.

Create and manage API keys for programmatic access. Pass keys via the X-API-Key header or Authorization: Bearer header.

View reporter profiles, reputation scores, and credit history from community contributions.

Platform-wide statistics, trends, and geographic distribution. All endpoints are public and cached.

Register HTTP endpoints to receive push notifications when IOC events occur. Webhooks auto-disable after 10 consecutive delivery failures.

Subscribe to IOC patterns and receive alerts when new reports match. Supports keyword, exact, domain, and IP matching.

Server-Sent Events stream for live updates. Connect via EventSource with JWT passed as a query parameter (EventSource cannot set headers). Events: report:new, report:status, vote:new.

Operator-focused feeds identified by slug. Each feed exposes publication thresholds plus explicit operator intent so you can distinguish direct block, watch, context, and policy surfaces before wiring them into enforcement.

Download confirmed IOCs in STIX 2.1, MISP, CSV, JSON, or plain text format. All feed endpoints require authentication. Supports time windowing. The generic feeds are broad exports, so recommended operator action is exposed in metadata and headers to help you decide whether to block directly or apply stricter local filtering first.

Standard TAXII 2.1 endpoints for automated threat intelligence sharing. Compatible with STIX/TAXII clients like OpenCTI, MISP, and Cortex XSOAR.

Fingerprinted phishing kits clustered by structural similarity. Each kit groups reports that share page structure, forms, or resources.

Leaderboard and analytics for brands targeted by phishing campaigns.

Request removal of false-positive IOCs from the active DNSBL. Public endpoints — no authentication required. Protected by Turnstile captcha.

Chronological lifecycle events for a report — from submission through confirmation, DNSBL promotion, feed publication transitions, abuse notifications, and takedown.

Detailed contribution statistics for a reporter — activity heatmap, category breakdown, IOC types, streaks, and top targeted brands.

In-app notification system for report confirmations, vote activity, and other alerts.

Upload evidence screenshots for phishing reports via presigned URLs. Supports PNG, JPEG, WebP, and GIF. Presigned URLs expire in 15 minutes.

Track API usage across your keys — request counts, tier limits, and daily history.