Whisper

<h2>The Foundational Intelligence Layer for the Internet</h2>
<p>The Whisper API provides comprehensive, real-time intelligence on any internet asset. By connecting billions of data points across live internet routing, historical registration records, and deep resolution data, our API moves beyond simple enrichment to deliver predictive, context-rich insights.</p>
<p>This document is the single source of truth for our v1 API. It is designed for security experts, developers, and automated systems to understand and leverage the full power of our platform.</p>

<h3>🚀 Quick Start</h3>
<p><b>1. Get your API key:</b> <a href="https://dash.whisper.security">Sign up at dash.whisper.security</a></p>
<p><b>2. Make your first request:</b></p>
<pre><code>curl -H "Authorization: Bearer YOUR_API_KEY" https://api.whisper.security/v1/indicators/ip/8.8.8.8</code></pre>
<p><b>3. Explore the API:</b> Use the "Try it out" button in each endpoint below to test interactively.</p>

<h3>🎯 Key Features</h3>
<ul>
    <li><b>Unified & Simple:</b> Small set of powerful, resource-oriented endpoints</li>
    <li><b>Performant by Design:</b> Asynchronous-first with strategic caching (&lt;500ms typical response)</li>
    <li><b>Workflow-Oriented:</b> Built for real-world security operations, not just data dumps</li>
    <li><b>Comprehensive:</b> IP, Domain, DNS, WHOIS, Routing, Geolocation, Screenshots, Monitoring</li>
</ul>

<h3>⚡ Performance Targets</h3>
<table>
    <tr><th>Endpoint Type</th><th>Response Time</th><th>Use Case</th></tr>
    <tr><td>Geolocation</td><td>&lt;150ms</td><td>Real-time fraud detection</td></tr>
    <tr><td>Single Indicator</td><td>&lt;500ms</td><td>Incident response enrichment</td></tr>
    <tr><td>With Routing Data</td><td>&lt;2s (cached: 200ms)</td><td>Deep network analysis</td></tr>
    <tr><td>Bulk Operations</td><td>5-30s</td><td>Batch log enrichment</td></tr>
    <tr><td>Search/Discovery</td><td>10-60s</td><td>Threat hunting</td></tr>
</table>

<h3>🔐 Authentication</h3>
<p>All endpoints require Bearer token authentication. Click the <b>"Authorize"</b> button above and enter your API key.</p>
<pre><code>Authorization: Bearer wsk_live_1234567890abcdef</code></pre>

<h3>📊 Rate Limits</h3>
<table>
    <tr><th>Category</th><th>Limit</th></tr>
    <tr><td>Standard Enrichment</td><td>100 req/min</td></tr>
    <tr><td>Bulk Operations</td><td>10 req/min</td></tr>
    <tr><td>Search/Discovery</td><td>5 req/min</td></tr>
    <tr><td>Screenshots</td><td>10 req/min</td></tr>
</table>
<p><i>Rate limits return HTTP 429. Retry after the time specified in the <code>Retry-After</code> header.</i></p>

<h3>📚 Resources</h3>
<ul>
    <li><a href="https://docs.whisper.security">Full Documentation</a></li>
    <li><a href="https://docs.whisper.security/quickstart">Quick Start Guide</a></li>
    <li><a href="https://docs.whisper.security/examples">Code Examples</a></li>
    <li><a href="https://whisper.security/support">API Support</a></li>
</ul>


Whisper API v1

Operational security tools for active analysis and monitoring. Includes screenshots, infrastructure scanning, and asynchronous job tracking. Most endpoints are async and return a jobId for status polling.

Operations

<p>Generates potential lookalike, typosquatting, and homoglyph domains for brand protection and threat hunting.</p>
<h4>Detection Methods:</h4>
<ul>
    <li>Typosquatting (keyboard proximity)</li>
    <li>Homoglyph attacks (visually similar characters)</li>
    <li>Combosquatting (brand + keyword)</li>
    <li>TLD variations</li>
</ul>
<h4>Performance:</h4>
<p>Typically completes in 5-15 seconds depending on options.</p>


Find Similar Domains (Asynchronous)

