API reference

Use https://threatmap.co/api/v1 with a Bearer API key./v1/* is a rewrite alias. JSON POST requests requireContent-Type: application/json. Account verification, scope, plan, credits, and provider configuration apply.

{
  "value": "8.8.8.8"
}

Enrichment and intelligence

Profiles and detection rules require administrator catalog imports. Runtime reads only RelataDB; unavailable catalogs return a service error. Vulnerability profiles cover CISA KEV, not the full NVD universe.

The Detections portal offers explicit draft translation of a supplied Sigma subset using a destination field schema and fixed Splunk SPL or Microsoft Kusto template. No event records are required. Unsupported logic is blocked and unresolved mappings require confirmation. Native SIEM validation is not performed; every draft requires review. This Teams/Enterprise portal operation costs zero customer credits in phase one. Public /convert and MCP conversion remain deterministic.

POST /attack operations attack_coverage and attack_gaps accept an optional entity_id (ATT&CK group/software or CVE) or target_ids. They return exact rule mappings, gaps, provenance and a Navigator layer. CVE mappings without attributable evidence are unavailable. Library mappings do not measure deployed detection effectiveness.

• POST /api/v1/ioc (alias /v1/ioc): JSON value, for example {"value":"8.8.8.8"}. One IOC only, up to 2,048 characters; no arrays or comma-separated lists.
• POST /cve: JSON id, for example {"id":"CVE-2024-3094"}.
• POST /actor: name, id, or query.
• GET /profiles: type (actors, malware, vulns), q, tactic, product, limit, and offset. GET /profiles/{type}/{id} returns detail.
• POST /feed: feed or name; limit defaults to 50 and is bounded to 1–500.
• POST /attack: operation plus operation-specific fields for the imported MITRE Enterprise ATT&CK catalog in RelataDB. Technique and coverage results carry source/version metadata; supplied IDs do not prove detection quality.
• POST /cve-discovery: operation search_cves orget_cve_references. NVD keyword, CVSS v3 severity, and bounded publication-date search are supported. Upstream failures are explicit.
• POST /cvss: explain a full CVSS v3.1 base vector. Base severity is not an organization-specific risk score.
• POST /breaches: public HIBP breach catalog operations only; these do not check whether an account was exposed.

IOC/CVE source objects also expose public evidence: NVD CVSS vectors and CWE IDs, Shodan open ports and service summaries, HIBP breach dates and data categories, and GreyNoise observation tags/CVEs. HIBP domain results describe breached sites, not accounts at that domain. Raw banners, breach HTML, credentials and cookies are omitted. Unknown GreyNoise observations and missing NVD severity have no reputation score; absence of evidence is not a clean verdict. Provider availability still depends on configuration and entitlement.

SOC triage

• POST /api/v1/extract: JSON text, for example {"text":"8.8.8.8 evil.example"}. Extracts IPv4, IPv6, domain, URL, MD5/SHA-1/SHA-256 hash, and CVE indicators locally from pasted text; no enrichment and no credit charge. Text is capped at 100,000 characters. Email addresses are not returned as an indicator type.
• POST /api/v1/triage: JSON observables, for example {"observables":["8.8.8.8"]}. Triages 1–20 observables (IPs, domains, URLs, hashes, emails, CVEs) and returns a verdict, score, and source reasons per observable plus an overall verdict. One credit is charged per successfully enriched observable.
• POST /api/v1/email-headers: JSON headers, for example {"headers":"From: a@example.com"}. Parses the Received chain and Authentication-Results and reports SPF/DKIM/DMARC results with From-domain alignment findings. Header text is untrusted input, no DNS is resolved, and no credits are charged.

Relationships and pivots

POST /graph takes start and optional hops (1–5, default 3). It returns query, graph nodes/edges, and metadata. The portal can derive a graph from existing lookup sources. Standalone provider traversal reserves one credit regardless of hop count; derived execution has no base graph reservation.

Infrastructure routes include /dns, /certificates,/whois, /trackers, /host-pairs, and/pivots. Inputs differ by pivot; MCP discovery exposes schemas for DNS and certificate tools. Do not assume every pivot accepts identical fields.

