☀️ 🌙
Home API Docs CLI Docs DNS Hosting Login Sign Up

API Documentation

Comprehensive REST API reference for DNS Science

Table of Contents

Getting Started

The DNS Science API is a RESTful API that allows you to scan domains, retrieve DNS security information, and monitor SSL certificates. All API responses are in JSON format.

Base URL: https://dnsscience.com/api

All requests should include the following headers:

Content-Type: application/json
Accept: application/json

Authentication

Most endpoints are public and do not require authentication. Premium features require an API key or JWT token.

API Key Authentication

Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

JWT Token Authentication

After logging in, include the JWT token in your requests:

Authorization: Bearer YOUR_JWT_TOKEN
Security Note: Never expose your API keys in client-side code. Always make API requests from your backend server.

Rate Limiting

To ensure fair usage, the API implements rate limiting:

  • Free tier: 15,000 requests per day
  • Essentials: 80,000 requests per day
  • Professional: 135,000 requests per day
  • Commercial: 375,000 requests per day
  • Research: 275,000 requests per day
  • Enterprise: Unlimited

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Domain Endpoints

POST /api/scan

Scan a domain for DNS security configurations including DNSSEC, SPF, DKIM, DMARC, MTA-STS, and SMTP STARTTLS.

Request Body

Parameter Type Required Description
domain string Required Domain name to scan (e.g., example.com)
check_ssl boolean Optional Include SSL certificate scanning (default: true)
advanced boolean Optional Enable advanced mode with comprehensive security checks
expert boolean Optional NEW Enable expert mode with customizable intelligence sources
options object Optional NEW Expert mode options: dns, security, email, intel categories

Example Request (Simple)

curl -X POST https://dnsscience.com/api/scan \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "check_ssl": true}'

Example Request (Expert Mode)

curl -X POST https://dnsscience.com/api/scan \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "expert": true,
    "options": {
      "dns": ["records", "dnssec", "propagation"],
      "security": ["ssl", "ssl-chain", "cert-transparency"],
      "email": ["spf", "dkim", "dmarc", "mx-health"],
      "intel": ["whois", "reputation", "threat"]
    }
  }'

Example Response

{
  "domain": "example.com",
  "dnssec_enabled": true,
  "dnssec_valid": true,
  "dnssec_details": "DNSSEC validation successful",
  "spf_valid": true,
  "spf_record": "v=spf1 include:_spf.google.com ~all",
  "spf_details": "SPF record found and valid",
  "dkim_valid": true,
  "dkim_selectors": "[\"default\", \"google\"]",
  "dkim_details": "2 DKIM selectors found",
  "mta_sts_enabled": true,
  "mta_sts_details": "MTA-STS policy found",
  "mta_sts_policy": "version: STSv1\nmode: enforce\nmax_age: 604800",
  "smtp_starttls_25": true,
  "smtp_starttls_587": true,
  "smtp_details": "STARTTLS available on both ports",
  "ssl_certificates": [...]
}

GET /api/domain/{domain}

Retrieve the latest scan results for a specific domain.

URL Parameters

Parameter Type Description
domain string Domain name to retrieve

Example Request

curl https://dnsscience.com/api/domain/example.com

GET /api/domain/{domain}/history

Retrieve scan history for a domain to track configuration changes over time.

Query Parameters

Parameter Type Default Description
limit integer 100 Maximum number of history entries to return

Example Request

curl https://dnsscience.com/api/domain/example.com/history?limit=10

Example Response

{
  "domain": "example.com",
  "count": 10,
  "history": [
    {
      "scan_timestamp": "2025-11-09T10:30:00Z",
      "dnssec_enabled": true,
      "spf_valid": true,
      "dkim_valid": true,
      ...
    }
  ]
}

GET /api/domains

List all tracked domains with pagination support.

Query Parameters

Parameter Type Default Description
limit integer 100 Maximum number of domains to return

Example Request

curl https://dnsscience.com/api/domains?limit=50

GET /api/search

Search for domains by name or pattern.

Query Parameters

Parameter Type Description
q string Search query

Example Request

curl https://dnsscience.com/api/search?q=google

IP Intelligence Endpoints

Comprehensive IP address intelligence including geolocation, BGP routing, threat intelligence, and network information.

GET /api/ip/<ip>/scan

Comprehensive scan of an IP address including geolocation, network info, BGP routing, reputation, and blacklist checks.

Path Parameters

Parameter Type Description
ip string IPv4 address to scan (e.g., 8.8.8.8)

Query Parameters

Parameter Type Default Description
force_refresh boolean false Bypass cache and force fresh scan
full_scan boolean true Include full details (BGP, WHOIS, RBLs)
advanced boolean false 🔬 Advanced Mode: Enable comprehensive analysis with Cloudflare DNS intelligence, IPInfo privacy detection (VPN/Proxy/Tor/Hosting), AbuseIPDB threat intelligence, enhanced BGP analysis, and comprehensive RBL checks
expert boolean false NEW 🎯 Expert Mode: Customize intelligence sources and scan options with granular control
options string (JSON) null NEW Expert mode options: geo, security, advanced categories (JSON string)

Example Requests

# Standard scan
curl https://dnsscience.com/api/ip/8.8.8.8/scan

# Advanced scan with all intelligence sources
curl https://dnsscience.com/api/ip/8.8.8.8/scan?advanced=true

# Expert mode with customizable sources
curl 'https://dnsscience.com/api/ip/8.8.8.8/scan?expert=true&options={"geo":["ipinfo","maxmind"],"security":["abuseipdb","rbl"]}'

# Force fresh advanced scan
curl https://dnsscience.com/api/ip/8.8.8.8/scan?advanced=true&force_refresh=true

Example Response