<p>Initiates an asynchronous job to capture a screenshot of a website. Supports various viewport sizes, full-page captures, and JavaScript rendering.</p>
<p><b>Performance Note:</b> A typical screenshot capture takes 10-30 seconds. Poll the `/v1/ops/jobs/{jobId}` endpoint to retrieve the URL of the final image.</p>
<p><b>Output:</b> The job result will contain a URL to download the screenshot image in the specified format (PNG, JPEG, or WebP).</p>


Capture a Website Screenshot (Asynchronous)

<p>Create a recurring job to capture website screenshots at regular intervals. Essential for monitoring website changes, detecting defacements, and tracking competitor updates.</p>
<h4>Schedule Options:</h4>
<ul>
    <li><b>Cron Expression:</b> Full cron syntax support (e.g., `0 0 * * * *` = hourly)</li>
    <li><b>Frequency Presets:</b> hourly, daily, weekly, monthly</li>
    <li><b>Timezone:</b> Specify timezone for accurate scheduling</li>
    <li><b>Retention:</b> Auto-cleanup old screenshots (default: keep last 30)</li>
</ul>
<h4>Performance:</h4>
<ul>
    <li><b>Setup Time:</b> ~2 seconds to create schedule</li>
    <li><b>Screenshot Time:</b> 10-30 seconds per capture</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Automated defacement detection</li>
    <li>Compliance monitoring and archival</li>
    <li>Competitor website tracking</li>
    <li>Visual regression testing</li>
</ul>


Schedule Recurring Screenshots (Asynchronous)

<p>Initiates a comprehensive security scan of a domain's infrastructure. Performs reconnaissance, port scanning, service detection, and vulnerability assessment.</p>
<h4>Scan Types:</h4>
<ul>
    <li><b>comprehensive:</b> Full scan including all modules (recommended for complete assessment)</li>
    <li><b>subdomains:</b> Subdomain enumeration only</li>
    <li><b>ports:</b> Port scanning and service detection</li>
    <li><b>technologies:</b> Technology stack detection</li>
    <li><b>vulnerabilities:</b> Known vulnerability checks</li>
    <li><b>ssl:</b> SSL/TLS configuration and certificate analysis</li>
    <li><b>dns:</b> DNS configuration and zone transfer tests</li>
    <li><b>whois:</b> Registration and ownership information</li>
</ul>
<h4>Performance:</h4>
<ul>
    <li><b>Quick scans:</b> 30-60 seconds (subdomains, dns, whois)</li>
    <li><b>Comprehensive scan:</b> 5-15 minutes depending on infrastructure size</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Pre-engagement reconnaissance for penetration testing</li>
    <li>Attack surface assessment</li>
    <li>Infrastructure inventory and mapping</li>
    <li>Vulnerability management</li>
</ul>


Infrastructure Security Scan (Asynchronous)

<p>Create alert rules for a monitored asset. Get notified via webhook, email, or Slack when specific conditions are met.</p>
<h4>Alert Types:</h4>
<ul>
    <li><b>downtime:</b> Site becomes unreachable</li>
    <li><b>dns_change:</b> DNS records modified</li>
    <li><b>whois_change:</b> Registration details updated</li>
    <li><b>ssl_expiring:</b> Certificate expires soon (7, 14, 30 days)</li>
    <li><b>content_change:</b> Page content modified</li>
    <li><b>technology_change:</b> Tech stack changes detected</li>
</ul>
<h4>Notification Channels:</h4>
<ul>
    <li>Webhook (POST to your endpoint)</li>
    <li>Email</li>
    <li>Slack</li>
    <li>PagerDuty</li>
</ul>
<h4>Example Configuration:</h4>
<pre><code>{
  "type": "ssl_expiring",
  "threshold_days": 14,
  "channels": ["email", "slack"],
  "email": "alerts@example.com",
  "slack_webhook": "https://hooks.slack.com/..."
}</code></pre>


Configure Monitoring Alerts (Asynchronous)

<p>Creates a comprehensive map of infrastructure relationships starting from a domain or IP. Discovers connected assets through shared hosting, DNS, certificates, and network relationships.</p>
<h4>Mapping Depth Levels:</h4>
<ul>
    <li><b>Depth 1:</b> Direct relationships only (~30 seconds, 10-50 assets)</li>
    <li><b>Depth 2:</b> 2 hops out (~2-5 minutes, 50-500 assets)</li>
    <li><b>Depth 3:</b> 3 hops out (~10-30 minutes, 500-5000 assets)</li>