POST /live-dns supports live record, reverse PTR, bounded static SPF chain, common SRV, wildcard-probe, and email-policy checks. SPF chain is not a sender verdict. Per-record resolver errors differ from no record; wildcard detection is heuristic and email policy has no risk score.POST /routing uses RIPE NCC RIS for observed ASN, IP, and prefix routing with its query time/window. Both require an operation field.

POST /exploit-evidence returns bounded ExploitDB records for one CVE. Passive HackerTarget host search, reverse-IP and single-IP ASN operations are available through /api/v1/hackertarget with operation, value and optional limit (1–50). These reference calls use zero ThreatMap credits and remain subject to provider quotas. SecurityTrails subdomain, A/AAAA DNS-history, and current WHOIS operations require a caller-owned key with provider access; missing keys or permission failures remain explicitly unavailable. Provider failures are distinct from an empty result.

CVE portfolios

POST /cve/prioritize accepts rows with CVE ID, optional asset context, exposure and normalized observations. Ranking is free; explicit enrichment requires an Idempotency-Key and returns 202 with a job polling URL. It charges one credit per successful fresh distinct CVE, including BYOK, and refunds unused reservations. Quick/deep depth does not change the price. Input is limited to 2 MiB and the current plan ceiling of 50, 300 or 1,000 rows/CVEs, subject to lookup and project policy.

GET /vulnerability-jobs/[id] returns up to 100 rows per page; offset selects the next page and format=csv exports a completed or partial page. DELETE requests cancellation with a read-write key or session CSRF. The same actor, project and key remain required. Private payloads expire after at most 24 hours; financial replay identity remains, so expiry never creates a second charge. The existing CVE endpoint and MCP cve_check still accept one ID.

GET /assets/vulnerabilities lists stored asset vulnerability intervals in the caller's project scope, optionally for one asset_id;cursor pages the asset catalog and offset pages one asset's findings (an offset requires asset_id).GET /cve/kev-changes lists persisted watched-CVE changes, with an optional ISO 8601 since filter on the stored creation time and alimit of 1–200 (default 100).POST /package-vulns looks up one package via OSV from apurl, or an ecosystem and name with an optional version; an omitted version stays unpinned and is never guessed, and the lookup charges zero credits. The MCP toolsasset_vulns, kev_changes, and package_vulnsproxy these routes, alongside vuln_prioritise (rank-only synchronous ranking; enrich-mode job polling is not built in),sbom_vulns (an inline SBOM document capped at 512 KiB), andpatch_advice (a fixed version only when the CVE data literally states one).

Rules, detection, and scanning

• GET/POST /rules: q/query, format, page, and limit.
• POST /convert: rule or rule_id, source/from, target/to.
• POST /detect: events with a supported rule/rule_id.
• POST /yara/scan: supported YARA scan input; use the tool schema.
• POST /scan: target, value, or ip; requires enabled scanning/provider configuration.
• POST /detonate: url, hash, or value. Arbitrary multipart file upload is not supported.

Account resources and MCP

The deprecated /api/watches API and its/phishing-domains, /code-leaks,/supply-chain, and /packages children return HTTP 501 NOT_IMPLEMENTED for GET and POST. These routes read and write no watch records. Use the supported monitor operations at/api/portal/monitors.

Projects and monitors have authenticated collection/item APIs. Portal APIs support UI operations. Manual portal monitor checks return 202 with a run ID; evaluation completes asynchronously. Settings password changes require a browser session, CSRF, current password, and valid replacement password.

Saved IOC lookups can open the monitor review form with their original project and indicator. Saving rechecks access; the monitor starts with a fresh scheduled observation.

/api/mcp accepts JSON-RPC POST. Initialize/ping may be public; tool discovery and execution require authorization. GET returns metadata, not an SSE subscription. See both MCP configurations.

MCP tool calls accept response shaping: preset (minimal, standard, or full), format (json, text, or csv), and limit with an opaque cursor. Pagination is in-memory and exactly-once — later pages reuse the first fetch without another charge. Standard-preset text is capped at 16 KB. Use get_related for typed relationships; dns_pivot and cert_search are deprecated aliases. search_tools and describe_tool search the visible tool catalog locally at no credit cost.

