Request	Value
Method	GET
URL	https://api.metadefender.com/v4/hash/:hash

Summary

Look up a hash by MD5, SHA1, or SHA256.

Request

URL Parameters

	Description	Example
:hash	MD5, SHA1, or SHA256 of a file	6A5C19D9FFE8804586E8F4C0DFCC66DE

Header Parameters

	Description	Allowed Values	Required
apikey	gives rights to use the endpoint (token authentication) (API Authentication Mechanisms)	apikey	YES

Response

HTTP Status Codes

Please refer to Status Codes for more information.

Body

Example of a successful request:

{
    "scan_result_history_length": 154,
    "file_id": "ZTE3MDgyMkh5UmZGTl94cV9a",
    "data_id": "ZTE3MDgyMkh5UmZGTl94cV9aUzFsSWU3aGtVNA",
    "process_info": {
        "result": "Blocked",
        "profile": "Sanitize",
        "post_processing": {
            "copy_move_destination": "",
            "converted_to": "",
            "converted_destination": "",
            "actions_ran": "",
            "actions_failed": ""
        },
        "file_type_skipped_scan": false,
        "blocked_reason": "Infected"
    },
    "scan_results": {
        "scan_details": {
            "Zillya!": {
                "threat_found": "Adware.GenericKD.Win32.5471",
                "scan_time": 26,
                "scan_result_i": 1,
                "def_time": "2019-02-26T17:27:00.000Z"
            },
            ...
            "Vir.IT ML": {
                "threat_found": "",
                "scan_time": 2275,
                "scan_result_i": 0,
                "def_time": "2019-02-22T14:46:00.000Z"
            }
        },
        "rescan_available": true,
        "scan_all_result_i": 1,
        "start_time": "2019-02-26T21:53:32.770Z",
        "total_time": 11206,
        "total_avs": 37,
        "total_detected_avs": 15,
        "progress_percentage": 100,
        "scan_all_result_a": "Infected"
    },
    "file_info": {
        "file_size": 765024,
        "upload_timestamp": "2017-09-05T18:30:04.000Z",
        "md5": "6A5C19D9FFE8804586E8F4C0DFCC66DE",
        "sha1": "016CD548A5BA78015F85E2591BF6189658ACA066",
        "sha256": "BE41E36233DD8DB2B28A109E7FC7C409E1353BF2D1710158BBE267280E163353",
        "file_type_category": "E",
        "file_type_description": "Executable File",
        "file_type_extension": "exe",
        "display_name": "CleanupConsole.exe"
    },
    "share_file": 1,
    "rest_version": "4",
    "additional_info": [],
    "votes": {
        "up": 0,
        "down": 0
    }
}

Example of a successful request for an archive:

{
    "scan_result_history_length": 5,
    "file_id": "YTE3MDgwMlNKd1pQcmRmSlBX",
    "data_id": "YTE3MDgwMlNKd1pQcmRmSlBXcmtrZDdlTlVfNlE",
    "process_info": {
        "result": "Blocked",
        "profile": "File scan",
        "post_processing": {
            "copy_move_destination": "",
            "converted_to": "",
            "converted_destination": "",
            "actions_ran": "",
            "actions_failed": ""
        },
        "file_type_skipped_scan": false,
        "blocked_reason": "Infected"
    },
    "extracted_files": {
        "data_id": "YTE3MDgwMlNKd1pQcmRmSlBXcmtrZDdlTlVfNlE",
        "files_in_archive": [
            {
                "scan_result_i": 15,
                "progress_percentage": 100,
                "file_type": "application/encrypted",
                "file_size": 14336,
                "display_name": "test_protected.xlsx",
                "detected_by": 0,
                "data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYcnlYdWxWVXVUbQ"
            },
            {
                "scan_result_i": 15,
                "progress_percentage": 100,
                "file_type": "application/msword",
                "file_size": 22528,
                "display_name": "test_protected.doc",
                "detected_by": 0,
                "data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYckpIX3hWVU82bQ"
            }
        ]
    },
    "scan_results": {
        "scan_details": {
            "TrendMicro House Call": {
                "threat_found": "",
                "scan_time": 975,
                "scan_result_i": 0,
                "def_time": "2018-11-11T02:00:00.000Z"
            },
            ...
            "Vir.IT ML": {
                "threat_found": "",
                "scan_time": 5,
                "scan_result_i": 0,
                "def_time": "2018-11-09T14:46:00.000Z"
            }
        },
        "rescan_available": true,
        "scan_all_result_i": 1,
        "start_time": "2018-11-13T13:38:52.680Z",
        "total_time": 7001,
        "total_avs": 35,
        "total_detected_avs": 0,
        "progress_percentage": 100,
        "scan_all_result_a": "Infected"
    },
    "file_info": {
        "file_size": 1286700,
        "upload_timestamp": "2018-03-21T16:47:30.000Z",
        "md5": "EF4A5B9ECC9D2E3380D035F71C00AFA1",
        "sha1": "972695E77E75307EC38B2F089EDBE129C29FF870",
        "sha256": "0C4161B19D8CE5B2721AA0AF2CDDE5F121DDAB81004DB3B7FF243D74CFFD3EA4",
        "file_type_category": "",
        "file_type_description": "ZIP Archive",
        "display_name": "archive.zip"
    },
    "share_file": 1,
    "rest_version": "4",
    "additional_info": [],
    "votes": {
        "up": 0,
        "down": 0
    }
}

Example of failed scan request:

{
    "error": {
        "code": 404003,
        "messages": [
            "The hash was not found"
        ]
    }
}

Descriptions of response:

