API Documentation

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

Rate Limits

Limits are enforced per API key or IP address. 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 } }

Authentication

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

Reports

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

IOC Lookup

Fast single-value lookup by SHA-256 hash. The public endpoint returns minimal data; the authenticated endpoint returns the full report.

IOC Requests

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

Pivot Search

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

IP RBL

Check whether an IPv4 or IPv6 address is listed in the vspam.org IP reputation blocklist. Returns listing details including confidence score and linked report count.

Votes

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

API Keys

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

Profile & Credits

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

Statistics

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

Webhooks

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

Watchlist

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

Real-time Events (SSE)

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.

Named Feeds

Per-category IOC feeds identified by slug. List available feeds or download a specific feed's IOCs in CSV, JSON, or plain text. Public listing; downloads require authentication.

Threat Feeds

Download confirmed IOCs in STIX 2.1, MISP, CSV, JSON, or plain text format. All feed endpoints require authentication. Supports time windowing.

TAXII 2.1

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

Phishing Kits

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

Targeted Brands

Leaderboard and analytics for brands targeted by phishing campaigns.

Delist Requests

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

Report Timeline

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

Reporter Stats

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

Notifications

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

Evidence Uploads

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

Usage & Billing

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