SOC triage MCP tools: extract_iocs extracts indicators from pasted text via /api/v1/extract at no credit cost, triage_observables triages up to 20 observables via /api/v1/triage at one credit per successfully enriched observable, and email_header_analysis analyses pasted email headers via /api/v1/email-headers at no credit cost. Extracted and parsed values are untrusted text from the supplied input.

MCP exposure tools (TM-243): domain_breach_exposure, credential_exposure, and lookalike_domains each take one verified domain_id and proxy the REST exposure routes below. The ownership gate and masking are identical to REST (REQ-017 item 11, ADR-044): only a currently verified domain owned by your project returns a report, mailbox local parts stay masked for every viewer, and no credential material is ever returned. lookalike_domains starts discovery and returns the job response without polling.

MCP prompts (TM-244): both transports serve five playbooks — soc_triage_alert, phishing_email_triage, weekly_vuln_report, brand_exposure_review, and threat_actor_brief. prompts/list shows only playbooks whose required tools your plan and project can use; prompts/get renders the playbook text after validating its arguments (4,000-character cap per string). Prompts execute no tool and charge no credits, and every playbook states that tool output is untrusted data, never instructions.

Ransomware leak-site exposure (TM-251): POST /api/v1/ransomware-exposure and the MCP tool ransomware_exposure search ransomware.live victims by company or supplier name or domain, or by sector plus country. Each match explains its field and kind (exact_domain, name_exact, name_fuzzy, sector_country). Without a ransomware.live key the response is an explicit not_configured state at no credit cost; victim data is attributed to ransomware.live.

Domain ownership

Manage exact domain DNS proof in /portal/exposure. Portal GET/POST/api/portal/exposure/domains, GET/DELETE of its domain ID, and POST/challenge or /verify require a verified session and current project authority; mutations require CSRF. Challenges last 24 hours and are shown only when created or regenerated. Ownership is verified once, with explicit removal and administrator suspension. Proof does not activate a source subscription or grant paid exposure reports.

Masked domain exposure

Teams and Enterprise can POST /api/v1/exposure/breaches or /stealers with a verified project domain_id and supported stored credential scopes. Source rights and HIBP enrollment are additional prerequisites. Private BYOK cannot serve a shared team scope. Read-only keys may generate these intelligence reports; deletion and recovery require mutation authority.

One new useful or valid-empty report costs one credit. Failed-only attempts cost zero. Saved views, masked JSON/CSV exports and observed-completion recovery do not reserve again. Every response rechecks current proof, credentials, policy, deletion and expiry. All mailbox local parts remain masked for owners too. Missing source coverage remains unknown.

GET /api/v1/exposure/reports lists summaries and pending IDs. Individual reports support get, export, privileged deletion and POST /recover. Provider DNS enrollment is separate from ThreatMap ownership. Generation is also available through the MCP exposure tools above with identical checks; no activated vendor subscription is implied.

Lookalike discovery

Teams and Enterprise can POST /api/v1/exposure/lookalikes with a verified project domain_id. Discovery runs the pinned OpenSquat CLI (416c2dd72f0e7867a326d2907450b9c4a0375e5a) in an isolated bounded worker against the operator-provided feed only; ThreatMap generates no permutations. One successful or valid-empty job costs one credit; failed jobs cost zero. GET /api/v1/exposure/lookalikes lists summaries, pending IDs and the operator gate. Individual jobs support get and JSON/CSV export. An unconfigured feed or runtime returns an explicit state, never an empty success. Operators configure OPENSQUAT_ENABLED, OPENSQUAT_FEED_PATH with OPENSQUAT_FEED_LICENSED=1, and OPENSQUAT_CLI_PATH; absence stays not_configured.

Response and error interpretation

Responses are endpoint-specific. IOC responses include query, sources, enrichment, and metadata. Inspect failed/skipped providers and credits_used; a partial response does not mean every provider succeeded. Structured error paths use Problem Details. 401 indicates credentials, 403 authorization or verification, 402 exhausted credits, and 429 rate limits.

AI, ASM/posture, tenant provisioning/branding, and batch IOC/CVE APIs are not part of the implemented interface. Account export/deletion acknowledgement routes do not perform a complete export or persisted deletion.