Using the API Documentation to Run API Queries
The API documentation offers a valuable feature: directly querying the REST API for Indicators, Reports, Alerts, Actors, Malware, Vulnerabilities, and other data.
To get started, obtain your API key by logging into the Google Threat Intelligence (Google TI) portal, navigating to the 'API Key' section on the left side, and then visiting this URL: https://www.virustotal.com/gui/user/<your username>/apikey
The key will be used in the x-apikey field in the documentation.
To retrieve the Google TI Threat Score, provide a string in the x-tool field within the documentation. This string can be any value, such as “API_Docs_Testing.”
Both the x-tool and x-apikey fields are located in the HEADERS section of the documentation’s query builder. The query builder also includes PATH PARAMS and QUERY PARAMS. Path parameters appear before the question mark in the query URL, while query parameters appear after the question mark.
After building the query, click the “Try It!” button in the lower right corner of the “REQUEST” box. If successful, the “REQUEST” box will show the working Python 3 code, and the “RESPONSE” box will display the API-returned data in the requested format (e.g., JSON). You can quickly select and copy the contents of either box using the Copy button in their lower left corner.
The Python code can then be used in a script to develop an application that meets the requirements of your organization.
Example:
This example demonstrates retrieving all Indicators of Compromise (IOCs) associated with APT29. Begin by obtaining APT29's Collection ID using the list threats feature.
In the QUERY PARAMS → filter box put APT29.
In the HEADERS → x-apikey box put your API Key.
Click on “Try It!”
You will see the Python code in the “REQUEST” box and it will look like this: import requests
url = "https://www.virustotal.com/api/v3/collections?filter=APT29"
headers = {
"accept": "application/json",
"x-apikey": "your API Key"
}
response = requests.get(url, headers=headers)
print(response.text)
You will see the JSON response in the "RESPONSE" box.
This is only the start of the response, but you can see the collection ID is "threat-actor--7a39953e-0dae-569a-9d49-d52a4a8865b1",
{
"data": l
{
"id": "threat-actor--7a39953e-0dae-569a-9d49-d52a4a8865b1",
"type": "collection",
"links": {
"self": "https://www.virustotal.com/api/v3/collections/threat-actor--7a39953e-0dae-569a-9d49-d52a4a8865b1"
},
You can then Export the IOCs for APT29 from the “Export IOCs from a threat” page.
In the PATH PARAMS → id box input APT29’s collection ID threat-actor--7a39953e-0dae-569a-9d49-d52a4a8865b1.
In the PATH PARAMS → format box input the format of your choice JSON, CSV, or STIX.
In the HEADERS → x-apikey box put your API Key.
Click on “Try It!”
You now have working Python code to pull collection IDs in the “REQUEST” box.
You also have the IOCs in the “RESPONSE” box.
Conclusion
The ability to quickly build and test queries directly within the documentation makes the API more accessible and efficient for developing use cases tailored to your organization's requirements.