Overview
The Domain Analysis API performs deep reconnaissance on any domain, providing:
- DNS record resolution (A, AAAA, MX, TXT, NS, CNAME, SOA)
- WHOIS registration information
- SSL/TLS certificate details
- Security header analysis
- Technology stack detection
- HTTP response information
- Subdomain enumeration (optional)
- Reputation and threat intelligence
This endpoint uses Server-Sent Events (SSE) streaming to provide real-time progress updates as each analysis step completes.
Endpoint
Request
Content-Type: application/json
Body Parameters
Domain name to analyze. Protocol, www prefix, paths, and ports are automatically removed.Examples:
"example.com""https://www.example.com/path" → cleaned to "example.com""subdomain.example.com:8080" → cleaned to "subdomain.example.com"
Analysis options
options.includeSubdomains
Enable subdomain enumeration (adds ~20-30 seconds to analysis)Default: false
Request Example
curl -X POST http://localhost:3000/api/domain/analyze \
-H "Content-Type: application/json" \
-d '{
"domain": "example.com",
"options": {
"includeSubdomains": true
}
}'
Response
The endpoint returns a Server-Sent Events (SSE) stream with Content-Type: text/event-stream.
Event Types
Progress update during analysis
Current analysis step (e.g., “Resolving DNS records”)
Number of completed steps
Partial result from a completed step
Partial analysis results (DNS, WHOIS, SSL, etc.)
Final complete analysis result
See complete result structure below
Complete Result Structure
ISO 8601 timestamp of analysis
Whether the domain is available for registration
DNS Records
All DNS records
A records (IPv4 addresses)
AAAA records (IPv6 addresses)
MX records (mail servers) with priority
TXT records (SPF, DKIM, verification, etc.)
SOA records (zone authority)
DnsRecord contains:{
type: 'A' | 'AAAA' | 'MX' | 'TXT' | 'NS' | 'CNAME' | 'SOA',
value: string,
ttl?: number,
priority?: number // MX records only
}
Domain registration informationShow WhoisData properties
Authoritative nameservers
SSL Certificate
SSL/TLS certificate detailsShow SslCertificate properties
Certificate issuer (e.g., “Let’s Encrypt”)
Certificate subject (domain)
Certificate valid from date
Certificate expiration date
Days until certificate expires
Whether certificate is expired
Whether certificate is currently valid
Certificate serial number
Subject alternative names (other domains covered)
Security header analysisShow SecurityHeaders properties
Strict-Transport-Security header present
X-Frame-Options header present
X-Content-Type-Options header present
Content-Security-Policy header present
X-XSS-Protection header present
Referrer-Policy header present
Permissions-Policy header present
Overall security score (0-100)
Technology Detection
Detected technologiesEach entry contains:{
name: string, // e.g., "WordPress", "Cloudflare"
category: string, // e.g., "CMS", "CDN", "Web Server"
confidence: number, // 0-100
version?: string, // e.g., "6.4.2"
icon?: string // Icon URL
}
Redirect target URL if applicable
X-Powered-By header value
Response time in milliseconds
Subdomains (if enabled)
Discovered subdomainsEach entry contains:{
name: string, // Subdomain (e.g., "api.example.com")
ip?: string, // IP address
source: string // Discovery source
}
Reputation
Threat intelligence and reputation dataShow reputation properties
Overall risk score (0-100)
Response Example
{
"type": "progress",
"data": {
"step": "Fetching WHOIS data",
"total": 7,
"completed": 2
}
}
Error Responses
{
"success": false,
"error": "Domain is required"
}
{
"success": false,
"error": "Invalid domain format"
}
{
"success": false,
"error": "Request failed"
}
Source Code Reference
- API Route:
source/app/api/domain/analyze/route.ts:50
- Domain Functions:
source/lib/domain/
- Type Definitions:
source/lib/domain/types.ts
Timeouts: Domain analysis can take 10-60 seconds depending on options.
Analysis Duration
- Basic analysis (no subdomains): 5-10 seconds
- With subdomain enumeration: 25-35 seconds
- Subdomain timeout: 25 seconds (to prevent hanging)
Optimization Tips
- Disable subdomains for faster results
- Cache results to avoid redundant analyses
- Parallel requests are handled by the server
- Streaming updates provide real-time feedback
Best Practices
Recommendations
- Domain cleaning: Submit clean domains (protocol and path are auto-removed)
- Handle timeouts: Some steps may fail or timeout gracefully
- Cache wisely: Cache for 1-24 hours depending on use case
- Monitor SSL expiry: Alert when
daysUntilExpiry < 30
- Security scoring: Flag domains with
securityHeaders.score < 50
Example Implementation
interface DomainReport {
domain: string;
status: 'available' | 'registered';
sslValid: boolean;
sslExpiry?: string;
securityScore: number;
technologies: string[];
riskLevel: 'safe' | 'suspicious' | 'dangerous';
}
async function analyzeDomainComplete(domain: string): Promise<DomainReport> {
const response = await fetch('/api/domain/analyze', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ domain })
});
const reader = response.body!.getReader();
const decoder = new TextDecoder();
let result: any;
while (true) {
const { done, value } = await reader.read();
if (done) break;
const text = decoder.decode(value);
const lines = text.split('\n');
for (const line of lines) {
if (line.startsWith('data: ')) {
const event = JSON.parse(line.slice(6));
if (event.type === 'complete') {
result = event.data.result;
}
}
}
}
// Generate report
const report: DomainReport = {
domain: result.domain,
status: result.isAvailable ? 'available' : 'registered',
sslValid: result.ssl?.isValid ?? false,
sslExpiry: result.ssl?.validTo,
securityScore: result.securityHeaders?.score ?? 0,
technologies: result.technologies?.map((t: any) => t.name) ?? [],
riskLevel: result.reputation?.isMalicious || result.reputation?.isPhishing
? 'dangerous'
: result.reputation?.riskScore > 50
? 'suspicious'
: 'safe'
};
return report;
}