{ "openapi": "3.0.3", "info": { "title": "ScamLens API", "version": "1.0.0", "description": "ScamLens is an AI-native anti-fraud intelligence platform. This API provides domain threat detection, crypto address analysis, content analysis, community reporting, and AI-powered investigation services.\n\n## Authentication\n\nMost read-only endpoints are public with IP-based rate limiting. Write operations and advanced features require authentication:\n\n- **Public**: No auth needed, IP rate-limited\n- **API Key**: Pass `X-API-Key: your-key` header (create keys in your account dashboard)\n- **JWT**: Pass `Authorization: Bearer ` header (from /auth/login)\n\n## Rate Limits\n\n| Tier | Limit | Window |\n|------|-------|--------|\n| Public (read) | 60 req | 1 min |\n| Public (write) | 10 req | 1 min |\n| Public (AI) | 5 req | 1 min |\n| API Key (free) | 1,000 req | 1 day |\n| API Key (pro) | 10,000 req | 1 day |\n\n## Response Format\n\nAll responses follow: `{ success: boolean, data?: T, error?: string }`", "contact": { "name": "ScamLens", "url": "https://scamlens.org" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.scamlens.org", "description": "Production" }, { "url": "https://smart-bookmarks-api.waynetaylorx.workers.dev", "description": "Production (alias)" } ], "tags": [ { "name": "Domain Intelligence", "description": "Domain threat detection and risk analysis" }, { "name": "Crypto Intelligence", "description": "Cryptocurrency address analysis" }, { "name": "Content Analysis", "description": "AI-powered text/email/message analysis" }, { "name": "AI Chat", "description": "Anti-fraud AI assistant" }, { "name": "Community", "description": "Reports, votes, comments, and feedback" }, { "name": "Threat Feed", "description": "Aggregated threat intelligence feed" }, { "name": "Investigation", "description": "Deep AI-powered domain investigation" }, { "name": "Blog", "description": "Anti-fraud educational content" }, { "name": "Authentication", "description": "User registration and login" }, { "name": "Account", "description": "API keys, webhooks, and subscription management" }, { "name": "Admin", "description": "Admin-only endpoints (requires admin auth)" } ], "paths": { "/v1/health": { "get": { "summary": "Health check", "operationId": "healthCheck", "tags": [ "Domain Intelligence" ], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "version": { "type": "string", "example": "1.0.0" } } } } } } } } }, "/v1/public/check": { "get": { "summary": "Quick domain threat check", "description": "Fast lookup against 90 threat intelligence sources. Returns threat signals, trust score, and safety verdict.", "operationId": "quickCheck", "tags": [ "Domain Intelligence" ], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Domain to check (e.g. example.com)", "example": "example.com" }, { "name": "url", "in": "query", "schema": { "type": "string" }, "description": "Full URL (optional, provides additional context)" } ], "responses": { "200": { "description": "Threat check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreatCheckResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/public/check/batch": { "post": { "summary": "Batch domain threat check", "description": "Check multiple domains in a single request (max 10).", "operationId": "batchCheck", "tags": [ "Domain Intelligence" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "example": [ "example.com", "suspicious-site.xyz" ] } } } } } }, "responses": { "200": { "description": "Batch results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ThreatCheckResult" } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/public/domain/intelligence": { "post": { "summary": "Full domain intelligence", "description": "Comprehensive domain analysis: WHOIS, DNS, SSL, threat sources, registration data, hosting info.", "operationId": "domainIntelligence", "tags": [ "Domain Intelligence" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "url": { "type": "string" } } } } } }, "responses": { "200": { "description": "Intelligence data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainIntelligenceResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/public/domain/risk-summary": { "get": { "summary": "AI risk summary", "description": "AI-generated human-readable risk assessment for a domain. Supports 12 languages.", "operationId": "riskSummary", "tags": [ "Domain Intelligence" ], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "example": "example.com" }, { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "Language code (en, zh, es, fr, de, ja, ko, pt, ru, ar, hi, vi)" } ], "responses": { "200": { "description": "AI risk summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "summary": { "type": "string" }, "riskLevel": { "type": "string", "enum": [ "safe", "low", "medium", "high", "critical" ] }, "threats": { "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/public/crypto/intelligence": { "post": { "summary": "Crypto address intelligence", "description": "Analyze a cryptocurrency address for threat signals across 6 EVM chains + Bitcoin/Solana.", "operationId": "cryptoIntelligence", "tags": [ "Crypto Intelligence" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18" }, "chain": { "type": "string", "enum": [ "1", "56", "137", "43114", "42161", "10", "btc", "sol" ], "description": "Chain ID (auto-detected if omitted)" } } } } } }, "responses": { "200": { "description": "Crypto analysis", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "address": { "type": "string" }, "chain": { "type": "string" }, "inputType": { "type": "string", "enum": [ "wallet", "token" ] }, "threatSources": { "type": "array", "items": { "type": "object" } } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/public/crypto/risk-summary": { "get": { "summary": "Crypto risk summary", "description": "AI-generated risk assessment for a crypto address.", "operationId": "cryptoRiskSummary", "tags": [ "Crypto Intelligence" ], "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "chain", "in": "query", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Risk summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "summary": { "type": "string" }, "riskLevel": { "type": "string" }, "threats": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "/v1/public/analyze": { "post": { "summary": "Analyze suspicious content", "description": "AI analysis of suspicious text messages, emails, or chat logs. Detects phishing patterns, social engineering, urgency tactics, and scam indicators.", "operationId": "analyzeContent", "tags": [ "Content Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "Text to analyze (max 5000 chars)", "example": "Dear user, your account has been compromised..." }, "mode": { "type": "string", "enum": [ "phishing", "scam", "email" ], "default": "scam", "description": "Analysis mode" } } } } } }, "responses": { "200": { "description": "Analysis result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "analysis": { "type": "object", "properties": { "detected": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "patterns": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/public/chat/start": { "post": { "summary": "Start AI chat session", "description": "Initialize an anti-fraud AI assistant session. Supports domain-specific, crypto-specific, or general anti-fraud conversations.", "operationId": "chatStart", "tags": [ "AI Chat" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "context_type": { "type": "string", "enum": [ "global", "domain", "analyze", "crypto" ], "default": "global" }, "context_domain": { "type": "string" }, "context_address": { "type": "string" }, "language": { "type": "string", "default": "en" } } } } } }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "contextType": { "type": "string" }, "language": { "type": "string" } } } } } } } } }, "/v1/public/chat/message": { "post": { "summary": "Send chat message", "description": "Send a message to the AI anti-fraud assistant and receive a response.", "operationId": "chatMessage", "tags": [ "AI Chat" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId", "message" ], "properties": { "sessionId": { "type": "string" }, "message": { "type": "string", "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "AI response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "reply": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/v1/public/report": { "post": { "summary": "Submit domain report", "description": "Report a domain as suspicious or fraudulent. Supports Cloudflare Turnstile verification.", "operationId": "submitReport", "tags": [ "Community" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain", "report_type" ], "properties": { "domain": { "type": "string" }, "report_type": { "type": "string", "enum": [ "phishing", "scam", "malware", "spam", "fake_shop", "investment_fraud", "tech_support_scam", "other" ] }, "description": { "type": "string" }, "evidence_url": { "type": "string" }, "turnstile_token": { "type": "string" }, "language": { "type": "string" } } } } } }, "responses": { "200": { "description": "Report created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" } } } } } } } } }, "/v1/public/report/{domain}": { "get": { "summary": "Get domain reports", "operationId": "getReports", "tags": [ "Community" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain reports", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "reports": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } } } } } }, "/v1/public/vote": { "post": { "summary": "Vote on domain safety", "operationId": "submitVote", "tags": [ "Community" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain", "vote" ], "properties": { "domain": { "type": "string" }, "vote": { "type": "string", "enum": [ "safe", "suspicious" ] }, "turnstile_token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Vote recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } } } }, "/v1/public/vote/{domain}": { "get": { "summary": "Get domain vote counts", "operationId": "getVotes", "tags": [ "Community" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Vote counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "votes": { "type": "object", "properties": { "safe": { "type": "integer" }, "suspicious": { "type": "integer" } } } } } } } } } } }, "/v1/public/comments/{domain}": { "get": { "summary": "Get domain comments", "operationId": "getComments", "tags": [ "Community" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domain comments", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "comments": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } } } } } }, "/v1/public/feedback": { "post": { "summary": "Submit detection feedback", "description": "Report a false positive or confirm detection accuracy. Helps improve AI detection.", "operationId": "submitFeedback", "tags": [ "Community" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" }, "accurate": { "type": "boolean", "description": "Was the detection accurate?" }, "helpful": { "type": "boolean" }, "comment": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Feedback recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } } } }, "/v1/public/reputation/leaderboard": { "get": { "summary": "Community reputation leaderboard", "operationId": "getLeaderboard", "tags": [ "Community" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 50 } } ], "responses": { "200": { "description": "Leaderboard", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string" }, "reputation_score": { "type": "number" }, "contributions": { "type": "integer" } } } } } } } } } } } }, "/v1/public/threats": { "get": { "summary": "Threat intelligence feed", "description": "Paginated list of known threat domains aggregated from multiple sources.", "operationId": "getThreatFeed", "tags": [ "Threat Feed" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "source", "in": "query", "schema": { "type": "string" }, "description": "Filter by threat source" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Filter by threat type" } ], "responses": { "200": { "description": "Threat list", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/ThreatEntry" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } } } } } }, "/v1/public/threats/stats": { "get": { "summary": "Threat statistics", "operationId": "getThreatStats", "tags": [ "Threat Feed" ], "responses": { "200": { "description": "Threat stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalDomains": { "type": "integer" }, "bySource": { "type": "object" }, "byType": { "type": "object" }, "recent": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/v1/public/threats/trends": { "get": { "summary": "Threat trends over time", "description": "Daily threat counts, top targeted brands, most abused TLDs, and lookup volume over a configurable time window.", "operationId": "getThreatTrends", "tags": [ "Threat Feed" ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 90 }, "description": "Time window in days" } ], "responses": { "200": { "description": "Threat trends", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "object", "properties": { "days": { "type": "integer" }, "since": { "type": "string" } } }, "dailyThreats": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "count": { "type": "integer" } } } }, "topTargetedBrands": { "type": "array", "items": { "type": "object", "properties": { "target_brand": { "type": "string" }, "count": { "type": "integer" } } } }, "topThreatTlds": { "type": "array", "items": { "type": "object", "properties": { "tld": { "type": "string" }, "count": { "type": "integer" } } } } } } } } } } } }, "/v1/public/crypto/threats": { "get": { "summary": "Crypto threat feed", "operationId": "getCryptoThreats", "tags": [ "Threat Feed" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "source", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Crypto threats", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } } } } } }, "/v1/investigation/checkout": { "post": { "summary": "Start deep investigation (paid)", "description": "Initiate a deep AI-powered investigation. Creates a Stripe checkout session. After payment, the investigation runs automatically with multi-AI cross-reference analysis.", "operationId": "investigationCheckout", "tags": [ "Investigation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" }, "email": { "type": "string", "format": "email" }, "locale": { "type": "string", "default": "en" } } } } } }, "responses": { "200": { "description": "Checkout session", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "sessionId": { "type": "string" }, "redirectUrl": { "type": "string", "format": "uri" } } } } } } } } }, "/v1/investigation/{id}": { "get": { "summary": "Get investigation status", "operationId": "getInvestigation", "tags": [ "Investigation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Investigation data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/InvestigationResult" } } } } } } } } }, "/v1/investigation/{id}/report": { "get": { "summary": "Get investigation report", "operationId": "getInvestigationReport", "tags": [ "Investigation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full investigation report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/v1/public/blog/posts": { "get": { "summary": "List blog posts", "operationId": "listBlogPosts", "tags": [ "Blog" ], "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Blog posts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPost" } }, "total": { "type": "integer" } } } } } } } } } } }, "/v1/public/blog/posts/{slug}": { "get": { "summary": "Get blog post by slug", "operationId": "getBlogPost", "tags": [ "Blog" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Blog post", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/BlogPost" } } } } } }, "404": { "description": "Post not found" } } } }, "/v1/public/stats": { "get": { "summary": "Platform statistics", "operationId": "getStats", "tags": [ "Domain Intelligence" ], "responses": { "200": { "description": "Platform stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalDomains": { "type": "integer" }, "totalReports": { "type": "integer" }, "totalVotes": { "type": "integer" }, "last24hReports": { "type": "integer" } } } } } } } } }, "/v1/public/recent": { "get": { "summary": "Recently checked domains", "description": "List of 10 most recently checked domains with their safety status.", "operationId": "getRecentDomains", "tags": [ "Domain Intelligence" ], "responses": { "200": { "description": "Recent domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "safe": { "type": "boolean" }, "trustScore": { "type": "number" }, "checkedAt": { "type": "string" } } } } } } } } } } } }, "/v1/public/official-domains": { "get": { "summary": "Official brand domains", "description": "List of verified official domains used for brand impersonation detection.", "operationId": "getOfficialDomains", "tags": [ "Domain Intelligence" ], "responses": { "200": { "description": "Official domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "brand_name": { "type": "string" }, "domain": { "type": "string" }, "category": { "type": "string" } } } } } } } } } } } }, "/v1/public/reddit/{domain}": { "get": { "summary": "Reddit mentions for domain", "operationId": "getRedditMentions", "tags": [ "Domain Intelligence" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reddit mentions", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "upvotes": { "type": "integer" }, "timestamp": { "type": "string" } } } } } } } } } } } }, "/v1/auth/register": { "post": { "summary": "Register new account", "operationId": "register", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 }, "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Registration successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "user": { "type": "object" }, "tokens": { "$ref": "#/components/schemas/AuthTokens" } } } } } } } } }, "/v1/auth/login": { "post": { "summary": "Login", "operationId": "login", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "user": { "type": "object" }, "tokens": { "$ref": "#/components/schemas/AuthTokens" } } } } } }, "401": { "description": "Invalid credentials" } } } }, "/v1/auth/api-keys": { "get": { "summary": "List API keys", "operationId": "listApiKeys", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "API keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tier": { "type": "string" }, "createdAt": { "type": "string" }, "lastUsed": { "type": "string", "nullable": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "summary": "Create API key", "operationId": "createApiKey", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "tier": { "type": "string", "enum": [ "free", "pro", "enterprise" ], "default": "free" } } } } } }, "responses": { "200": { "description": "API key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string", "description": "Only shown once at creation time" }, "name": { "type": "string" }, "tier": { "type": "string" } } } } } } } } } } }, "/v1/auth/webhooks": { "get": { "summary": "List webhooks", "operationId": "listWebhooks", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } } } } } } } } } } }, "post": { "summary": "Create webhook", "description": "Subscribe to events: threat_detected, report_verified, investigation_completed", "operationId": "createWebhook", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "threat_detected", "report_verified", "investigation_completed" ] } } } } } } }, "responses": { "200": { "description": "Webhook created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/v1/auth/account": { "delete": { "summary": "Delete account (GDPR)", "description": "Permanently delete the authenticated user account and all associated data. This action is irreversible.", "operationId": "deleteAccount", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Account deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/export-data": { "get": { "summary": "Export user data (GDPR)", "description": "Export all data associated with the authenticated user account in JSON format. Supports GDPR data portability requirements.", "operationId": "exportData", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "User data export", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "Complete user data including profile, reports, votes, feedback, API keys, and usage history" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/credits/balance": { "get": { "summary": "Get credit balance", "description": "Get the current credit balance and usage stats for the authenticated user.", "operationId": "getCreditBalance", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Credit balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "balance": { "type": "number" }, "plan": { "type": "string" }, "monthlyQuota": { "type": "object" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/credits/history": { "get": { "summary": "Get credit transaction history", "operationId": "getCreditHistory", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Credit history", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/public/credits/pricing": { "get": { "summary": "Get credit pricing", "description": "Get available credit packs and pricing information.", "operationId": "getCreditPricing", "tags": [ "Account" ], "responses": { "200": { "description": "Credit pricing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/v1/public/enterprise/contact": { "post": { "summary": "Enterprise contact form", "description": "Submit an enterprise inquiry or partnership request.", "operationId": "enterpriseContact", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "company" ], "properties": { "email": { "type": "string", "format": "email" }, "company": { "type": "string" }, "name": { "type": "string" }, "message": { "type": "string" }, "use_case": { "type": "string" } } } } } }, "responses": { "200": { "description": "Inquiry submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } } } }, "/v1/public/crypto/trace/pricing": { "get": { "summary": "Get crypto trace pricing", "description": "Get pricing tiers for cryptocurrency fund tracing ($99/$199/$399).", "operationId": "cryptoTracePricing", "tags": [ "Crypto Intelligence" ], "responses": { "200": { "description": "Trace pricing", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/v1/public/crypto/trace/checkout": { "post": { "summary": "Start crypto trace (paid)", "description": "Create a Stripe checkout session for cryptocurrency fund tracing. Supports 18 chains.", "operationId": "cryptoTraceCheckout", "tags": [ "Crypto Intelligence" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "chain": { "type": "string" }, "tier": { "type": "string", "enum": [ "standard", "advanced", "forensic" ] }, "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Checkout session", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "sessionId": { "type": "string" }, "redirectUrl": { "type": "string", "format": "uri" } } } } } } } } }, "/v1/public/crypto/trace/{traceId}": { "get": { "summary": "Get crypto trace status", "operationId": "getCryptoTrace", "tags": [ "Crypto Intelligence" ], "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trace data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } }, "404": { "description": "Trace not found" } } } }, "/v1/public/wallet/profile": { "post": { "summary": "Wallet profile analysis", "description": "Full behavioral analysis of a blockchain wallet: classification, activity patterns, token holdings, DeFi interactions.", "operationId": "walletProfile", "tags": [ "Crypto Intelligence" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "chain": { "type": "string" } } } } } }, "responses": { "200": { "description": "Wallet profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/v1/public/wallet/risk": { "post": { "summary": "Wallet risk assessment", "description": "Enhanced risk model with 4-level factor hierarchy (A-D), transitive risk propagation, and behavioral anomaly detection.", "operationId": "walletRisk", "tags": [ "Crypto Intelligence" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "chain": { "type": "string" } } } } } }, "responses": { "200": { "description": "Risk assessment", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/v1/public/contract/analyze": { "post": { "summary": "Smart contract analysis", "description": "Analyze a smart contract for known scam patterns: rug pull, honeypot, proxy abuse, reentrancy.", "operationId": "contractAnalyze", "tags": [ "Crypto Intelligence" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "chain": { "type": "string" } } } } } }, "responses": { "200": { "description": "Contract analysis", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } } } }, "/v1/public/scam-feed": { "get": { "summary": "Scam address feed", "description": "Real-time feed of newly discovered scam and high-risk blockchain addresses. Public tier with pagination.", "operationId": "getScamFeed", "tags": [ "Threat Feed" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "chain", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scam address feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } } } } } }, "/v1/admin/review-queue": { "get": { "summary": "Get AI review queue", "description": "Paginated list of AI-generated high-risk verdicts pending admin review. Requires admin authentication.", "operationId": "getReviewQueue", "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approve", "reject", "override" ], "default": "pending" }, "description": "Filter by review status" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Review queue", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewQueueItem" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/admin/review-queue/{id}/review": { "post": { "summary": "Review AI verdict", "description": "Approve, reject, or override a high-risk AI verdict. Requires admin authentication.", "operationId": "reviewVerdict", "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "approve", "reject", "override" ], "description": "Review action" }, "note": { "type": "string", "description": "Optional reviewer note" } } } } } }, "responses": { "200": { "description": "Verdict reviewed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid action" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Review item not found or already reviewed" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "ThreatCheckResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "domain": { "type": "string" }, "safe": { "type": "boolean" }, "trustScore": { "type": "number", "minimum": 0, "maximum": 100 }, "threats": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "safe": { "type": "boolean" }, "threats": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "number" }, "details": { "type": "object" } } } } } }, "ThreatCheckResult": { "type": "object", "properties": { "domain": { "type": "string" }, "safe": { "type": "boolean" }, "trustScore": { "type": "number" }, "threats": { "type": "array", "items": { "type": "string" } } } }, "DomainIntelligenceResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "domain": { "type": "string" }, "registrar": { "type": "string", "nullable": true }, "createdDate": { "type": "string", "nullable": true }, "expiresDate": { "type": "string", "nullable": true }, "threatSources": { "type": "array", "items": { "type": "object" } }, "dnsRecords": { "type": "object" }, "sslInfo": { "type": "object" } } } } }, "ThreatEntry": { "type": "object", "properties": { "domain": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "threatType": { "type": "string" }, "targetBrand": { "type": "string", "nullable": true }, "totalUrls": { "type": "integer" }, "firstSeen": { "type": "string", "format": "date-time" }, "lastSeen": { "type": "string", "format": "date-time" } } }, "InvestigationResult": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "tier": { "type": "string", "enum": [ "advanced", "deep" ] }, "riskLevel": { "type": "string", "enum": [ "safe", "low", "medium", "high", "critical" ] }, "executiveSummary": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "BlogPost": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "content": { "type": "string" }, "category": { "type": "string" }, "readingTime": { "type": "integer" }, "featured": { "type": "boolean" }, "publishedAt": { "type": "string", "format": "date-time" } } }, "AuthTokens": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "integer", "description": "Token TTL in seconds" } } }, "ReviewQueueItem": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "trust_score": { "type": "integer", "description": "Trust score at time of verdict (0-100)" }, "ai_verdict": { "type": "string", "enum": [ "safe", "medium", "high" ] }, "ai_summary": { "type": "string", "nullable": true }, "evidence_tags": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "approve", "reject", "override" ] }, "reviewer_note": { "type": "string", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "responses": { "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Rate limit exceeded. Try again later." } } } } } }, "Unauthorized": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" } } } } } } } } }