Phishing Detection API

Detect phishing and policy violations in marketplace messages. Designed for server-to-server integrations using API keys.

Base URL

Production: https://api.pasteproof.com

Authentication

All endpoints below are under the backend auth middleware (/v1/*). Clients authenticate using one of:

User session: Authorization: Bearer <user_jwt>
API key: X-API-Key: pp_...

Detect Phishing

This endpoint is intended for server-to-server integrations. Use an API key in the X-API-Key header.

Endpoint:

POST /v1/phishing/detect

Headers:

X-API-Key: pp_...
Content-Type: application/json

Request:

{
  "message": {
    "text": "Hi, pay me via Venmo outside the platform. Click https://example.com to confirm.",
    "senderId": "sender-123",
    "timestamp": "2026-01-21T12:00:00Z",
    "messageId": "msg-abc"
  },
  "conversationHistory": [
    { "text": "Is this still available?", "senderId": "buyer-1", "timestamp": "2026-01-21T11:59:00Z", "role": "buyer" }
  ],
  "userContext": {
    "accountAgeDays": 720,
    "location": { "country": "US" },
    "purchaseHistory": { "totalPurchases": 10, "averageOrderValue": 120 }
  },
  "senderContext": {
    "accountAgeDays": 2,
    "location": { "country": "JP" },
    "reputationScore": 10,
    "recentActivity": { "similarMessages": 12 }
  },
  "platformContext": {
    "marketplaceType": "discogs",
    "listingId": "listing-1",
    "transactionId": "tx-1",
    "category": "vinyl"
  }
}

Response (200):

{
  "success": true,
  "analysis": {
    "riskScore": 0,
    "riskLevel": "low",
    "confidence": 0,
    "indicators": [],
    "patternMatches": { "suspiciousUrls": [], "keywords": [] },
    "aiAnalysis": null,
    "behavioralFlags": [],
    "recommendedActions": [{ "action": "allow", "priority": "low", "reason": "Low risk - appears legitimate" }]
  },
  "metadata": {
    "analyzedAt": "2026-01-21T12:00:01Z",
    "analysisTimeMs": 123,
    "model": "llama-3.1-8b-instant",
    "version": "1.0.0"
  }
}

Behavior note (location mismatch): For marketplaceType in discogs, mercari, or ebay, international buyer/seller location mismatches are common and are downweighted as a primary phishing signal.

Error Handling

401 for missing/invalid auth (Bearer token or API key)
429 for rate limits
5xx for transient backend/model errors (retry with backoff)