{
  "ip": "8.8.8.8",
  "scan_timestamp": "2025-01-12T10:30:00Z",
  "scan_duration_ms": 2341,
  "ip_version": 4,
  "is_private": false,
  "geolocation": {
    "country": "US",
    "region": "California",
    "city": "Mountain View",
    "postal_code": "94035",
    "coordinates": {
      "latitude": 37.4056,
      "longitude": -122.0775
    },
    "timezone": "America/Los_Angeles"
  },
  "network": {
    "asn": 15169,
    "asn_name": "GOOGLE",
    "organization": "AS15169 Google LLC",
    "isp": "Google LLC",
    "hostname": "dns.google",
    "is_vpn": false,
    "is_proxy": false,
    "is_tor": false,
    "is_hosting": true
  },
  "bgp": {
    "prefix": "8.8.8.0/24",
    "origin_asn": 15169,
    "asn_name": "GOOGLE",
    "asn_country": "US",
    "is_announced": true,
    "path": [15169, 7018, 3356]
  },
  "reputation": {
    "abuse_confidence": 0,
    "total_reports": 0,
    "num_distinct_users": 0,
    "last_reported_at": null,
    "is_whitelisted": false,
    "usage_type": "Data Center/Web Hosting/Transit",
    "isp": "Google LLC",
    "domain": "google.com",
    "threat_categories": [],
    "blacklists": {
      "hit_count": 0,
      "listed_in": [],
      "details": {
        "spamhaus_zen": {"listed": false},
        "spamhaus_sbl": {"listed": false},
        "spamhaus_xbl": {"listed": false},
        "sorbs": {"listed": false},
        "barracuda": {"listed": false},
        "spamcop": {"listed": false}
      }
    }
  },
  "whois": {
    "net_name": "GOOGLE",
    "description": "Google LLC",
    "country": "US",
    "net_range": "8.8.8.0 - 8.8.8.255",
    "abuse_contact": "network-abuse@google.com"
  },
  "reverse_dns": {
    "has_ptr": true,
    "ptr_record": "dns.google",
    "ptr_records": ["dns.google"]
  },
  "data_sources": ["ipinfo", "abuseipdb", "ripestat_bgp", "whois", "rbl", "ptr"],
  "errors": []
}

Response Fields

Field Type Description
geolocation object Geographic location data from IPInfo.io (country, region, city, coordinates, timezone)
network.is_vpn boolean IPInfo.io privacy detection: VPN detected (requires paid tier)
network.is_proxy boolean IPInfo.io privacy detection: Proxy detected (requires paid tier)
network.is_tor boolean IPInfo.io privacy detection: Tor exit node detected (requires paid tier)
network.is_hosting boolean IPInfo.io privacy detection: Datacenter/hosting IP (requires paid tier)
reputation.abuse_confidence integer AbuseIPDB confidence score (0-100) indicating likelihood of malicious activity
reputation.threat_categories array AbuseIPDB threat category IDs (3=Fraud, 4=DDoS, 9=Hacking, 10=Spam, 11=Malware, etc.)
reputation.num_distinct_users integer Number of distinct users who reported this IP to AbuseIPDB
reputation.blacklists object RBL/DNSBL check results from 10+ blacklist databases
whois.abuse_contact string Abuse contact email from WHOIS/RIPEstat data
data_sources array List of successfully queried data sources
errors array Any errors encountered while querying data sources

GET /api/ip/<ip>/reputation

Quick reputation check for an IP address (abuse confidence, reports, blacklists).

Example Request

curl https://dnsscience.com/api/ip/45.33.32.156/reputation

Example Response

{
  "ip": "45.33.32.156",
  "abuse_confidence": 0,
  "total_reports": 0,
  "blacklists": {
    "total_hits": 0,
    "details": {
      "spamhaus": {"listed": false},
      "sorbs": {"listed": false},
      "barracuda": {"listed": false}
    }
  },
  "is_tor": false,
  "is_proxy": false,
  "is_vpn": false
}

GET /api/ip/<ip>/bgp

Get BGP routing information for an IP address.

Example Response

{
  "ip": "1.1.1.1",
  "bgp": {
    "prefix": "1.1.1.0/24",
    "origin_asn": 13335,
    "as_path": [13335],
    "is_announced": true,
    "rpki_status": "valid"
  }
}

GET /api/ip/<ip>/history

Get historical scan data for an IP address.

Query Parameters

Parameter Type Default Description
limit integer 50 Number of historical scans to return

GET /api/range/<cidr>/scan

Scan an IP range in CIDR notation with authentication-based limits.

Path Parameters

Parameter Type Description
cidr string CIDR notation (e.g., 192.168.1.0/24)

Query Parameters

Parameter Type Default Description
max_ips integer 256 Maximum IPs to scan (authenticated users: up to 65536)

Access Control

User Type Maximum Range Max IPs
Anonymous /24 or smaller 256
Authenticated /16 or smaller 65,536

Example Requests

# Anonymous users - /24 or smaller
curl "https://dnsscience.com/api/range/8.8.8.0%2F24/scan"

# Authenticated users can scan larger ranges
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://dnsscience.com/api/range/8.8.0.0%2F20/scan?max_ips=4096"

Example Response

{
  "cidr": "8.8.8.0/29",
  "total_ips": 8,
  "scanned_ips": 6,
  "results": [
    {
      "ip": "8.8.8.1",
      "geolocation": {...},
      "network": {...},
      "reputation": {...}
    },
    ...
  ],
  "summary": {
    "alive_ips": 6,
    "threat_ips": 0,
    "blacklisted_ips": 0,
    "countries": {"US": 6},
    "asns": {15169: 6}
  }
}
Note: Range scanning limits are enforced based on authentication status. Anonymous users are limited to /24 (256 IPs) to prevent abuse. Login to scan larger ranges.

GET /api/asn/<asn>

Get Autonomous System information by ASN number.

Example Request

curl https://dnsscience.com/api/asn/15169

Example Response