</ul>
<h4>Relationship Types Discovered:</h4>
<ul>
    <li>Domains on same IP</li>
    <li>Domains sharing nameservers</li>
    <li>Domains with same SSL certificate</li>
    <li>IPs in same ASN</li>
    <li>Domains with same registrant</li>
</ul>
<h4>Output Format:</h4>
<p>Results returned as graph data compatible with visualization libraries (nodes and edges).</p>
<h4>Use Cases:</h4>
<ul>
    <li>Threat actor infrastructure mapping</li>
    <li>Discovering related phishing domains</li>
    <li>Finding shadow IT and forgotten assets</li>
</ul>


Map Infrastructure Relationships (Asynchronous)

<p>Retrieve all previously captured screenshots for a specific URL, ordered by capture time (newest first). Includes download URLs and metadata for each capture.</p>
<h4>Response Includes:</h4>
<ul>
    <li><b>Download URL:</b> Direct link to screenshot image</li>
    <li><b>Capture Time:</b> Timestamp when screenshot was taken</li>
    <li><b>Dimensions:</b> Image width and height</li>
    <li><b>Format:</b> Image format (PNG, JPEG, WebP)</li>
    <li><b>File Size:</b> Size in bytes</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Review website evolution over time</li>
    <li>Compare screenshots for change detection</li>
    <li>Download historical screenshots for reporting</li>
</ul>


Get Screenshot History

<p>Retrieves current monitoring configuration and historical metrics for a domain or IP address.</p>
<h4>Status Information:</h4>
<ul>
    <li><b>Monitoring State:</b> Active, paused, or not monitored</li>
    <li><b>Check Frequency:</b> How often checks are performed</li>
    <li><b>Active Alerts:</b> Currently triggered alert conditions</li>
    <li><b>Last Check:</b> Timestamp of most recent check</li>
</ul>
<h4>Metrics Included:</h4>
<ul>
    <li>Uptime percentage (last 30 days)</li>
    <li>Average response time</li>
    <li>SSL certificate expiration countdown</li>
    <li>DNS change events</li>
    <li>WHOIS change events</li>
</ul>


Get Monitoring Status and Metrics

<p>Retrieves the current status and results of an asynchronous job. Poll this endpoint to check job progress.</p>
<h4>Polling Recommendations:</h4>
<ul>
    <li>For fast jobs (e.g., similar domains), poll every 1-2 seconds.</li>
    <li>For slow jobs (e.g., WHOIS search, screenshots), poll every 5-10 seconds.</li>
    <li>Implement an exponential backoff strategy for very long-running jobs.</li>
    <li>Stop polling when the status is `COMPLETED`, `FAILED`, or `CANCELLED`.</li>
</ul>
<h4>Job Statuses:</h4>
<ul>
    <li><b>PENDING:</b> Job is queued and waiting to start.</li>
    <li><b>PROCESSING:</b> Job is actively being processed.</li>
    <li><b>COMPLETED:</b> Job finished successfully, results are available.</li>
    <li><b>FAILED:</b> Job failed with an error.</li>
    <li><b>CANCELLED:</b> Job was cancelled by user or system.</li>
</ul>


Get Asynchronous Job Status and Results

<p>Retrieves a list of recent jobs for the authenticated user, optionally filtered by status.</p>
<h4>Query Parameters:</h4>
<ul>
    <li><b>status:</b> Filter by job status (PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED)</li>
    <li><b>limit:</b> Maximum number of jobs to return (default: 50, max: 100)</li>
    <li><b>offset:</b> Number of jobs to skip for pagination (default: 0)</li>
</ul>
<h4>Response Format:</h4>
<p>Returns a JSON object with a "jobs" array containing job summaries.</p>


List Recent Jobs

