Threat intelligence API / Reference / Threats

Threats endpoints

Incident clusters: the deduplicated, scored record per story, with its articles, entities, IOCs and STIX export.

GET /search · GET /threats · GET /threats/{identifier} · GET /threats/{identifier}/iocs · GET /threats/{identifier}/stix

GET /search

Search clusters, entities and the dark web in one call · 5 credits per call

One query across the corpus. Case-insensitive substring match on cluster titles and summaries, entity names, and dark-web victims, groups, markets, breaches and underground sites. The same fan-out the site's search box uses.

Query parameters

q: Search term (min 2 characters)
limit: Max hits per bucket (default 10, max 20; free keys 10)
days: Only hits dated within the last N days (clusters, articles,

victims, breaches, underground). Default: no window. Free keys: 7.

include_articles: Also return individual articles whose title matches

(default false; clusters are the primary unit, articles are noisier)

Returns buckets: clusters (same shape as GET /threats, chain the short_id to /threats/{id}), entities (pass entity_type + entity_value to /entities/{type}/{value}), darkweb (typed hits: victim, group, market, breach, underground, underground_victim) and, on request, articles.

Results are most-recent first within each bucket.

Free keys: the window is fixed at 7 days and clusters are trimmed like /threats.

Parameters

Name	In	Type
q	query	string
limit	query	integer
days	query	integer
include_articles	query	boolean

Response 200 · SearchResponse

Field	Type	Meaning
query *	string
clusters	array of object	Clusters in the same shape as GET /threats
entities	array of SearchEntityHit
darkweb	array of SearchDarkwebHit
articles	array or null	Only present when include_articles=true
include_articles	boolean
limit *	integer
days	integer or null	Window applied, when one was (free keys: always 7)
total *	integer	Sum across the returned buckets
tier	string or null
lookback_days	integer or null

curl -H "X-API-Key: $TC_KEY" \
  "https://threatcluster.io/api/public/v1/search"

GET /threats

List threat clusters · 1 credit per call

Get threat clusters.

Query parameters

limit: Max results (default: 50, max: 100)
offset: Pagination offset
time_filter: 1h, 24h, 7d, 30d (default: 7d)
sort_by: trending, new (default: trending)
keyword: Optional keyword filter

Returns list of threat clusters with entities.

Parameters

Name	In	Type
limit	query	integer
offset	query	integer
time_filter	query	string
sort_by	query	string
keyword	query	string

Response 200 · ThreatsListResponse

Field	Type	Meaning
threats *	array of ThreatListItem
count	integer or null
total	integer or null
limit	integer or null
offset	integer or null

curl -H "X-API-Key: $TC_KEY" \
  "https://threatcluster.io/api/public/v1/threats"

GET /threats/{identifier}

Threat cluster detail · 1 credit per call

Get a single threat cluster by ID.

Path parameters

identifier: Full UUID or 8-char short ID

Returns threat cluster with articles and entities.

Parameters

Name	In	Type	Required	Meaning
identifier	path	string	yes

Response 200 · ThreatDetailResponse

Field	Type	Meaning
cluster_id *	string
title	string or null
ai_title	string or null
ai_summary	string or null
image_url	string or null
timeline	string or array or null
article_count	integer or null
threat_score	number or null
recency_score	number or null
coverage_score	number or null
severity_score	number or null
sentiment_score	number or null
geopolitical_score	number or null
actionability_score	number or null
severity_reason	string or null
credibility_score	number or null
urgency_level	string or null
ranking_score	number or null
keywords	array or null
sources	array or null
severity_indicators	array or null
date_range_earliest	string or null
date_range_latest	string or null
created_at	string or null
updated_at	string or null
recent_article_count_12h	integer or null
recent_article_count_6h	integer or null
insights_count	integer or null
articles	array or null
entities	object or null

curl -H "X-API-Key: $TC_KEY" \
  "https://threatcluster.io/api/public/v1/threats/{identifier}"

GET /threats/{identifier}/iocs

Threat cluster IOCs · 1 credit per call

Export IOCs from a threat cluster.

Path parameters

identifier: Cluster ID or short ID

Query parameters

types: Comma-separated (ip, domain, url, hash, email, all) - default: all
format: json, csv, txt (default: json)

Returns IOCs in requested format.

Parameters

Name	In	Type	Required
identifier	path	string	yes
types	query	string
format	query	string

Response 200 · ThreatIocsResponse

Field	Type	Meaning
iocs *	array of object	Each entry: {type, value, confidence, reason, ...}
count *	integer
cluster_id *	string

curl -H "X-API-Key: $TC_KEY" \
  "https://threatcluster.io/api/public/v1/threats/{identifier}/iocs"

GET /threats/{identifier}/stix

Threat cluster as STIX 2.1 bundle · 3 credits per call

Export threat cluster to STIX 2.1 format.

Path parameters

identifier: Cluster ID (full UUID or short ID)

Query parameters

tlp: TLP marking (white, green, amber, red) - default: white

Returns STIX 2.1 bundle with threat actors, malware, attack patterns, and indicators.

Parameters

Name	In	Type	Required	Meaning
identifier	path	string	yes
tlp	query	string

curl -H "X-API-Key: $TC_KEY" \
  "https://threatcluster.io/api/public/v1/threats/{identifier}/stix"