{
  "asn": 15169,
  "name": "GOOGLE",
  "description": "Google LLC",
  "country": "US",
  "announced_prefixes": 256,
  "prefixes": [
    "8.8.8.0/24",
    "8.8.4.0/24",
    ...
  ]
}

GET /api/ips/high-risk

Get list of IPs with high abuse confidence scores.

Query Parameters

Parameter Type Default Description
limit integer 100 Number of IPs to return
min_confidence integer 75 Minimum abuse confidence score (0-100)

Example Response

{
  "total": 42,
  "ips": [
    {
      "ip": "185.220.101.15",
      "abuse_confidence": 100,
      "total_reports": 543,
      "country": "NL",
      "asn": 206898,
      "last_seen": "2025-11-12T07:30:00Z"
    },
    ...
  ]
}
Data Sources: IP intelligence data is aggregated from multiple sources including IPinfo, AbuseIPDB, RIPEstat, BGPView, and 10+ DNS-based blacklists. Results are cached for 6-24 hours depending on data type.

Authentication Endpoints

POST /api/auth/register

Register a new user account.

Request Body

Parameter Type Required Description
email string Required User email address
password string Required User password (min 8 characters)
first_name string Optional User first name
last_name string Optional User last name

Example Request

curl -X POST https://dnsscience.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "first_name": "John",
    "last_name": "Doe"
  }'

POST /api/auth/login

Authenticate and receive a JWT token.

Request Body

Parameter Type Required Description
email string Required User email address
password string Required User password

Example Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 123,
    "email": "user@example.com",
    "first_name": "John"
  }
}

Reverse WHOIS Endpoints

Search for domains by registrant information, registrar, or nameserver. Similar to SecurityTrails reverse WHOIS functionality.

GET /api/v1/reverse-whois/email/{email}

Search all domains registered with a specific email address.

Parameters

  • email (path) - Email address to search
  • limit (query, optional) - Maximum results (default: 100, max: 1000)
  • offset (query, optional) - Pagination offset (default: 0)

Example Request

curl -X GET "https://dnsscience.afterdarksys.com/api/v1/reverse-whois/email/admin@example.com?limit=50" \
     -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "search_type": "email",
  "search_value": "admin@example.com",
  "domain_count": 42,
  "cached": true,
  "last_updated": "2025-11-17T10:30:00Z",
  "domains": [
    {
      "domain_name": "example.com",
      "registrar_name": "GoDaddy",
      "registration_date": "2020-01-15T00:00:00Z",
      "expiration_date": "2026-01-15T00:00:00Z",
      "nameservers": ["ns1.example.com", "ns2.example.com"],
      "entity_role": "registrant"
    }
  ]
}

GET /api/v1/reverse-whois/organization/{organization}

Search all domains registered to an organization.

Parameters

  • organization (path) - Organization name to search
  • limit (query, optional) - Maximum results (default: 100)

Example Response

{
  "search_type": "organization",
  "search_value": "Acme Corporation",
  "domain_count": 156,
  "domains": [
    {
      "domain_name": "acmecorp.com",
      "registrar_name": "NameCheap",
      "country_code": "US",
      "expiration_date": "2026-05-20T00:00:00Z"
    }
  ]
}

GET /api/v1/reverse-whois/registrar/{registrar}

Search all domains using a specific registrar.

Example Response

{
  "search_type": "registrar",
  "search_value": "GoDaddy",
  "domain_count": 2341,
  "registrar_info": {
    "registrar_iana_id": 146,
    "abuse_email": "abuse@godaddy.com"
  },
  "domains": [
    {
      "domain_name": "example.com",
      "registration_date": "2015-03-10T00:00:00Z",
      "expiration_date": "2026-03-10T00:00:00Z",
      "secure_dns_delegated": true
    }
  ]
}

GET /api/v1/reverse-whois/nameserver/{nameserver}

Search all domains using a specific nameserver.

Example Response

{
  "search_type": "nameserver",
  "search_value": "ns1.cloudflare.com",
  "domain_count": 8742,
  "domains": [
    {
      "domain_name": "example.com",
      "registrar_name": "Cloudflare",
      "nameservers": ["ns1.cloudflare.com", "ns2.cloudflare.com"]
    }
  ]
}

Threat Intelligence Endpoints

Check domains and IPs against 20+ threat intelligence feeds including CISA KEV, URLhaus, ThreatFox, Feodo Tracker, CINS Score, Blocklist.de, and SSL Blacklist.

GET /api/v1/threat-intel/check/{indicator}

Check if a domain or IP address appears in threat intelligence feeds.

Parameters

  • indicator (path) - Domain name or IP address to check

Example Request

curl -X GET "https://dnsscience.afterdarksys.com/api/v1/threat-intel/check/malicious-site.com" \
     -H "X-API-Key: YOUR_API_KEY"

Example Response (Threat Detected)

{
  "indicator": "malicious-site.com",
  "is_malicious": true,
  "severity": "high",
  "threat_type": "phishing",
  "feeds": ["PhishTank", "OpenPhish", "URLhaus"],
  "details": "Known phishing site targeting financial institutions",
  "first_seen": "2025-11-10T08:30:00Z",
  "last_seen": "2025-11-17T14:22:00Z",
  "feeds_checked": 20
}

Example Response (Clean)

{
  "indicator": "google.com",
  "is_malicious": false,
  "feeds_checked": 20,
  "checked_at": "2025-11-17T15:00:00Z"
}

GET /api/v1/threat-intel/cisa-kev/{cve_id}

Check if a CVE is in CISA's Known Exploited Vulnerabilities catalog.

Parameters

  • cve_id (path) - CVE identifier (e.g., CVE-2024-1234)

Example Response (In KEV)

{
  "cve_id": "CVE-2024-1234",
  "in_cisa_kev": true,
  "vulnerability_name": "Apache Log4j Remote Code Execution",
  "vendor": "Apache",
  "product": "Log4j",
  "description": "Log4j allows remote code execution via JNDI injection",
  "date_added": "2024-12-10",
  "due_date": "2024-12-31",
  "required_action": "Apply updates per vendor instructions",
  "known_ransomware_use": false
}

