What is the VirusTotal API?
The VirusTotal API lets you upload and scan files, submit and scan URLs, access finished scan reports and make automatic comments on URLs or samples without the need of using the HTML website interface. In other words, it allows you to build simple scripts to access the information generated by VirusTotal.
The chosen format for the API is HTTP POST requests with JSON object responses and it is limited to at most 20 requests of any nature in a given 5 minutes time frame. If you run a honeyclient, honeypot or any other automation that is going to provide resources to VirusTotal and not only retrieve reports you are entitled to a special API with a higher request rate quota, ask for it at info@virustotal.com. The public API is a free service, available for any web site or application that is free to consumers.
The API must not be used in commercial products or services, it can not be used as a substitute for antivirus products and it can not be integrated in any project that may harm the antivirus industry directly or indirectly. Noncompliance of these terms will result in inmediate permanent ban of the infractor individual or organization. Please see the terms of use for more information.
How do I start?
The process could not be easier. Sign up to VT Community (using the sign in box at the top left hand side of the page). Once you have a valid VT Community account, you will find your personal API key in the inbox of your account (sign in and drop down the My account menu). This key is all you need to use VirusTotal's API.
So what can I do with the VirusTotal API?
The following examples show how to perform specific tasks with the API, the examples are coded in Python, but take into account that they work with any coding language, you just need to be able to perform HTTP requests and load JSON objects. Some implementations of the API in other languages can be found at the bottom of this page.
Note that the API response format will always be a dictionary containing at least a result field. If the item you searched for was not present this result will be 0, if you exceeded the public API request rate it will be -2, if the API key provided is incorrect it will be -1, any other case is detailed in the following sections. |