Field	Description	Type	Values
scan_results.scan_details	Per engine scan results	object
scan_results.scan_details.<engine>	The individual engine results	object	List of anti-malware engines
scan_results.scan_details.<engine>.scan_time	How much time in milliseconds it took for the engine to scan the file	int
scan_results.scan_details.<engine>.scan_result_i	The scan code of the engine for this file	int	Description on scan result codes
scan_results.scan_details.<engine>.def_time	The engine definition time	date
scan_results.scan_details.<engine>.threat_found	If a threat was found, this field will contain the exact string of the infection returned by the engine	string
scan_results.rescan_available	Whether this file can be rescanned or not	boolean
scan_results.scan_all_result_i	The scan returned code	int	Description on scan result codes
scan_results.start_time	The time when the scan has started. This is different from the "file_info.upload_timestamp" field and the difference between these 2 fields show how much the file has been waiting in the queue to be scanned.	date
scan_results.total_time	The total time it took to scan this file	int	A positive number in milliseconds
scan_results.total_avs	The total number of AVs returned in the result	int
scan_results.total_detected_avs	The total number of AVs reporting this file as infected	int
scan_results.progress_percentage	The progress so far. Returns values between 0 and 100	int
scan_results.scan_all_result_a	A text description of the scan results	string
file_info.file_type_extension	File extension, deduced from "file_type_description"	string
file_info.file_type_description	File description as returned by the magic lib	string
file_info.file_type_category	Category for the file type	char	Description of file categories
file_info.upload_timestamp	The time the file was first uploaded	date
file_info.display_name	The name provided by the initial uploader of the file with the "filename" header	string
file_info.sha256	The sha256 of the file (we recommend using this hash as the reference)	hex
file_info.sha1	The sha1 of the file	hex
file_info.md5	the md5 of the file	hex
file_info.file_size	The size of the file, in bytes	int
data_id	Unique identifier for this particular scan of the file	string
file_id	Unique identifier of the file in our system	string
threat_name	OPSWAT generated threat name in the format "<malware_type>/<malware_family>!<unique_file_id>"	string	E.g: Ransomware/WannaCry!FifMs89q
votes.down	Crowdsourced community downvotes	int
votes.up	Crowdsourced community upvotes	int
additional_info	An array containing strings showing the existence of additional information	array	"exif" - call EXIF Lookup to get extra information "peinfo" - call PE Info Lookup for extra information "appinfo" - call Appinfo Lookup for extra information "apk-info" - call Apk Lookup for extra information
scan_result_history_length	The total number of scans	int
share_file	The privacy setting of the file. This is set by the "samplesharing" header at upload time	int	0 - the file is not stored. It was scanned once and deleted 1 - the file is stored on our servers, can be rescanned
stored	Informs the user if this file is stored or not by OPSWAT for later rescan	boolen	true - the file is stored false - the file was permanently deleted

Descriptions of archive scan response:

When scanning archives, the archive itself will be scanned as a file, and the files inside the archive will be extracted and scanned individually. The list of files in the archive, the scan results and total number of engines which detected the file as infected can be accessed in the parent archive scan results. For accessing the detailed scan results of the contained file, a separate call needs to be made to the file's data_id.

Field	Description	Type	Values
extracted_files.data_id	Same data_id as the original file	string
extracted_file. files_in_archive	The list of files extracted from the scanned archive; each item from the list contains a few scan result details.	array
extracted_file. files_in_archive.<>.data_id	The data_id of the individual file scan	string
extracted_file. files_in_archive.<>.detected_by	How many engines detected the file as infected	int
extracted_file. files_in_archive.<>.display_name	The name of the file as found in the archive	string
extracted_file. files_in_archive.<>.file_size	The size of the file	int	Bytes
extracted_file. files_in_archive.<>.file_type	The type of the file as returned by the magic lib, just as "file_info.file_type_description" above	string
extracted_file. files_in_archive.<>.progress_percentage	The scanning progress of the file	int
extracted_file. files_in_archive.<>.scan_result_i	The code of the scan result	int	Description on scan result codes
parent_data_id	The data_id of the archive that contains the accessed file (the parent archive). This property will only be found in files inside archives.	string

Supported archive types: ZIP, TAR, RAR, GZ, BZ2, 7Z, XZ, CRX, RPM, Z, LZ, XPI, CAB.
If the archive contains sanitizable file types when scanning an entire archive, the respective files won't be sanitized, being interpreted as non-sanitizable files. Please refer to Data Sanitization Request for more information about sanitization.
When accessing the extracted files from an archive, "Parent Archive" option is available to identify and access the archive that contains the respective files.
Rescan is available only for the entire archive; the extracted files cannot be rescanned one by one.

Errors

The format of error messages:

Field	Description	Type	Values
error.code	The unique error code	int	Errors
error.messages	An array of string messages with additional information about the error	array

Sample code (Node.js)

var http = require("https");
 
var options = {
  "method": "GET",
  "hostname": [
    "api",
    "metadefender",
    "com"
  ],
  "path": [
    "v4",
    "hash",
    "6A5C19D9FFE8804586E8F4C0DFCC66DE"
  ],
  "headers": {
    "apikey": process.env.APIKEY
  }
};
 
var req = http.request(options, function (res) {
  var chunks = [];
 
  res.on("data", function (chunk) {
    chunks.push(chunk);
  });
 
  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});
 
req.end();

Sample code (cURL)

curl -X GET \
  https://api.metadefender.com/v4/hash/6A5C19D9FFE8804586E8F4C0DFCC66DE \
  -H "apikey: ${APIKEY}"

3.1 Retrieving scan reports using a data hash