GET /api/v1/threat-intel/feeds

List all active threat intelligence feeds and their status.

Example Response

{
  "total_feeds": 20,
  "feeds": [
    {
      "name": "CISA KEV",
      "type": "cve",
      "status": "active",
      "last_updated": "2025-11-17T06:00:00Z",
      "indicator_count": 1247
    },
    {
      "name": "URLhaus",
      "type": "url",
      "status": "active",
      "last_updated": "2025-11-17T14:00:00Z",
      "indicator_count": 8932
    },
    {
      "name": "CINS Score",
      "type": "ip",
      "status": "active",
      "last_updated": "2025-11-17T15:00:00Z",
      "indicator_count": 15634
    },
    {
      "name": "Blocklist.de",
      "type": "ip",
      "status": "active",
      "last_updated": "2025-11-17T15:00:00Z",
      "indicator_count": 23421
    },
    {
      "name": "ThreatFox",
      "type": "ioc",
      "status": "active",
      "last_updated": "2025-11-17T14:30:00Z",
      "indicator_count": 4521
    },
    {
      "name": "Feodo Tracker",
      "type": "botnet_c2",
      "status": "active",
      "last_updated": "2025-11-17T14:45:00Z",
      "indicator_count": 342
    },
    {
      "name": "SSL Blacklist",
      "type": "ssl_certificate",
      "status": "active",
      "last_updated": "2025-11-17T15:00:00Z",
      "indicator_count": 1823
    }
  ]
}

Web Technologies Endpoints NEW

W3Techs-style Detection: Detect web technologies including web servers, CMS platforms, programming languages, JavaScript frameworks, CDNs, analytics, and more. Market share statistics are computed across all scanned websites.

POST /api/tech/scan

Scan a website to detect technologies used. Returns detected technologies with confidence scores and evidence.

Request Body

Parameter Type Required Description
url string Required Domain or URL to scan (e.g., "example.com" or "https://example.com")

Example Response

{
  "domain": "example.com",
  "url": "https://example.com",
  "server_ip": "93.184.216.34",
  "technologies": [
    {
      "name": "nginx",
      "category": "Web Server",
      "subcategory": null,
      "version": "1.21.6",
      "confidence": 100,
      "evidence": "server header",
      "website": "https://nginx.org"
    },
    {
      "name": "Cloudflare",
      "category": "CDN",
      "subcategory": null,
      "version": null,
      "confidence": 95,
      "evidence": "cf-ray header",
      "website": "https://cloudflare.com"
    }
  ],
  "ssl_info": {
    "issuer": "DigiCert Inc",
    "not_before": "2024-01-01",
    "not_after": "2025-01-01",
    "days_until_expiry": 180
  }
}

GET /api/tech/stats

Get overall technology statistics including total websites scanned, technologies tracked, and detection counts.

Example Response

{
  "total_websites": 15420,
  "total_technologies": 156,
  "total_categories": 12,
  "total_detections": 89340,
  "last_scan": "2024-12-14T10:30:00Z"
}

GET /api/tech/top

Get top technologies by website usage count. Optionally filter by category.

Query Parameters

Parameter Type Required Description
category string Optional Filter by category (e.g., "Web Server", "CMS", "CDN")
limit integer Optional Number of results (default: 20, max: 100)

Example Response

{
  "technologies": [
    {"name": "nginx", "category": "Web Server", "website_count": 8540},
    {"name": "Apache", "category": "Web Server", "website_count": 4230},
    {"name": "Cloudflare", "category": "CDN", "website_count": 6120},
    {"name": "WordPress", "category": "CMS", "website_count": 3890}
  ]
}

GET /api/tech/categories

Get statistics for all technology categories including top technologies in each category.

Example Response

{
  "categories": [
    {
      "category": "Web Server",
      "website_count": 12540,
      "unique_technologies": 15,
      "top_technologies": [
        {"name": "nginx", "count": 8540},
        {"name": "Apache", "count": 4230}
      ]
    },
    {
      "category": "CMS",
      "website_count": 5890,
      "unique_technologies": 28,
      "top_technologies": [
        {"name": "WordPress", "count": 3890},
        {"name": "Drupal", "count": 420}
      ]
    }
  ]
}

GET /api/tech/website/{domain}

Get previously detected technologies for a specific website.

GET /api/tech/using/{tech_name}

Get list of websites using a specific technology.

GET /api/tech/search

Search for technologies by name.

Query Parameters

Parameter Type Required Description
q string Required Search query
limit integer Optional Number of results (default: 20)

Quality Alerts Endpoints NEW

Website Quality Analysis: Check websites for common quality issues including SEO problems, security headers, accessibility, and performance indicators.

POST /api/quality/check

Analyze a website for quality issues. Returns a list of checks with pass/fail status and recommendations.

Request Body

Parameter Type Required Description
url string Required Domain or URL to analyze

Quality Checks Performed

  • Page Title - Checks for presence of <title> tag
  • Meta Description - Checks for meta description tag
  • Character Encoding - Checks for charset declaration
  • Viewport Meta - Checks for mobile-friendly viewport
  • Language Attribute - Checks for lang attribute on <html>
  • HTTPS - Checks if site uses HTTPS
  • Security Headers - Checks for X-Content-Type-Options, X-Frame-Options
  • Page Size - Warns if page exceeds 1MB
  • Favicon - Checks for favicon presence

Example Response

{
  "url": "https://example.com",
  "alerts": [
    {
      "check": "Page Title",
      "passed": true,
      "message": "Page has a title tag",
      "severity": "info"
    },
    {
      "check": "Meta Description",
      "passed": false,
      "message": "Missing meta description - important for SEO",
      "severity": "warning"
    },
    {
      "check": "HTTPS",
      "passed": true,
      "message": "Site uses HTTPS",
      "severity": "info"
    },
    {
      "check": "Security Headers",
      "passed": false,
      "message": "Missing X-Content-Type-Options header",
      "severity": "warning"
    }
  ]
}