<p>Retrieves detected changes in infrastructure configuration for a domain or IP over time. Essential for security monitoring and compliance auditing.</p>
<h4>Change Types Tracked:</h4>
<ul>
    <li><b>dns:</b> A, AAAA, MX, NS, TXT record changes</li>
    <li><b>whois:</b> Registrant, registrar, nameserver changes</li>
    <li><b>ssl:</b> Certificate replacements and expirations</li>
    <li><b>ip:</b> IP address changes for domains</li>
    <li><b>content:</b> Homepage content modifications</li>
    <li><b>technology:</b> Tech stack changes</li>
</ul>
<h4>Response Format:</h4>
<p>Timeline of changes with before/after values:</p>
<pre><code>{
  "changes": [
    {
      "timestamp": "2025-01-15T10:30:00Z",
      "type": "dns",
      "field": "A_RECORD",
      "old_value": "8.8.8.8",
      "new_value": "1.1.1.1"
    }
  ]
}</code></pre>
<h4>Use Cases:</h4>
<ul>
    <li>Security incident investigation</li>
    <li>Compliance and audit trails</li>
    <li>Detecting unauthorized changes</li>
    <li>Infrastructure change management</li>
</ul>


Get Infrastructure Change History

High-performance geolocation and ASN intelligence for IP addresses and networks. Essential for fraud detection, access control, and threat analysis. All endpoints are optimized for sub-200ms response times.

Location

<p>Retrieve geolocation data for up to 1000 IP addresses in a single request. Optimized for batch processing with parallel lookups.</p>
<h4>Request Format:</h4>
<p>Send a JSON array of IP addresses (IPv4 or IPv6):</p>
<pre><code>["8.8.8.8", "1.1.1.1", "208.67.222.222"]</code></pre>
<h4>Performance:</h4>
<ul>
    <li><b>Response Time:</b> 500-2000ms for typical batches (10-100 IPs)</li>
    <li><b>Processing:</b> Parallel lookups with automatic batching</li>
    <li><b>Limit:</b> Maximum 1000 IPs per request</li>
    <li><b>Rate Limit:</b> 10 requests per minute</li>
</ul>
<h4>Response Format:</h4>
<p>Returns an array of geolocation objects matching the order of input IPs. Failed lookups are indicated with error objects.</p>
<h4>Use Cases:</h4>
<ul>
    <li>Batch enrichment of access logs</li>
    <li>Bulk fraud scoring</li>
    <li>Geographic distribution analysis</li>
    <li>Network infrastructure mapping</li>
</ul>


Bulk IP Geolocation Lookup

<p>Returns metadata and statistics about the geolocation database, including coverage, update frequency, and data quality metrics.</p>
<h4>Statistics Included:</h4>
<ul>
    <li><b>Coverage:</b> Total IP addresses, networks, and ASNs covered</li>
    <li><b>Geographic:</b> Number of countries, cities, and regions</li>
    <li><b>Freshness:</b> Last update timestamp and update frequency</li>
    <li><b>Data Sources:</b> Providers and data collection methods</li>
    <li><b>Accuracy:</b> Quality metrics and confidence scores</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Verifying database coverage for your use case</li>
    <li>Monitoring data freshness</li>
    <li>Understanding data quality and accuracy</li>
</ul>


Get Geolocation Database Statistics

<p>Search the geolocation database by specific fields to find all IP addresses matching your criteria. Powerful for threat hunting, infrastructure discovery, and pattern analysis.</p>
<h4>Searchable Fields:</h4>
<ul>
    <li><b>Geographic:</b> city, country, country_code, region, postal_code, continent, continent_code</li>
    <li><b>Network:</b> asn, as_number, organization, isp, isp_name</li>
    <li><b>Coordinates:</b> latitude, longitude</li>
</ul>
<h4>Query Examples:</h4>
<ul>
    <li><b>Find all IPs in a city:</b> field=city&value=London</li>
    <li><b>Find all IPs for an ASN:</b> field=asn&value=15169</li>
    <li><b>Find all IPs for an ISP:</b> field=isp_name&value=Google</li>
    <li><b>Find all IPs in country:</b> field=country_code&value=US</li>
