Home • Hashes • Research • About • Swag Shop
| 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 https://virusshare.com/apiv2. A typical query is formatted as follows: |
| https://virusshare.com/apiv2/<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. Excessive 204 response codes will result in you being automatically blocked. It is highly recommended that you add a momentary pause to your code after receiving a 204 response from the server. |
| • 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 |
| /file |
| 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 |
| /download |
| 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 |
| /quick |
| 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: |
| {"response":1} |
| Retrieving source information for a file |
| /source |
| 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: |