- Because Sharing is Caring

Home • Hashes • Research • About

Account: Login

How to use the VirusShare API
The VirusShare API allows you to access reports and files programmaically without the need for a browser. Queries are made through a simple HTTP GET request and responses are returned in JSON formatted text.
All requests described in this reference share the common URL prefix A typical query is formatted as follows:<request>?apikey=<apikey>&hash=<hash_string>
API responses
All requests handled correctly by the server will return a 200 HTTP status code. The body of the response will usually be a JSON object (except for file downloads) that will contain the additional property 'response' to inform the status of the request. If the item searched for was not found in the database, the response code will be 0. In the case of file searches the response code of 1 indicates the item requested was found and is categorized as 'malware' or was detected by at least one antivirus engine, while a response code of 2 indicates the item requested was found and is categorized as 'benign' or having no detections. For non-file searches such as DNS or crawler history, return codes are limited to 0 and 1 to indicate not-found and found, respectively.
In the event of an error, you may receive any of the following HTTP status codes:
• 204 - Request rate limit exceeded. You are making more requests than are allowed or have exceeded your quota.
• 400 - Bad request. Your request was incorrect. This can be caused by missing parameters or incorrect values.
• 403 - Forbidden. You don't have privileges to make this request. You may be making a request without providing your API key or your key may not be authorized to make the request.
• 404 - Not found. The file you have requested could not be found. This is typically returned for file download requests where the file is not in the database.
• 500 - Internal server error. This error is probably not the result of your request but rather indicates an issue with how the server handled your request.
• 503 - Service unavailable. The system is not available to process your request at this time. Please try again later.
Retrieving a file report
You can retrieve the report for a file by specifying a single cryptographic hash string in the hash parameter. Hash values supported are md5, sha1, sha224, sha256, sha384, and sha512. The hash type will be auto-detected by the server. Only one hash may be requested per query.
Example response:
Downloading a file
You can download a file by specifying the hash string. Like the file report request above, the hash type will be auto-detected by the server and, if found, will be delivered inside a password-protected zip file. The password to extract the data is 'infected'. Benign files that have not been detected by an antivirus engine are not available for download at this time.
Quickly checking the status of a file
To save time, power, and bandwidth, you can use the quick request to inquire the status of a file by specifying the hash string. The response will be a JSON object containing only the 'response' value of 0, 1, or 2 to indicate unknown, malware, and benign, respectively.
Example response:
Retrieving source information for a file
You can retrieve a report of the source data for a file by specifying the sha256 hash string in the hash parameter. This request will return a JSON object containing an array of unix-timestamps and URLs where the crawlers found the file. This request only supports the sha256 hash at this time.
Example response: