URLScans API Documentation
Integrate URLScans's phishing detection and brand protection capabilities into your applications, workflows, and security tools.
Real-time Detection
Get instant phishing detection results with sub-second response times. Perfect for real-time security checks.
Enterprise Grade
Built for scale with rate limiting, authentication, and comprehensive error handling. Production-ready infrastructure.
RESTful API
Simple, intuitive REST API with JSON responses. Easy integration with any programming language or framework.
Comprehensive Docs
Detailed documentation with code examples, authentication guides, and best practices for integration.
Endpoints — API key required
Send your key in the X-API-Key header.
/api/scan?url=example.comScan a URL, domain, or IP for phishing/malware threats. Returns a verdict, risk score, reasons, WHOIS, redirect chain, email-auth (SPF/DMARC/DKIM) and content categories. Counts against your monthly quota.
/api/whois?domain=example.com · ?ip=8.8.8.8WHOIS/RDAP data (registrar, abuse contacts, hosting) for a domain or IP. Rate-limited per key; does not use scan quota.
/api/categoriesJSON body: { "url": "example.com" }Content/business category signals for a URL (Cloudflare Radar). Rate-limited per key; does not use scan quota.
/api/db/lookups?limit=20List recent scan records (newest first, max 100). Rate-limited per key.
Endpoints — no key required
Open endpoints for public data and threat-intel feeds.
/api/phishing-checkJSON body: { "url": "example.com" }Lightweight phishing heuristics check for a URL (page content + patterns).
/api/recent-scans?limit=20Recent public scan results for the live feed (safe fields only).
/api/public-statsAggregate scan statistics (totals by verdict).
/api/feed/export?days=30Threat-intel feed: plain-text list of recent malicious/suspicious URLs and domains.
Quick Start Example
// Scan a URL, domain, or IP (include your API key)
const response = await fetch(
'https://urlscans.com/api/scan?url=' + encodeURIComponent('example.com'),
{
headers: {
'X-API-Key': 'YOUR_API_KEY',
},
}
);
const result = await response.json();
console.log(result.verdict.verdict); // 'safe' | 'suspicious' | 'malicious'
console.log(result.verdict.score); // risk score
console.log(result.verdict.categories); // Threat categories
console.log(result.urlScansAnalysis.emailAuth); // SPF / DMARC / DKIM (when checked)
console.log(result.urlScansAnalysis.cloudflareCategories); // Cloudflare Radar categoriesQuotas, Rate Limits & Errors
Quota
Free keys include 1,000 scans/month. Only /api/scan consumes quota. Check your usage anytime at GET /api/auth/me (returns usageThisMonth and quotaMonthly). Exceeding it returns 429 Quota exceeded.
Rate limits
The other key-protected endpoints (whois, categories, lookups) are rate-limited per key (~120 req/min) and don't use scan quota. Pass ?nocache=1 on /api/scan to bypass the cache and force a fresh scan.
Response codes
- 200 — success
- 400 — invalid input (bad URL, domain, or IP)
- 401 — missing or invalid API key
- 429 — quota exceeded or rate-limited (see
Retry-After) - 503 — upstream check temporarily unavailable
Authentication
Key-protected endpoints require a valid X-API-Key header. Scripts, servers, and integrations must set the header themselves; the public site sends it from the browser automatically. Your registered key works on every key-protected endpoint listed above. Register for a free API key (1,000 scans/month).
Ready to Integrate?
Start using URLScans API today or contact us for enterprise integration support.