How It Works

You send one API call. ThreatMap fans out across 20+ sources in parallel, normalises the results into one schema, calculates a unified score, and returns one JSON. Here's what happens in those 500ms.

The flow

Your app ThreatMap Upstream sources
───────── ───────── ────────────────

POST /v1/ioc ──────────────► 1. Identify applicable
value="8.8.8.8" sources for this IOC type
(IP → AbuseIPDB, GreyNoise,
Shodan, Censys, VT, OTX...)

2. Check cache (Redis)
hit? → return cached (5ms)
miss? → continue

3. Fan out in parallel ──────► AbuseIPDB API
(Promise.allSettled) ──────► GreyNoise API
each call has its own ──────► Shodan API
timeout + circuit breaker ──► Censys API
► VirusTotal API
► OTX API
► + more

4. Collect results as they
arrive. Failed/timed-out
sources excluded (partial OK)

5. Normalise into one schema
- map fields
- reconcile scores
- merge enrichment (ASN, geo)

6. Calculate ThreatMap Score
weighted by source reliability

7. Cache result (15 min TTL)

◄────────────────────── return unified JSON
{
threatmap_score: 12,
sources: { abuseipdb: {...}, ... },
metadata: { latency_ms: 340 }
}

ThreatMap Score (0–100)

The score is a weighted average of every source's verdict. Sources are weighted by reliability:

Score range	Verdict	What it means
0–20	Clean	No malicious signals from any source
21–40	Suspicious	Some indicators, no strong consensus
41–70	Malicious	Multiple sources agree, active threat
71–100	Critical	High-confidence malicious, active campaign

Source weights are transparent — the sourcesobject in every response shows each source's contribution. Weights are reviewed quarterly.

Caching

Results are cached in three layers to reduce upstream costs and latency:

Layer	TTL	What
Edge (gateway)	1–5 sec	Burst protection — same query from 5 agents in 1 second = 1 upstream call
Application (Redis)	15–60 min	Per-provider responses. IOC reputation: 15 min. Passive DNS: 60 min. WHOIS: 24h.
Persistent (RelataDB)	18 months	Historical sightings — builds our own dataset over time

Enterprise can bypass cache with force_refresh=true.

BYOK routing

When you register a provider key via BYOK, ThreatMap routes calls to that provider through your key instead of ours. BYOK calls cost 0 credits.

Without BYOK:
  POST /v1/ioc → ThreatMap calls Shodan with OUR key → 2 credits

With BYOK (you registered your Shodan key):
  POST /v1/ioc → ThreatMap calls Shodan with YOUR key → 0 credits

BYOK also works for mixed routing — if you have a Shodan key but not a GreyNoise key, Shodan calls are free and GreyNoise calls use 2 credits.

Circuit breaker

Each upstream source has a circuit breaker. If a source fails repeatedly (5 consecutive errors or >50% error rate in 60 seconds), the circuit opens — calls to that source are short-circuited for 30 seconds. This prevents one slow provider from degrading the entire response.

Failed sources are excluded from the response (providers_failedin metadata) — you always get partial results.

MCP — how AI agents connect

The MCP server exposes every endpoint as a tool. Your AI agent (Claude, Cursor, Copilot) calls ThreatMap automatically when it encounters an IOC, CVE, or domain in conversation.

User: "Is 203.0.113.50 suspicious?"
       │
       ▼
Claude calls MCP tool: threatmap_ioc_lookup(value="203.0.113.50")
       │
       ▼
ThreatMap fans out → normalises → returns score: 87 (High)
       │
       ▼
Claude: "Yes — score 87/100. Known C2 node across 3 sources.
         Recommended action: block at perimeter."

Free tier uses a public read-only MCP server. Teams+ uses your API key for authed MCP. Enterprise gets per-team MCP endpoints with per-tool ACLs.