Statistics Endpoints

GET /api/stats/live

Get real-time platform statistics including total domains, SSL certificates, and threat intelligence data.

Example Response

{
  "total_domains": 125000,
  "ssl_certificates": 87500,
  "email_records": 156000,
  "drift_monitoring": 42000,
  "ips_tracked": 98000,
  "active_feeds": 20,
  "last_updated": "2025-11-09T10:30:00Z"
}

Advanced DNS v2 Endpoints NEW

Version 2 API: These endpoints provide advanced DNS analysis capabilities including EDE decoding, domain reputation scoring, DNS fingerprinting, and SVCB/HTTPS record analysis.

POST /api/v2/ede/decode

Decode Extended DNS Error (EDE) codes per RFC 8914. Returns detailed information about DNS errors including severity and recommendations.

Request Body

Parameter Type Required Description
code integer Required EDE error code (0-29)
extra_text string Optional Additional text from DNS response

Example Response

{
  "code": 6,
  "name": "DNSSEC Bogus",
  "description": "DNSSEC validation failed",
  "severity": "critical",
  "extra_text": "RRSIG expired",
  "rfc": "RFC 8914",
  "troubleshooting": [
    "Check RRSIG record signatures and expiration",
    "Verify DNSKEY records match DS in parent zone",
    "Test with: dig @8.8.8.8 +dnssec example.com"
  ]
}

GET /api/v2/ede/codes

List all 30 Extended DNS Error codes defined in RFC 8914.

GET /api/v2/ede/test-resolver

Test if a DNS resolver supports Extended DNS Errors.

Query Parameters

Parameter Type Required Description
resolver string Optional Resolver IP (default: 8.8.8.8)

GET /api/v2/reputation/score

Calculate a comprehensive domain reputation score (0-1000) based on 8 weighted factors including DNS configuration, email authentication, DNSSEC, SSL/TLS, stability, threat intelligence, infrastructure diversity, and performance.

Query Parameters

Parameter Type Required Description
domain string Required Domain name to score

Example Response

{
  "domain": "cloudflare.com",
  "score": 920,
  "grade": "A+",
  "components": {
    "dns_config": 180,
    "email_auth": 140,
    "dnssec": 150,
    "ssl_tls": 95,
    "stability": 90,
    "threat_intel": 145,
    "diversity": 80,
    "performance": 40
  },
  "recommendations": [
    "Consider adding DANE/TLSA records for enhanced security"
  ]
}

GET /api/v2/fingerprint/domain

Fingerprint domain infrastructure by analyzing DNS response patterns, nameserver providers, CDN usage, and hosting characteristics.

Query Parameters

Parameter Type Required Description
domain string Required Domain to fingerprint

Example Response

{
  "domain": "example.com",
  "providers": {
    "dns": "cloudflare",
    "cdn": ["cloudflare"],
    "hosting": ["aws"]
  },
  "characteristics": {
    "anycast": true,
    "load_balanced": true,
    "geo_distributed": true
  },
  "confidence": 0.95
}

GET /api/v2/fingerprint/resolver

Fingerprint DNS resolver software by analyzing response patterns and characteristics.

Query Parameters

Parameter Type Required Description
resolver string Required Resolver IP address

GET /api/v2/svcb/analyze

Analyze SVCB (type 64) and HTTPS (type 65) records per RFC 9460, including ECH key extraction and ALPN protocol parsing.

Query Parameters

Parameter Type Required Description
domain string Required Domain to analyze

Example Response

{
  "domain": "cloudflare.com",
  "svcb_records": [],
  "https_records": [
    {
      "priority": 1,
      "target": ".",
      "alpn": ["h3", "h2"],
      "ipv4hint": ["104.16.132.229"],
      "ipv6hint": ["2606:4700::6810:84e5"],
      "ech": "present"
    }
  ],
  "supports_http3": true,
  "supports_ech": true
}

Premium Endpoints PREMIUM

Premium Features: The following endpoints require a premium subscription and API authentication.

POST /api/validate/dns-config PREMIUM

Validate uploaded DNS configuration files (BIND9, Unbound, NSD, djbdns).

Request (multipart/form-data)

Parameter Type Description
file file DNS configuration file
server_type string Server type (bind9, unbound, nsd, djbdns) - optional, auto-detected

Example Request

curl -X POST https://dnsscience.com/api/validate/dns-config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@named.conf" \
  -F "server_type=bind9"

POST /api/cert/resolve-chain PREMIUM

Automatically resolve and download complete certificate chain from a leaf certificate.

Request (multipart/form-data)

Parameter Type Description
file file Certificate file (PEM, DER, CRT)
export_format string Export format (pem, der, pkcs7) - optional

Example Request

curl -X POST https://dnsscience.com/api/cert/resolve-chain \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@certificate.pem" \
  -F "export_format=pem"

POST /api/jks/validate PREMIUM

Validate Java KeyStore (JKS) files and check certificate chain integrity.

Request (multipart/form-data)

Parameter Type Description
file file JKS keystore file
password string Keystore password

Example Request

curl -X POST https://dnsscience.com/api/jks/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@keystore.jks" \
  -F "password=changeit"

GraphQL API

Introduction

DNS Science provides a powerful GraphQL API for flexible querying of DNS intelligence data. GraphQL allows you to request exactly the data you need in a single query.

GraphQL Endpoint: https://dnsscience.com/graphql
GraphiQL Interface: https://dnsscience.com/graphql (Interactive API Explorer)

Key Features

  • Request only the fields you need
  • Combine multiple queries in one request
  • Strongly typed schema with automatic validation
  • Nested data fetching (e.g., domain → DNS records → geolocation)
  • Built-in documentation via GraphiQL