</ul>
<h4>Performance:</h4>
<ul>
    <li><b>Response Time:</b> 200-500ms depending on result size</li>
    <li><b>Rate Limit:</b> 5 searches per minute</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Infrastructure mapping for threat actors</li>
    <li>Finding all IPs in a specific region for compliance</li>
    <li>Discovering VPN/proxy exit nodes</li>
    <li>Threat hunting by ISP or ASN</li>
</ul>


Search Geolocation Database by Field

<p>Returns geolocation and network information for an entire network range specified in CIDR notation. Useful for analyzing network blocks, ranges, and subnets.</p>
<h4>Supported Formats:</h4>
<ul>
    <li><b>IPv4 CIDR:</b> 192.168.1.0/24</li>
    <li><b>IPv6 CIDR:</b> 2001:db8::/32</li>
</ul>
<h4>Data Included:</h4>
<ul>
    <li><b>Network Details:</b> CIDR range, first/last IP, total addresses</li>
    <li><b>Geographic:</b> Country, city, region for the network block</li>
    <li><b>Network:</b> ASN, organization, ISP information</li>
    <li><b>Classification:</b> Network type and usage category</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Analyzing suspicious network ranges</li>
    <li>Bulk geolocation for network blocks</li>
    <li>Infrastructure mapping and reconnaissance</li>
</ul>


Get Network/CIDR Geolocation Data

<p>Returns comprehensive geolocation and network information for any IPv4 or IPv6 address. This is one of the fastest endpoints in the API, optimized for real-time fraud detection and access control.</p>
<h4>Data Included:</h4>
<ul>
    <li><b>Geographic:</b> Country, city, region, postal code, coordinates, timezone</li>
    <li><b>Network:</b> ASN, ISP/organization name, network range</li>
    <li><b>Classification:</b> Connection type (residential, datacenter, VPN, proxy, hosting)</li>
    <li><b>Reputation:</b> Risk indicators and abuse scores</li>
</ul>
<h4>Performance:</h4>
<ul>
    <li><b>Response Time:</b> Typically &lt;150ms</li>
    <li><b>Cache:</b> Results cached for 6 hours by default</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Real-time fraud detection in payment flows</li>
    <li>Geographic access control and compliance</li>
    <li>Bot and VPN detection</li>
    <li>Threat intelligence enrichment</li>
</ul>


Get IP Geolocation and ASN Data

The core of the Whisper API. This family provides comprehensive threat intelligence and enrichment for foundational internet assets like IP addresses and domains. It's designed for rapid investigation, incident response, and proactive threat hunting.

Indicators

<p>Initiates an asynchronous job to search for indicators matching specific criteria. This endpoint is extremely powerful for infrastructure discovery and threat hunting.</p>
<p><b>Performance Note:</b> Searches on WHOIS fields (like `registrantCompany`) are data-intensive and can take over 50 seconds to complete. This endpoint is therefore asynchronous by design. Poll the `/v1/ops/jobs/{jobId}` endpoint to retrieve results.</p>
<h4>Example Search Queries:</h4>
<ul>
    <li>`registrantCompany:EvilCorp` - Find all domains registered by EvilCorp</li>
    <li>`asn:15169` - Find all IPs in Google's ASN</li>
    <li>`city:"San Francisco"` - Find all IPs geolocated to San Francisco</li>
</ul>


Search Indicators (Asynchronous)

<p>Initiates an asynchronous job to generate potential lookalike domains using default options. This GET variant is provided for convenience.</p>
<p>For custom options (algorithms, limits, etc.), use the POST version of this endpoint.</p>
<p>The API immediately returns a `jobId`. Poll the `/v1/ops/jobs/{jobId}` endpoint to get the results when complete.</p>


Generate Similar Domains - GET (Asynchronous)

<p>Initiates an asynchronous job to generate potential lookalike domains for typosquatting, homoglyph, and brand protection analysis. This is a powerful tool for proactive threat hunting.</p>
<p>Because this can be a long-running process, the API immediately returns a `jobId`. Poll the `/v1/ops/jobs/{jobId}` endpoint to get the results when the job is complete.</p>
<p>Use this POST version to specify custom options like algorithms, limits, or filters.</p>


Generate Similar Domains - POST (Asynchronous)

