API Reference

Analyze an email with the PhishStack BERT model. Accepts JSON or multipart form data.

Request (JSON)

curl -X POST http://localhost:3000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"email_content": "Subject: URGENT...\n\nClick http://bad.example/verify"}'

Response

{
  "verdict": "MALICIOUS",
  "risk_score": 99,
  "phishing_confidence": 0.9999,
  "model_used": "PhishStack BERT",
  "processing_time_ms": 1180,
  "header_auth_status": "unavailable",
  "urls_analyzed": 1,
  "attachments_analyzed": 0,
  "key_indicators": [
    { "type": "Urgency or Pressure", "description": "...", "severity": "medium" }
  ]
}

Fields: subject + body are also accepted instead of email_content. For files, POST multipart/form-data with a file field (.eml/.msg/.txt).

Real site statistics (persisted in Postgres). Returns "available": false with null values if the stats store is unreachable, never fabricated numbers.

{ "available": true, "total_analyzed": 182, "malicious_domains": 40, "community_reports": 40 }

Recently detected phishing URLs. Query param limit (default varies).

{
  "count": 5,
  "urls": [
    {
      "url": "https://secure-bank-verification.com/verify-account",
      "domain": "secure-bank-verification.com",
      "phishing_confidence": 0.9999,
      "threat_score": 99.9,
      "detection_date": "2026-06-14T13:45:30Z"
    }
  ]
}

Public, anonymized indicators of compromise (IOCs). Query params: limit (max 1000), ioc_type (url / domain / ip).

curl "http://localhost:3000/api/v1/threats?limit=5&ioc_type=url"

Service health check.

{ "status": "healthy", "version": "1.0.0", "timestamp": "..." }

Response codes

Python example

import requests

# Analyze an email
r = requests.post("http://localhost:3000/api/analyze",
                  json={"email_content": "Subject: Hi\n\nPlease verify your account."})
result = r.json()
print(result["verdict"], result["risk_score"], result["model_used"])

# Pull recent detections
threats = requests.get("http://localhost:3000/api/community/recent_urls?limit=10").json()
for t in threats["urls"]:
    print(t["url"], t["phishing_confidence"])