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.

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.

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.

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. No new MCP tool or 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.