<p>Process multiple indicators (IPs and/or domains) in a single request. This endpoint is optimized for batch processing and can handle up to 100 indicators per request.</p>
<p><b>Performance:</b> Processing time depends on batch size and requested data modules. Expect 5-30 seconds for typical batches.</p>
<p><b>Rate Limits:</b> Limited to 10 requests per minute due to the resource-intensive nature of bulk operations.</p>


Bulk Indicator Enrichment (Asynchronous)

<p>Retrieves comprehensive intelligence for a single IP address or domain. This is the primary, high-performance endpoint for synchronous enrichment.</p>
<p>It aggregates data from multiple sources, including geolocation, WHOIS, DNS, reputation scoring, and relationship mapping. Use the `include` parameter to request additional, deeper data sets that may have higher latency.</p>
<h4>Performance:</h4>
<ul>
    <li><b>Base Response:</b> Typically under 500ms.</li>
    <li><b>With `include=routing`:</b> First request may take up to 5 seconds; subsequent requests are cached for 5 minutes and respond in &lt;200ms.</li>
    <li><b>With `include=ip_intelligence`:</b> Adds 200-500ms of latency for each IP address resolved from the domain.</li>
</ul>


Enrich a Single Indicator (IP or Domain)

<p>Retrieves time-series historical data for an IP address or domain. Track how infrastructure changes over time for threat intelligence and forensic analysis.</p>
<h4>History Types:</h4>
<ul>
    <li><b>whois:</b> Registration history - registrant changes, expiration updates, transfers</li>
    <li><b>routing:</b> BGP routing history - prefix announcements, ASN changes, route hijacks</li>
    <li><b>dns:</b> DNS resolution history - IP address changes, nameserver updates</li>
    <li><b>ssl:</b> Certificate history - cert replacements, CA changes, expiration events</li>
    <li><b>reputation:</b> Risk score history - blacklist appearances, reputation changes</li>
</ul>
<h4>Data Format:</h4>
<p>Timeline with dated snapshots showing what changed and when:</p>
<pre><code>{
  "history": [
    {
      "timestamp": "2025-01-15T10:00:00Z",
      "field": "registrant_company",
      "old_value": "Evil Corp",
      "new_value": "Legitimate LLC"
    }
  ]
}</code></pre>
<h4>Use Cases:</h4>
<ul>
    <li>Tracking domain ownership changes</li>
    <li>Investigating IP reputation degradation</li>
    <li>Forensic timeline reconstruction</li>
    <li>Detecting infrastructure pivots by threat actors</li>
</ul>


Get Historical Data for Indicator

<p>Returns graph visualization data showing relationships between the indicator and related infrastructure. Perfect for interactive network diagrams and threat actor infrastructure mapping.</p>
<h4>Relationship Types Included:</h4>
<ul>
    <li><b>For Domains:</b>
        <ul>
            <li>Resolves to IPs</li>
            <li>Shares nameservers with</li>
            <li>Same SSL certificate as</li>
            <li>Same registrant as</li>
            <li>Links to/from other domains</li>
        </ul>
    </li>
    <li><b>For IPs:</b>
        <ul>
            <li>Hosts domains</li>
            <li>Same ASN as</li>
            <li>Same network block as</li>
            <li>Connected via routing</li>
        </ul>
    </li>
</ul>
<h4>Output Format:</h4>
<p>Compatible with react-force-graph, vis.js, cytoscape.js:</p>
<pre><code>{
  "nodes": [
    {"id": "example.com", "type": "domain", "label": "example.com"},
    {"id": "8.8.8.8", "type": "ip", "label": "8.8.8.8"}
  ],
  "links": [
    {"source": "example.com", "target": "8.8.8.8", "type": "resolves_to"}
  ]
}</code></pre>
<h4>Performance:</h4>
<ul>
    <li>Response Time: 500ms-2s depending on graph complexity</li>
    <li>Default: 100 nodes maximum (adjustable)</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Interactive threat actor infrastructure visualization</li>
    <li>Discovering related phishing campaigns</li>
    <li>Mapping shadow IT and sprawl</li>
    <li>Network topology visualization</li>
</ul>


Get Infrastructure Relationship Graph

Retrieves a list of discovered subdomains for a given root domain, based on passive DNS and other enumeration techniques.

Sections

Ask an AI

Code with AI