Upgrading from API v2 to v3: What You Need to Know

The VirusTotal API is a versatile and powerful tool that can be utilized in so many ways. Although it is commonly used for threat intelligence enrichment and threat analysis, the potential uses are virtually limitless. The latest version, VirusTotal API v3, is continuously updated with new features to enhance its capabilities with every new release.

With this post we want to help you understand its potential and, in case you are a VT API veteran, help you migrate from API v2 to API v3 to unleash its full potential.

To simplify the process of adopting and migrating to VirusTotal API v3, we have updated the official documentation with a specific section dedicated to this purpose. We also created a GitHub repository with working examples. In the next few weeks we will host a webinar showing you cool use cases you can implement with VT API, so stay tuned!

Why use VT API v3?

The migration guide describes in detail most API v3 benefits, including:

• Endpoints for all VirusTotal products and scanners. VT users can access all of VirusTotal’s tools through a single API, simplifying the integration process.
• User and group management helping administrators to automate managing access and accounts, as well as tracking usage across your team.
• Extra relevant information for file, URL, domain and IP reports. VT API v3 provides additional information for all file, URL, domain and IP reports, including metadata and context.
• REST-based, with predictable, resource-oriented URLs. VirusTotal API v3 uses a RESTful architecture, following a standard set of design principles for building web services with HTTP methods accessed through predictable, resource-oriented URLs, making it easier to use and integrate with other tools.
• MITRE related tactics and techniques seen in file behavior. API v3 provides information on TTPs used by malware samples, as defined by the MITRE ATT&CK framework. This helps understanding the potential impact of a sample and how to respond to any threats.
• More extensive documentation and code examples based on the Python module. V3 has more extensive documentation and code examples which make it easier for users to get started with the API and integrate it into their workflows.

API v2-v3 Migration Guide

Our migration guide outlines the differences between VT API v2 and v3, touching on aspects such as data formats, available integration with other VT products and features, and what are the API Scripts and client libraries available for each one.

It also details the differences between v2 and v3 endpoints, including differences in requests and responses. The table below summarizes endpoint correspondence between v2 and v3:

Description	VT API v2	VT API v3
Submitting samples, getting file reports, and rescanning files
Submit file (<= 32MB)	/file/scan	/files
Submit file(> 32MB)	/file/scan/upload_url and /file/scan	/files/upload_url and /files
Get file report	/file/report (allinfo parameter)	/files/{id}
Rescan file	/file/rescan	/files/{id}/analyse
Getting file behaviour reports and downloading network traffic files
Get file behavior report	/file/behaviour	/files/{id}/behaviours and /file_behaviours/{sandbox_id}/html
Download PCAP	/file/network-traffic	/file_behaviours/{sandbox_id}/pcap
Scanning URLs, getting reports for URLs, domains, and IP addresses
Scan URL	/url/scan	/urls
Get URL report	/url/report	/urls/{id}
Get domain report	/domain/report	/domains/{domain}
Get IP address report	/ip-address/report	/ip_addresses/{ip}
Feeds for enrichment
Get file feed	/file/feed	/feeds/files/{time} and /feeds/files/hourly/{time}
Getting URL feed	/url/feed	/feeds/urls/{time} and /feeds/urls/hourly/{time}
Getting file clusters and downloading files
Get file clusters	/file/clusters	/stats/vhash_clusters
Download file	/file/download	/files/{id}/download
VT Intelligence via API
Advanced search	/file/search (only for files)	/intelligence/search

One more thing

In addition to the examples provided in the GitHub repository, the official API documentation offers additional cool features.

First of all, it provides code examples for every endpoint! The 3 dots button shows a list of available programming languages you can get examples. Select any of them and the code is automatically updated to that language.

Additionally, the ‘Try It!’ button executes the request for you and shows the JSON result in the ‘RESPONSE’ section under the code snippet.

Conclusions

API v2 served VirusTotal users well for many years, but it lacks some features required to any modern professional API. Don’t panic, you can still continue using API v2 if you really have to. We want to make sure you understand the advantages of using v3 and provide you with everything needed to make v2 to v3 transition as smooth as possible.

Probably the main advantage is that API v3 is VirusTotal’s standard, and some day in the future we will have to sunset v2. Nevertheless, in v3 we make sure that every service and feature has its corresponding endpoint. That includes many functionalities not available in v2, like user and group management, threat landscape, Graphs or Private Scanning, among others. Moreover, API v3 provides extended data on VT reports for any observable!

We hope the extensive documentation and code examples will help you master API v3 very soon! If you have any suggestions or just want to share feedback, please feel free to reach out here.

Happy hunting!