A streaming API for evidence-based scans.

Validates the URL, applies rate and concurrency limits, creates a scan record, and starts the analysis pipeline. The response is an NDJSON stream with one JSON object per line.

Request body

Rate and concurrency controls

The defaults are 5 scans per minute and 30 per hour per client, with up to 4 concurrent scans. Configure with SCAN_RATE_LIMIT_PER_MINUTE, SCAN_RATE_LIMIT_PER_HOUR, and MAX_CONCURRENT_SCANS. The limiter is process-local; use a shared store for multi-instance deployments.

By default, forwarded client-IP headers are not trusted. Set TRUST_PROXY=true only when a trusted reverse proxy overwrites them, and set RATE_LIMIT_SALT to a random value.

Accounts and authentication

The scan endpoint is anonymous by default. A signed-in session is optional and raises the daily limit according to the plan. Anonymous callers are limited by a guest quota and the per-IP rate limiter; signed-in callers use their plan quota.

Daily quotas use UTC calendar days and reset at 00:00 UTC. Exceeding a quota returns 429 QUOTA_EXCEEDED with a Retry-After header.

Account, subscription, and billing endpoints require a signed-in session and a CSRF token (x-securvex-csrf). Full details are in the API reference.

Progress stream

Each line is a complete JSON object. Stage events describe progress; the final event is either complete or error.

{"type":"stage","stage":"reputation","label":"Querying threat-intelligence providers","status":"running","progress":18}

{"type":"complete","scanId":"V1StGXR8_Z5jdHi6B-myT","verdict":"Elevated risk","score":57,"progress":100}

{"type":"error","error":{"code":"SCAN_FAILED","message":"The scan could not be completed. No clean result was produced. Please try again."}}

Progress events are intentionally not a security boundary. Do not treat a stage status as a verdict; use the deterministic verdict in the completed report.

Returns the stored JSON report. Reports are addressed by a random, unguessable identifier and expire according to the deployment policy. Failed, running, missing, or expired reports return 404.

curl http://localhost:3000/api/scan/V1StGXR8_Z5jdHi6B-myT

The response is a complete report object with target, verdict, summary, evidence, providers, checks, scoring groups, limitations, and retention information. The HTML report is available at /scan/{publicId}.

Reports database health and which capabilities are configured. It never returns API keys or secrets. A healthy service returns 200; a database failure returns 503 with status: "degraded".

{
  "status": "ok",
  "timestamp": "2026-10-19T12:00:00.000Z",
  "database": { "ok": true },
  "providers": [
    { "id": "google_safe_browsing", "name": "Google Safe Browsing", "configured": false },
    { "id": "virustotal", "name": "VirusTotal", "configured": false },
    { "id": "urlhaus", "name": "URLhaus (abuse.ch)", "configured": false },
    { "id": "phishunt", "name": "Phishunt community feed", "configured": true }
  ],
  "ai": { "provider": "none", "configured": false, "model": null }
}

Deletes expired scan records. The endpoint is disabled unless CRON_SECRET is configured. Send the secret as a bearer token. Run this from a scheduler; the default retention period is 30 days.

curl -X POST http://localhost:3000/api/maintenance/retention \
  -H "Authorization: Bearer $CRON_SECRET"

The response contains the number of deleted records. Do not expose the secret to the browser or commit it to source control.

Error codes

Normal API errors use a JSON object with an error code, message, and optionally a retry delay. A failure after the stream begins is delivered as an NDJSON error event.