{"openapi":"3.1.0","info":{"title":"ScamDetector.eu API","version":"1.0.0","description":"Four-pillar website trust scanning (weirdness, scams, data-mining, misinformation) and scam-intelligence lookups.","contact":{"url":"https://scamdetector.eu/docs/api"}},"servers":[{"url":"https://scanner.scamdetector.eu"}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer sd_live_…` (or `X-API-Key`). API keys come with the Pro and Business plans (https://scamdetector.eu/pricing). The free tier is the website scamdetector.eu; calls without a key are refused unless they come from it."}},"schemas":{"ScanReportFull":{"type":"object","properties":{"scanId":{"type":"string","format":"uuid"},"schemaVersion":{"type":"number","enum":[1]},"engineVersion":{"type":"string"},"status":{"type":"string","enum":["completed","partial","failed"]},"startedAt":{"type":"string"},"completedAt":{"type":"string"},"durationMs":{"type":"number"},"target":{"type":"object","properties":{"canonicalUrl":{"type":"string"},"hostname":{"type":"string"},"hostnameUnicode":{"type":"string"},"registrableDomain":{"type":["string","null"]}},"required":["canonicalUrl","hostname","hostnameUnicode","registrableDomain"],"additionalProperties":{}},"scores":{"$ref":"#/components/schemas/ScanScores"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"facts":{"type":"object","additionalProperties":{}},"evidence":{"type":"object","additionalProperties":{}},"analyzers":{"type":"array","items":{"type":"object","additionalProperties":{}}},"stages":{"type":"array","items":{"type":"object","additionalProperties":{}}},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"cached":{"type":"boolean"}},"required":["scanId","schemaVersion","engineVersion","status","startedAt","completedAt","durationMs","target","scores","findings","facts","evidence","analyzers","stages","errors"]},"ScanScores":{"type":"object","properties":{"trustScore":{"type":"integer","minimum":0,"maximum":100},"verdict":{"type":"string","enum":["trusted","low_risk","suspicious","high_risk","critical_scam"]},"verdictLabel":{"type":"string"},"confidence":{"type":"number"},"pillars":{"type":"object","properties":{"weirdness":{"type":"object","properties":{"pillar":{"type":"string","enum":["weirdness","scams","datamining","misinformation"]},"score":{"type":"integer","minimum":0,"maximum":100},"status":{"type":"string","enum":["ok","partial","not_assessed"]},"findings":{"type":"integer"},"deductions":{"type":"number"},"bonus":{"type":"number"},"label":{"type":"string"}},"required":["pillar","score","status","findings","deductions","bonus","label"]},"scams":{"type":"object","properties":{"pillar":{"type":"string","enum":["weirdness","scams","datamining","misinformation"]},"score":{"type":"integer","minimum":0,"maximum":100},"status":{"type":"string","enum":["ok","partial","not_assessed"]},"findings":{"type":"integer"},"deductions":{"type":"number"},"bonus":{"type":"number"},"label":{"type":"string"}},"required":["pillar","score","status","findings","deductions","bonus","label"]},"datamining":{"type":"object","properties":{"pillar":{"type":"string","enum":["weirdness","scams","datamining","misinformation"]},"score":{"type":"integer","minimum":0,"maximum":100},"status":{"type":"string","enum":["ok","partial","not_assessed"]},"findings":{"type":"integer"},"deductions":{"type":"number"},"bonus":{"type":"number"},"label":{"type":"string"}},"required":["pillar","score","status","findings","deductions","bonus","label"]},"misinformation":{"type":"object","properties":{"pillar":{"type":"string","enum":["weirdness","scams","datamining","misinformation"]},"score":{"type":"integer","minimum":0,"maximum":100},"status":{"type":"string","enum":["ok","partial","not_assessed"]},"findings":{"type":"integer"},"deductions":{"type":"number"},"bonus":{"type":"number"},"label":{"type":"string"}},"required":["pillar","score","status","findings","deductions","bonus","label"]}},"required":["weirdness","scams","datamining","misinformation"]},"knockouts":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"cap":{"type":"number"},"description":{"type":"string"},"findingIds":{"type":"array","items":{"type":"string"}}},"required":["rule","cap","description","findingIds"]}},"capsApplied":{"type":"array","items":{"type":"string"}},"floorsApplied":{"type":"array","items":{"type":"string"}},"topReasons":{"type":"array","items":{"type":"object","properties":{"findingId":{"type":"string"},"title":{"type":"string"},"pillar":{"type":"string"},"severity":{"type":"string"},"impact":{"type":"number"}},"required":["findingId","title","pillar","severity","impact"]}},"trustSignals":{"type":"array","items":{"type":"object","properties":{"findingId":{"type":"string"},"title":{"type":"string"},"pillar":{"type":"string"},"severity":{"type":"string"},"impact":{"type":"number"}},"required":["findingId","title","pillar","severity","impact"]}},"scamCategories":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"weight":{"type":"number"}},"required":["slug","weight"]}}},"required":["trustScore","verdict","verdictLabel","confidence","pillars","knockouts","capsApplied","floorsApplied","topReasons","trustSignals","scamCategories"]},"Finding":{"type":"object","properties":{"id":{"type":"string","example":"WEIRD_DOMAIN_AGE_UNDER_7D"},"pillar":{"type":"string","enum":["weirdness","scams","datamining","misinformation","vulnerability"]},"analyzer":{"type":"string"},"severity":{"type":"string","enum":["info","low","medium","high","critical"]},"scoreImpact":{"type":"number"},"confidence":{"type":"number"},"title":{"type":"string"},"description":{"type":"string"},"remediationOrTip":{"type":"string"},"evidence":{"type":"object","additionalProperties":{}},"scamCategories":{"type":"array","items":{"type":"string"}}},"required":["id","pillar","analyzer","severity","scoreImpact","confidence","title","description","evidence"]},"ScanResult":{"type":"object","properties":{"scanId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","completed","failed"]},"report":{"$ref":"#/components/schemas/ScanReport"},"cached":{"type":"boolean"},"ageSeconds":{"type":"number"}},"required":["scanId","status"]},"ScanReport":{"type":"object","properties":{"scanId":{"type":"string","format":"uuid"},"schemaVersion":{"type":"number","enum":[1]},"engineVersion":{"type":"string"},"status":{"type":"string","enum":["completed","partial","failed"]},"startedAt":{"type":"string"},"completedAt":{"type":"string"},"durationMs":{"type":"number"},"target":{"type":"object","properties":{"canonicalUrl":{"type":"string"},"hostname":{"type":"string"},"hostnameUnicode":{"type":"string"},"registrableDomain":{"type":["string","null"]}},"required":["canonicalUrl","hostname","hostnameUnicode","registrableDomain"],"additionalProperties":{}},"scores":{"$ref":"#/components/schemas/ScanScores"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"facts":{"type":"object","additionalProperties":{}},"evidence":{"type":"object","additionalProperties":{}},"analyzers":{"type":"array","items":{"type":"object","additionalProperties":{}}},"stages":{"type":"array","items":{"type":"object","additionalProperties":{}}},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"cached":{"type":"boolean"}},"required":["scanId","schemaVersion","engineVersion","status","startedAt","completedAt","durationMs","target","scores","findings","facts","evidence","analyzers","stages","errors"]},"ScanAccepted":{"type":"object","properties":{"scanId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","completed","failed"]},"eventsUrl":{"type":"string"},"resultUrl":{"type":"string"},"cached":{"type":"object","properties":{"scanId":{"type":"string"},"ageSeconds":{"type":"number"},"stale":{"type":"boolean"}},"required":["scanId","ageSeconds","stale"]}},"required":["scanId","status","eventsUrl","resultUrl"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"INVALID_URL"},"message":{"type":"string"}},"required":["code","message"]},"requestId":{"type":"string"}},"required":["error","requestId"]},"ScanRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":4096,"example":"https://example.com","description":"URL, bare domain, or defanged indicator (hxxps://example[.]com)."},"mode":{"type":"string","enum":["fast","deep"],"default":"deep","description":"`fast` skips the headless browser stage."},"forceRescan":{"type":"boolean","default":false,"description":"Ignore a cached report (subject to a rescan cooldown for anonymous callers)."},"async":{"type":"boolean","default":false,"description":"Return 202 immediately with a scan id instead of waiting for the report."},"webhookUrl":{"type":"string","format":"uri","description":"HTTPS URL that receives a signed `scan.completed` POST (API keys only)."}},"required":["url"]},"DomainIntelligence":{"type":"object","properties":{"hostname":{"type":"string"},"trustScore":{"type":["number","null"]},"verdict":{"type":["string","null"]},"pillars":{"type":"object","additionalProperties":{"type":["number","null"]}},"lastScannedAt":{"type":["string","null"]},"scanCount":{"type":"number"},"latestReport":{"allOf":[{"$ref":"#/components/schemas/ScanReport"},{"type":["object","null"]}]},"scoreSeries":{"type":"array","items":{"type":"object","properties":{"scanId":{"type":"string"},"at":{"type":"string"},"score":{"type":"number"},"verdict":{"type":"string"}},"required":["scanId","at","score","verdict"]}},"history":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string"},"type":{"type":"string"},"summary":{"type":"string"}},"required":["at","type","summary"]}},"vulnerabilities":{"type":"array","items":{"type":"object","additionalProperties":{}}},"trackers":{"type":"array","items":{"type":"object","additionalProperties":{}}},"relatedDomains":{"type":"array","items":{"type":"object","additionalProperties":{}}},"communityReports":{"type":"object","properties":{"pending":{"type":"number"},"corroborated":{"type":"number"},"rejected":{"type":"number"}},"required":["pending","corroborated","rejected"]}},"required":["hostname","trustScore","verdict","pillars","lastScannedAt","scanCount","latestReport","scoreSeries","history","vulnerabilities","trackers","relatedDomains","communityReports"]},"BatchScanRequest":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string","minLength":1,"maxLength":4096},"minItems":1,"maxItems":100},"mode":{"type":"string","enum":["fast","deep"],"default":"fast"},"webhookUrl":{"type":"string","format":"uri"}},"required":["urls"]},"CommunityReportCreated":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","corroborated"]},"duplicate":{"type":"boolean"},"iocs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}},"required":["type","value"]}},"rejectedIocs":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"reason":{"type":"string"}},"required":["value","reason"]}}},"required":["id","status","duplicate","iocs","rejectedIocs"]},"CommunityReportRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"category":{"type":"string","enum":["phishing","identity-theft","email","phone","text-message","romance","crypto","facebook","instagram","zelle-venmo","amazon","cash-app","job","linkedin","financial","real-estate","credit-card","whatsapp","apple-google","marketplace","social-security-medicare","discord-telegram","insurance","travel"]},"description":{"type":"string","maxLength":5000,"default":""},"evidenceUrls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":10,"default":[]},"financialLoss":{"type":"boolean","default":false},"lossAmount":{"type":"number","minimum":0,"maximum":1000000000000},"lossCurrency":{"type":"string","minLength":3,"maxLength":3},"cryptoWalletOrIban":{"type":"string","maxLength":200},"turnstileToken":{"type":"string","maxLength":4096}},"required":["url","category"]}},"parameters":{}},"paths":{"/api/v1/scan":{"post":{"summary":"Scan a URL","description":"Runs the four-pillar scan. By default waits up to 60 s and returns the report; with `async: true` (or when the scan takes longer) returns 202 and a scan id. Send `Accept: text/event-stream` to stream progress events instead.","security":[{"ApiKey":[]},{}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"}}}},"responses":{"200":{"description":"Completed report (or cached report)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanResult"}}}},"202":{"description":"Scan accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanAccepted"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/scan/{scanId}":{"get":{"summary":"Get scan status and report","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"scanId","in":"path"}],"responses":{"200":{"description":"Scan status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanResult"}}}},"404":{"description":"Unknown scan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/scan/{scanId}/events":{"get":{"summary":"Stream scan progress (Server-Sent Events)","description":"Events: `scan_queued`, `scan_started`, `stage_started`, `analyzer_completed`, `finding_detected`, `stage_completed`, `scan_complete`, `scan_error`. Supports `Last-Event-ID` for resumption.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"scanId","in":"path"}],"responses":{"200":{"description":"text/event-stream"}}}},"/api/v1/scans":{"get":{"summary":"Your scans","description":"Scans made with your organisation's API keys, newest first. Scans made with an API key are private: they never appear on scamdetector.eu or to other customers.","parameters":[{"schema":{"type":"string","description":"Hostname contains"},"required":false,"description":"Hostname contains","name":"q","in":"query"},{"schema":{"type":"string","enum":["trusted","low_risk","suspicious","high_risk","critical_scam"]},"required":false,"name":"verdict","in":"query"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"pageSize","in":"query"}],"responses":{"200":{"description":"Your scans","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"scanId":{"type":"string"},"hostname":{"type":"string"},"url":{"type":"string"},"mode":{"type":"string"},"trustScore":{"type":["number","null"]},"verdict":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["scanId","hostname","url","mode","trustScore","verdict","createdAt"]}},"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"}},"required":["items","page","pageSize","total"]}}}}}}},"/api/v1/domain/{domain}":{"get":{"summary":"Your latest scan of a domain","description":"Your organisation's latest report and score history for a domain, from scans made with your API keys only. Never starts a scan; 404 when you have not scanned it.","parameters":[{"schema":{"type":"string","example":"example.com"},"required":true,"name":"domain","in":"path"}],"responses":{"200":{"description":"Domain intelligence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainIntelligence"}}}},"404":{"description":"Not scanned yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/batch-scan":{"post":{"summary":"Scan up to 100 URLs asynchronously (Pro and above)","description":"Returns scan ids immediately; a signed `batch.completed` webhook is sent when every scan has finished.","security":[{"ApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScanRequest"}}}},"responses":{"202":{"description":"Batch accepted","content":{"application/json":{"schema":{"type":"object","properties":{"batchId":{"type":"string","format":"uuid"},"scans":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"scanId":{"type":"string","format":"uuid"},"error":{"type":"string"}},"required":["url"]}}},"required":["batchId","scans"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/reports":{"post":{"summary":"Submit a community scam report","description":"Reports are stored as pending and never change a verdict on their own. Wallet addresses, IBANs, phone numbers and e-mail addresses are extracted as indicators.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityReportRequest"}}}},"responses":{"201":{"description":"Stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityReportCreated"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/feeds/scams":{"get":{"summary":"Recently verified scam detections","responses":{"200":{"description":"Feed items","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["items"]}}}}}}},"/api/v1/badge/{domain}.svg":{"get":{"summary":"Trust badge for verified site owners","description":"Renders the stored score only when the domain's DNS TXT ownership record is present and the score is at least 85; otherwise a non-verified badge.","parameters":[{"schema":{"type":"string"},"required":true,"name":"domain","in":"path"}],"responses":{"200":{"description":"image/svg+xml"}}}}},"webhooks":{}}