Available Queries

Domain Queries

# Get domain information
query {
  domain(domain: "example.com") {
    domain
    dnssecEnabled
    dnssecValid
    spfValid
    spfRecord
    dmarcValid
    dmarcPolicy
    sslValid
    sslIssuer
    sslExpiry
    dnsRecords {
      name
      type
      value
      ttl
    }
  }
}

# List all domains with pagination
query {
  domains(limit: 50, offset: 0) {
    domain
    dnssecEnabled
    createdAt
  }
}

# Search domains by pattern
query {
  searchDomains(query: "google", limit: 10) {
    domain
    dnssecEnabled
    spfValid
  }
}

IP Intelligence Queries

# Get comprehensive IP information
query {
  ipAddress(ip: "8.8.8.8") {
    ip
    ipVersion
    isPrivate
    scanTimestamp
    geolocation {
      country
      region
      city
      latitude
      longitude
      timezone
    }
    network {
      asn
      asnName
      organization
      isp
      hostname
      isVpn
      isProxy
      isTor
      isHosting
    }
    bgp {
      prefix
      originAsn
      asPath
      isAnnounced
      rpkiStatus
    }
    reputation {
      abuseConfidenceScore
      totalReports
      lastReported
      isWhitelisted
      blacklistHits
    }
  }
}

# Get IP scan history
query {
  ipScanHistory(ip: "1.1.1.1", limit: 10) {
    ip
    scanTimestamp
    geolocation {
      country
      city
    }
  }
}

Certificate Queries

# Get SSL certificate information
query {
  certificate(domain: "example.com") {
    domain
    issuer
    subject
    validFrom
    validUntil
    serialNumber
    isValid
    isExpired
    daysUntilExpiry
  }
}

# Get expiring certificates
query {
  expiringCertificates(days: 30) {
    domain
    validUntil
    daysUntilExpiry
    issuer
  }
}

Statistics Queries

# Get platform statistics
query {
  statistics {
    totalDomains
    totalIpScans
    dnssecEnabledCount
    sslValidCount
    totalUsers
  }
}

Mutations

GraphQL mutations allow you to trigger scans and modify data.

# Trigger a domain scan
mutation {
  scanDomain(domain: "example.com", checkSsl: true) {
    success
    domain {
      domain
      dnssecEnabled
      spfValid
    }
  }
}

# Trigger an IP scan
mutation {
  scanIpAddress(ip: "8.8.8.8", fullScan: true) {
    success
    ipAddress {
      ip
      geolocation {
        country
        city
      }
    }
  }
}

GraphQL Usage Examples

Python with requests

import requests

url = "https://dnsscience.com/graphql"

query = """
query {
  domain(domain: "example.com") {
    domain
    dnssecEnabled
    spfValid
    dnsRecords {
      type
      value
    }
  }
}
"""

response = requests.post(url, json={'query': query})
data = response.json()
print(data['data']['domain'])

JavaScript with fetch

const query = `
  query {
    ipAddress(ip: "8.8.8.8") {
      ip
      geolocation {
        country
        city
      }
      reputation {
        abuseConfidenceScore
      }
    }
  }
`;

fetch('https://dnsscience.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query })
})
.then(res => res.json())
.then(data => console.log(data.data.ipAddress));

cURL

curl -X POST https://dnsscience.com/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { domain(domain: \"example.com\") { domain dnssecEnabled spfValid } }"
  }'

WebSocket API

Introduction

DNS Science provides real-time WebSocket monitoring for Certificate Transparency logs, DNS changes, SSL expiry alerts, and threat intelligence feeds.

WebSocket Endpoint: wss://dnsscience.com/socket.io/
Demo Page: https://dnsscience.com/realtime (Live monitoring dashboard)

Key Features

  • Real-time Certificate Transparency log monitoring
  • Live DNS record change detection
  • SSL certificate expiry alerts
  • Threat intelligence feed
  • Domain-specific subscriptions
  • Platform statistics updates

Technology

DNS Science uses Socket.IO for WebSocket communication, providing automatic reconnection, fallback transports, and event-based messaging.

Client Events (Emit)

Events your client can emit to the server:

Event Parameters Description
subscribe_domain {domain: "example.com"} Subscribe to all events for a specific domain
unsubscribe_domain {domain: "example.com"} Unsubscribe from domain events
subscribe_ct_logs none Subscribe to global Certificate Transparency log stream
subscribe_dns_changes none Subscribe to global DNS change stream
subscribe_threat_feed none Subscribe to real-time threat intelligence feed
request_stats none Request current platform statistics
ping none Keepalive ping (responds with pong)

Server Events (Listen)

Events your client can listen for from the server:

Event Data Structure Description
connected {session_id, timestamp, message} Connection confirmation
ct_log_entry {domain, certificate: {issuer, serial, not_before, not_after}, timestamp} New Certificate Transparency log entry
dns_change {domain, record_type, old_value, new_value, timestamp} DNS record change detected
ssl_expiry_alert {domain, days_until_expiry, expiry_date, severity, timestamp} SSL certificate expiring soon
threat_alert {type, message, severity, ...} Security threat detected
scan_complete {domain, result, timestamp} Domain scan completed
stats_update {total_domains, total_scans_today, active_monitors, ct_logs_today, timestamp} Platform statistics update
pong {timestamp} Response to ping keepalive
error {message} Error message

Subscription Patterns

Domain-Specific Monitoring

Subscribe to all events for a specific domain:

// Subscribe to domain
socket.emit('subscribe_domain', { domain: 'example.com' });

// Listen for domain-specific events
socket.on('ct_log_entry', (data) => {
  if (data.domain === 'example.com') {
    console.log('New certificate:', data.certificate);
  }
});

socket.on('dns_change', (data) => {
  if (data.domain === 'example.com') {
    console.log('DNS changed:', data.record_type, data.new_value);
  }
});

