api_docs.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=5.0, user-scalable=yes">
<title>API Documentation | GFIN — Global Fraud Intelligence Network</title>
<meta name="description" content="GFIN API documentation — public and law enforcement API endpoints for fraud reporting, scam checking, and analytics.">
<style>
*{margin:0;padding:0;box-sizing:border-box}
body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#f8fafc;color:#1e293b;line-height:1.6}
.topbar{background:#0a0e1a;padding:12px 20px;display:flex;align-items:center;justify-content:space-between}
.topbar a{color:#64b5f6;text-decoration:none;font-size:14px}
.topbar .logo{color:#fff;font-weight:700;font-size:18px}
.header{background:#fff;border-bottom:1px solid #e2e8f0;padding:16px 20px}
.header h1{font-size:22px;color:#0f172a}
.header p{font-size:14px;color:#64748b}
.container{max-width:900px;margin:0 auto;padding:30px 20px}
.section{background:#fff;border-radius:12px;padding:24px;margin-bottom:16px;border:1px solid #e2e8f0}
.section h2{color:#0f172a;font-size:18px;margin-bottom:12px}
.endpoint{background:#0a0e1a;border-radius:8px;padding:14px;margin-bottom:10px;font-family:'Courier New',monospace}
.endpoint .method{display:inline-block;padding:3px 10px;border-radius:4px;font-size:12px;font-weight:700;margin-right:8px}
.method-get{background:#1b5e20;color:#a5d6a7}
.method-post{background:#1565c0;color:#90caf9}
.method-del{background:#c62828;color:#ef9a9a}
.endpoint .path{color:#fff;font-size:14px}
.endpoint .desc{color:#90a4ae;font-size:13px;margin-top:4px}
.tag{display:inline-block;background:#e3f2fd;color:#1565c0;padding:2px 8px;border-radius:4px;font-size:11px;font-weight:600;margin-left:8px}
.footer{text;background:#0a0e1a;color:#64748b;text-align:center;padding:24px;font-size:14px}
.footer a{color:#64b5f6;text-decoration:none;margin:0 8px}
@media(max-width:768px){.container{padding:16px}.section{padding:16px}body{font-size:15px}}
</style>
</head>
<body>
<div class="topbar">
<span class="logo">🛡️ GFIN</span>
<a href="/"><span style="color:#64748b">← Back to Home</span></a>
</div>
<div class="header">
<h1>API Documentation</h1>
<p>Public and law enforcement API endpoints for GFIN</p>
</div>
<div class="container">

<div class="section">
<h2>Overview</h2>
<p style="color:#475569;font-size:15px">The GFIN API provides access to fraud reporting, scam checking, analytics, and law enforcement tools. Public endpoints require no authentication. Police endpoints require JWT authentication.</p>
<p style="color:#475569;font-size:15px;margin-top:8px">Base URL: <code style="background:#e2e8f0;padding:2px 8px;border-radius:4px;font-size:14px">https://gfin-system.com</code></p>
</div>

<div class="section">
<h2>🔒 Victim Portal API <span class="tag">No Auth</span></h2>
<div class="endpoint"><span class="method method-post'>POST</span><span class="path'>/api/victim/register</span><div class="desc'>Register a new victim account (name, email, password, country, phone)</div></div>
<div class="endpoint"><span class="method method-post'>POST</span><span class="path'>/api/victim/login</span><div class="desc'>Login with email + password, returns JWT token</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/victim/me</span><div class="desc'>Get current victim profile (requires auth token)</div></div>
<div class="endpoint"><span class="method method-post'>POST</span><span class="path'>/api/victim/complaint</span><div class="desc'>File a new fraud complaint with evidence files. Triggers automated investigation pipeline</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/victim/complaints</span><div class="desc'>List all complaints filed by the authenticated victim</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/victim/complaint/{ref}</span><div class="desc'>Get details of a specific complaint by reference number</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/victim/track/{ref}</span><div class='desc'>Track complaint status by reference number (no auth required)</div></div>
</div>

<div class="section">
<h2>🔍 Scam Database API <span class="tag">Public</span></h2>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/scam-sites/check/{domain}</span><div class="desc">Check if a domain is in the scam database</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/scam-sites/list</span><div class="desc">List known scam websites (paginated)</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/scam-sites/search</span><div class="desc">Search scam database by keyword</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/scam-sites/stats</span><div class="desc">Get scam database statistics (counts, risk levels, losses)</div></div>
</div>

<div class="section">
<h2>📊 Analytics API <span class="tag">Public</span></h2>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/analytics/overview</span><div class="desc">Total complaints, active cases, losses, wallets traced</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/analytics/scam-types</span><div class="desc">Breakdown by scam category (15 types)</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/analytics/risk-levels</span><div class="desc">Distribution by risk level (critical, high, medium, low)</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/analytics/countries</span><div class="desc">Cases by country</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/analytics/timeline</span><div class="desc">Complaints over time</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/analytics/financial-loss</span><div class="desc">Financial loss breakdown</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/analytics/crypto</span><div class="desc">Cryptocurrency tracing statistics</div></div>
</div>

<div class="section">
<h2>🛡️ Scam Detection API <span class="tag">Public</span></h2>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/scam-detect</span><div class="desc">Analyze text for scam indicators using deterministic v3.0 engine (300+ patterns, 15 categories)</div></div>
</div>

<div class="section">
<h2>🌍 Country Routing API <span class="tag">Public</span></h2>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/countries</span><div class="desc">List all 189 supported countries with cybercrime contacts</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/countries/{country_code}</span><div class="desc">Get routing details for a specific country (contacts, Interpol, Europol)</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/countries/search/{name}</span><div class="desc">Search countries by name</div></div>
</div>

<div class="section">
<h2>🔍 Intelligence Playbook API <span class="tag">Public</span></h2>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/playbook/investigate</span><div class="desc">Run full intelligence investigation from trigger to physical address</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/playbook/entities</span><div class="desc">List supported entity types for investigation</div></div>
</div>

<div class="section">
<h2>📢 Awareness & Telegram API <span class="tag">Public</span></h2>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/awareness/stats</span><div class="desc">Awareness broadcast statistics</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/awareness/types</span><div class="desc">List 12 scam awareness types</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/telegram/status</span><div class="desc">Telegram bot status and subscriber count</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/telegram/subscribers</span><div class="desc">Get Telegram subscriber count (anonymized)</div></div>
</div>

<div class="section">
<h2>👮 Police API <span class="tag">Auth Required</span></h2>
<div class="endpoint"><span class="method method-post'>POST</span><span class="path'>/api/police/login</span><div class="desc">Police officer login (returns JWT, 7-day expiry)</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/police/me</span><div class="desc">Get current officer profile</div></div>
<div class="endpoint"><span class="method method-post'>POST</span><span class="path'>/api/police/register</span><div class="desc">Register new officer (admin only — first registration auto-admin)</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/police/officers</span><div class="desc">List all officers (admin only)</div></div>
<div class="endpoint"><span class="method method-post'>POST</span><span class="path'>/api/awareness/broadcast</span><div class="desc">Broadcast awareness message to all Telegram subscribers (police only)</div></div>
<div class="endpoint"><span class="method method-post'>POST</span><span class="path'>/api/awareness/broadcast/{scam_type}</span><div class="desc">Broadcast specific scam type awareness (police only)</div></div>
</div>

<div class="section">
<h2>📋 Reports API <span class="tag">Auth Required</span></h2>
<div class="endpoint"><span class="method method-post'>POST</span><span class="path'>/api/reports/generate</span><div class="desc">Generate investigation report for a case</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/reports/download/{filename}</span><div class="desc">Download generated report file</div></div>
</div>

<div class="section">
<h2>🔐 Evidence API <span class="tag">Auth Required</span></h2>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/api/evidence-secure/{case_id}</span><div class="desc">Secure evidence retrieval with chain of custody</div></div>
</div>

<div class="section">
<h2>System</h2>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/health</span><div class="desc">Health check — returns server status and database connection state</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/robots.txt</span><div class="desc">SEO robots file</div></div>
<div class="endpoint"><span class="method method-get'>GET</span><span class="path'>/sitemap.xml</span><div class="desc">XML sitemap for search engines</div></div>
</div>

<div class="section">
<h2>Rate Limits</h2>
<ul style="padding-left:20px;color:#475569;font-size:15px">
<li>General API: 100 requests/minute</li>
<li>Authentication endpoints: 10 requests/minute</li>
<li>Police endpoints: 60 requests/minute per IP</li>
<li>Complaint filing: 5 per hour per victim</li>
</ul>
</div>

</div>
<div class="footer">
<a href="/">Home</a><a href="/victim">Report a Scam</a><a href="/scam-sites">Scam Database</a><a href="/police/login">Police Login</a><br><br>
© 2026 Global Fraud Intelligence Network
</div>
<script src="/gfin-i18n.js"></script>
</body>
</html>