As the owner, you can use this endpoint to add elements such as IoCs, Attack Techniques and other associations to any of your threat objects, including: Threat Actor, Campaign, Malware Family, Software or Toolkit, IoC Collection.
This endpoint currently supports IoC Collections only. All other object types are in Private Preview.
Commonly used relationships are listed below. For a full specification, refer to the Relationships section within the object definition.
associations: it allows you to associate the following object types: threat actor, malware family, software or toolkit, IoC collection, vulnerability.reports: it allows you to associate reports.attack_techniques: it allows you associate attack techniques.files,domains,urls,ip_addresses: they allow you to associate IoCs.
As showed in the object creation request body template here, for the urls relationship you either use {"type": "url", "url": <a URL string>} or {"type": "url", "id": <a sha256 URL identifier>} as object descriptors. For domains and IP addresses you can use {"type": "domain", "id": <a domain>} or {"type": "ip_address", "id": <an IP address>}.
Examples
Add new elements, google.com and virustotal.com domains, to an existing IoC collection.
import requests
object_id = "bd4dbd7a189ca9a31cb1b0bdbe64aaba6aa1454ddcfde707518b811d2bc5b363"
relationship = "domains"
url = f"https://www.virustotal.com/api/v3/collections/{object_id}/relationships/{relationship}"
payload = { "data":
[
{
"type": "domain",
"id": "google.com"
},
{
"type": "domain",
"id": "virustotal.com"
}
]
}
headers = {
"accept": "application/json","x-apikey": <api-key>,"content-type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)Associate your threat-actor--c4cccd20514c416294a0b91fcfd40c44 actor with the malware--f872b3e0-c277-5716-baae-885a9c410398 Software or Toolkit, and the CVE-2026-39958 vulnerability.
import requests
object_id = "threat-actor--c4cccd20514c416294a0b91fcfd40c44"
relationship = "associations"
url = f"https://www.virustotal.com/api/v3/collections/{object_id}/relationships/{relationship}"
payload = { "data":
[
{
"type": "collection",
"id": "malware--f872b3e0-c277-5716-baae-885a9c410398"
},
{
"type": "collection",
"id": "vulnerability--cve-2026-39958"
}
]
}
headers = {
"accept": "application/json","x-apikey": <api-key>,"content-type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)Associate your actor with the report--26-10018712 report.
import requests
object_id = "threat-actor--c4cccd20514c416294a0b91fcfd40c44"
relationship = "reports"
url = f"https://www.virustotal.com/api/v3/collections/{object_id}/relationships/{relationship}"
payload = { "data":
[
{
"type": "collection",
"id": "report--26-10018712"
}
]
}
headers = {
"accept": "application/json","x-apikey": <api-key>,"content-type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)Link the T1087 attack technique to your actor.
import requests
object_id = "threat-actor--c4cccd20514c416294a0b91fcfd40c44"
relationship = "attack_techniques"
url = f"https://www.virustotal.com/api/v3/collections/{object_id}/relationships/{relationship}"
payload = { "data":
[
{
"type": "attack_technique",
"id": "T1087"
}
]
}
headers = {
"accept": "application/json","x-apikey": <api-key>,"content-type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)200