Global Feed Monitoring

Subscribe to global streams to monitor all activity:

// Subscribe to all CT logs
socket.emit('subscribe_ct_logs');

// Subscribe to all DNS changes
socket.emit('subscribe_dns_changes');

// Subscribe to threat intelligence
socket.emit('subscribe_threat_feed');

WebSocket Usage Examples

JavaScript/Browser (Socket.IO)

<script src="https://cdn.socket.io/4.5.4/socket.io.min.js"></script>
<script>
// Connect to WebSocket server
const socket = io('https://dnsscience.com');

// Connection events
socket.on('connect', () => {
  console.log('Connected to DNS Science WebSocket');

  // Subscribe to feeds
  socket.emit('subscribe_ct_logs');
  socket.emit('subscribe_dns_changes');
  socket.emit('subscribe_threat_feed');

  // Subscribe to specific domain
  socket.emit('subscribe_domain', { domain: 'example.com' });

  // Request stats
  socket.emit('request_stats');
});

socket.on('disconnect', () => {
  console.log('Disconnected from WebSocket');
});

// Listen for Certificate Transparency logs
socket.on('ct_log_entry', (data) => {
  console.log('New certificate for:', data.domain);
  console.log('Issuer:', data.certificate.issuer);
  console.log('Valid until:', data.certificate.not_after);
});

// Listen for DNS changes
socket.on('dns_change', (data) => {
  console.log('DNS changed for:', data.domain);
  console.log(`${data.record_type}: ${data.old_value} → ${data.new_value}`);
});

// Listen for SSL expiry alerts
socket.on('ssl_expiry_alert', (data) => {
  console.log('SSL expiring for:', data.domain);
  console.log(`Days remaining: ${data.days_until_expiry}`);
  console.log(`Severity: ${data.severity}`);
});

// Listen for threat alerts
socket.on('threat_alert', (data) => {
  console.warn('Threat detected:', data.type);
  console.warn('Message:', data.message);
});

// Listen for scan completion
socket.on('scan_complete', (data) => {
  console.log('Scan completed for:', data.domain);
});

// Listen for stats updates
socket.on('stats_update', (data) => {
  console.log('Platform stats:', data);
  console.log(`Total domains: ${data.total_domains}`);
  console.log(`Scans today: ${data.total_scans_today}`);
});
</script>

Python (socketio client)

import socketio

# Create Socket.IO client
sio = socketio.Client()

@sio.event
def connect():
    print('Connected to DNS Science WebSocket')

    # Subscribe to feeds
    sio.emit('subscribe_ct_logs')
    sio.emit('subscribe_dns_changes')
    sio.emit('subscribe_threat_feed')

    # Subscribe to specific domain
    sio.emit('subscribe_domain', {'domain': 'example.com'})

    # Request stats
    sio.emit('request_stats')

@sio.event
def disconnect():
    print('Disconnected from WebSocket')

@sio.on('ct_log_entry')
def on_ct_log(data):
    print(f"New certificate for: {data['domain']}")
    print(f"Issuer: {data['certificate']['issuer']}")

@sio.on('dns_change')
def on_dns_change(data):
    print(f"DNS changed for: {data['domain']}")
    print(f"{data['record_type']}: {data['old_value']} → {data['new_value']}")

@sio.on('ssl_expiry_alert')
def on_ssl_alert(data):
    print(f"SSL expiring for: {data['domain']}")
    print(f"Days remaining: {data['days_until_expiry']}")

@sio.on('threat_alert')
def on_threat(data):
    print(f"Threat detected: {data['type']}")
    print(f"Message: {data['message']}")

@sio.on('stats_update')
def on_stats(data):
    print(f"Platform stats: {data}")

# Connect to server
sio.connect('https://dnsscience.com')

# Keep alive
sio.wait()

Node.js (socket.io-client)

const io = require('socket.io-client');

// Connect to WebSocket server
const socket = io('https://dnsscience.com');

socket.on('connect', () => {
  console.log('Connected to DNS Science WebSocket');

  // Subscribe to feeds
  socket.emit('subscribe_ct_logs');
  socket.emit('subscribe_dns_changes');
  socket.emit('subscribe_threat_feed');

  // Subscribe to specific domain
  socket.emit('subscribe_domain', { domain: 'example.com' });

  // Request stats
  socket.emit('request_stats');
});

socket.on('disconnect', () => {
  console.log('Disconnected from WebSocket');
});

// Certificate Transparency logs
socket.on('ct_log_entry', (data) => {
  console.log(`New certificate for: ${data.domain}`);
  console.log(`Issuer: ${data.certificate.issuer}`);
});

// DNS changes
socket.on('dns_change', (data) => {
  console.log(`DNS changed for: ${data.domain}`);
  console.log(`${data.record_type}: ${data.old_value} → ${data.new_value}`);
});

// SSL expiry alerts
socket.on('ssl_expiry_alert', (data) => {
  console.log(`SSL expiring for: ${data.domain}`);
  console.log(`Days remaining: ${data.days_until_expiry}`);
});

// Threat alerts
socket.on('threat_alert', (data) => {
  console.warn(`Threat detected: ${data.type}`);
  console.warn(`Message: ${data.message}`);
});

// Platform statistics
socket.on('stats_update', (data) => {
  console.log(`Total domains: ${data.total_domains}`);
  console.log(`Scans today: ${data.total_scans_today}`);
});
Try it out: Visit the live monitoring dashboard to see WebSocket events in real-time.

Data Feeds (v2)

Access passive DNS data, new domain feeds, and DNS topology information.

GET /api/v2/passive-dns/query

Query passive DNS database for historical DNS records.

Parameters

  • domain (required) - Domain to search
  • limit (optional) - Max results (default: 100)
curl "https://dnsscience.io/api/v2/passive-dns/query?domain=example.com"
GET /api/v2/feeds/new-domains

Get newly registered domains feed for early threat detection.

Parameters

  • days (optional) - Days back to search (default: 7)
  • limit (optional) - Max results
GET /api/v2/topology/domain/{domain}

Visualize DNS infrastructure topology showing relationships between nameservers, IP addresses, and ASNs.

Services & Marketplace (v2)

Access DNSSEC auditing, data products, and compliance features.

POST /api/v2/audit/dnssec

Comprehensive DNSSEC security audit with scoring and recommendations.

curl -X POST "https://dnsscience.io/api/v2/audit/dnssec" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'
GET /api/v2/marketplace/products

List available data products (Passive DNS, Threat Intel, New Domain Feed, Zone Files).

GET /api/v2/first-watch/alerts

Get early IOC detection alerts before they appear in standard threat feeds.

GET /api/v2/whitelabel/config

Get current white-label configuration for resellers.

POST /api/v2/compliance/generate-report

Generate compliance reports (SOC 2, GDPR, PCI-DSS). Enterprise feature.

GET /api/v2/training/courses

List available DNS security training courses and certifications.

Advanced DNS Features (v2)

Cutting-edge DNS analysis including DoQ, ZONEMD, Multi-Signer DNSSEC, and more.

GET /api/v2/experimental/doq/test

Test DNS over QUIC (RFC 9250) support and compare performance with DoH/DoT.

Parameters

  • domain (required) - Domain to test
POST /api/v2/dnssec/zonemd/validate

Validate ZONEMD records (RFC 8976) for zone integrity verification.

GET /api/v2/dnssec/multi-signer/analyze

Analyze multi-signer DNSSEC configuration (RFC 8901).

Parameters

  • domain (required) - Domain to analyze
GET /api/v2/history/timeline/{domain}

View historical DNS snapshots and track changes over time.

Parameters

  • days (optional) - Days of history (default: 30)
  • record_type (optional) - Filter by record type
GET /api/v2/drift/detect/{domain}

ML-based anomaly detection for unexpected DNS configuration changes.

GET /api/v2/intel/tech-stack/{domain}

Detect technology stack from DNS records (CDN, email providers, hosting, security services).

POST /api/v2/bulk/submit

Submit bulk domain lookup job for async processing.

curl -X POST "https://dnsscience.io/api/v2/bulk/submit" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["example.com", "github.com", "google.com"]}'
GET /api/v2/sso/config

Get SSO configuration status. Enterprise feature supporting SAML, OIDC, and OAuth2.

Web3 & Alternative DNS (v2)

Resolve decentralized and alternative DNS systems including ENS, Unstoppable Domains, Handshake, and I2P.

GET /api/v2/web3/ens/resolve

Resolve Ethereum Name Service (.eth) domains to wallet addresses and records.

Parameters

  • name or domain (required) - ENS domain (e.g., vitalik.eth)
curl "https://dnsscience.io/api/v2/web3/ens/resolve?name=vitalik.eth"
GET /api/v2/web3/unstoppable/resolve

Resolve Unstoppable Domains (.crypto, .nft, .wallet, .blockchain).

Parameters

  • name or domain (required) - Domain to resolve
GET /api/v2/web3/handshake/resolve

Resolve Handshake (HNS) decentralized TLD domains.

Parameters

  • name or domain (required) - Handshake domain
GET /api/v2/alternative/i2p/resolve

Resolve I2P (.i2p) anonymous network domains.

Parameters

  • name or domain (required) - I2P domain (e.g., stats.i2p)
GET /api/v2/web3/resolve

Unified resolver that auto-detects domain type and resolves accordingly.

Parameters

  • name or domain (required) - Any Web3/alternative domain
# Auto-detects ENS domain
curl "https://dnsscience.io/api/v2/web3/resolve?domain=vitalik.eth"

# Auto-detects Unstoppable domain
curl "https://dnsscience.io/api/v2/web3/resolve?domain=brad.crypto"

# Auto-detects Handshake domain
curl "https://dnsscience.io/api/v2/web3/resolve?domain=welcome.nb"

# Auto-detects I2P domain
curl "https://dnsscience.io/api/v2/web3/resolve?domain=stats.i2p"

Code Examples

Python

import requests

# Scan a domain
response = requests.post(
    'https://dnsscience.com/api/scan',
    json={'domain': 'example.com', 'check_ssl': True}
)

result = response.json()
print(f"DNSSEC Enabled: {result['dnssec_enabled']}")
print(f"SPF Valid: {result['spf_valid']}")

# Get domain history with authentication
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
response = requests.get(
    'https://dnsscience.com/api/domain/example.com/history',
    params={'limit': 10},
    headers=headers
)

history = response.json()
print(f"Found {history['count']} historical scans")

JavaScript (Node.js)

const axios = require('axios');

// Scan a domain
async function scanDomain(domain) {
  try {
    const response = await axios.post('https://dnsscience.com/api/scan', {
      domain: domain,
      check_ssl: true
    });

    console.log('DNSSEC Enabled:', response.data.dnssec_enabled);
    console.log('SPF Valid:', response.data.spf_valid);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

// Get domain history with authentication
async function getDomainHistory(domain) {
  try {
    const response = await axios.get(
      `https://dnsscience.com/api/domain/${domain}/history`,
      {
        params: { limit: 10 },
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      }
    );

    console.log(`Found ${response.data.count} historical scans`);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

scanDomain('example.com');

cURL

# Scan a domain
curl -X POST https://dnsscience.com/api/scan \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "check_ssl": true}'

# Get domain information
curl https://dnsscience.com/api/domain/example.com

# Search domains
curl "https://dnsscience.com/api/search?q=google"

# Get domain history (authenticated)
curl https://dnsscience.com/api/domain/example.com/history?limit=10 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Upload and validate DNS config (premium)
curl -X POST https://dnsscience.com/api/validate/dns-config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@named.conf" \
  -F "server_type=bind9"