Request	Value
Method	POST
URL	https://api.metadefender.com/v4/file
Throttled	Yes

Summary

Scanning a file starts with uploading a file to MetaDefender Cloud to initiate the scan. Although we are trying to keep scanning very fast, scanning using 30+ engines takes many seconds to many minutes depending on types of files, and the load.

Scan by long polling

Scanning a file by long polling consists of 3 steps:

initiate Scan request by uploading a file
retrieve scan report using the "data_id" (found in the response of this endpoint)
perform long polling by "data_id" until scanning finishes

Scan with callback URL

As an alternative, there is a callback mechanism that notifies the API user when the scanning has finished. Just specify the "callbackurl" header with the desired URL where we will send the results once finished.

The response type will be 'content-type': 'application/json' and the user agent sent will be 'user-agent': 'opswat metadefender cloud' to easily identify traffic. Please refer to our webhook endpoint to see the status of a callback response.

Schedule periodic rescans

It is also possible to upload a file and define a schedule for automatic rescans of that file in the future. The schedule can be defined by two simple headers: the "rescan_count" header specifies how many times the file should be rescanned and the "rescan_interval" header defines how many hours should elapse between two consecutive scans. Note that each completed rescan will decrease the Prevention API rate limit as defined in 3. Rate Limiting.

Request

Header Parameters

	Description	Allowed Values	Required
apikey	Gives rights to use the endpoint (token authentication) (API Authentication Mechanisms)	apikey	YES
filename	File name is mainly for the descriptive purpose. File name does not affect the analysis. However, it is recommended to provide this info in order for you to associate the result with the actual file from the UI.		NO
archivepwd	If the submitted file is a password-protected archive, the value provided will be used to unlock the file. This information is removed once analysis is done.		NO
filepassword	If the submitted file is a password-protected document file, the value provided will be used to unlock the file. This information is removed once analysis is done.		NO
samplesharing	By default, it is enabled. If enabled, opt in to share the file with the malware research community or internal malware research team to investigate further, especially when the file is considered either false positive or potential outbreak malware. Only paid customers can exclude this file from our sample sharing algorithm. If disabled, the file will be deleted immediately once the analysis is done.	0 (disable) / 1 (enable)	NO
privateprocessing	By default, it is disabled. If enabled, the file will be immediately removed after analysis is done, and analysis results are only available to the owner, who submits the file for analysis. If disabled, the analysis results will be viewable to the public, and the samplesharing parameter will determine the malware sharing.	0 (disable) / 1 (enable)	NO
downloadfrom	Link to download file, allow the user to scan file by link before actually downloading it	Only direct downloads, no redirects	NO
rule	The workflow rule to activate. Multiple values can be sent separated by "," to combine multiple workflows in one. multiscan is always performed, even if not specified, except for cdr rule which can be used only as standalone rule and does only file sanitization.	multiscan (Default if no rule is sent) sanitize cdr (sanitize without multiscan) unarchive	NO
sandbox	Also request a sandbox scan for the uploaded file.	windows7, windows10	NO
sandbox_timeout	Specifies for how long the file should be analyzed on the sandbox. Short=150s, long=300s.	short; long	NO
sandbox_browser	What browser to use when uploading html/JavaScript files or analyzing URLs.	os_default, chrome, firefox	NO
content-type	HTTP content type	multipart/form-data (when doing multipart upload) application/octet-stream (when doing binary upload)	YES
callbackurl	Specify a valid, publicly accessible URL where we can send the scan results when finished (asynchronous scanning, similar to webhooks) See 8. Webhooks for details.	Valid URLs	NO
rescan_count	Defines how many times the file should be rescanned	1-720 (t he full schedule should fit into 720 hours)	NO
rescan_interval	Defines how many hours should pass between two consecutive scans	1-720 (t he full schedule should fit into 720 hours)	NO

When sanitizing a file we will keep a copy of the sanitized version of the file for 24 hours for the user to download unless the Delete Sanitized Files Endpoint is called.
Always specify the content-type header for the correct upload of files.

To ensure that files are uploaded correctly and file integrity is not altered some body payload restrictions must be respected:

binary: If files are sent in binary mode, 'content-type: application/octet-stream' header must be set. This mode of uploading files is PREFERRED!

curl -X POST https://api.metadefender.com/v4/file \
-H 'apikey: ${APIKEY}' \
-H 'content-type: application/octet-stream' \
-d @/path/to/data.file

form-data: when uploading files using the -F(--file) header, set 'content-type: multipart/form-data' header

curl -X POST https://api.metadefender.com/v4/file \
-H 'apikey: <apikey>' \
-H 'content-type: multipart/form-data' \
-F =@/path/to/data.file

Body (payload)

	Format	Required	Example
HTTP Body	binary / www-url-encode / multipart / chunked	YES	`----WebKitFormBoundary7MA4YWxkTrZu0gW` `Content-Disposition: form-data; name=""; filename=""` `Content-Type:` `----WebKitFormBoundary7MA4YWxkTrZu0gW`

Response

HTTP Status Codes

Please refer to Status Codes for more information.

Body

Example of a successful upload request:

{
    "data_id": "bzIwMDExN1NreHhiOG9RSmJVU2tXeFdJc1FKWjg",
    "status": "inqueue",
    "in_queue": 1,
    "queue_priority": "normal",
    "sha1": "068AE4D07A7F4FE2BF955CBA0FD05AB0A5A8A6FE",
    "sha256": "67C6BCEE6FFCEFA887E415CBF0247C2788696169B58EB66319F558DDB6822D9D"
}

Example of a failed upload request:

{
    "error": {
        "code": 400140,
        "messages": [
            "Multipart: Boundary not found"
        ]
    }
}

Descriptions of response:

dataId	Data ID used for retrieving scan results. Since multiple scans can potentially be performed for the same files when any engine has a different definition time or when there is an additional engine, this is the identifier for per-scan rather than per-file.
status	Status of the scan request. Value inqueue represents the state, when the scan is being queued for scanning.
in_queue	Counter representing the total numbers of files in the queue at the time of the request.
queue_priority	The priority of the file in scanning. Free users have normal priority, and paid users go to high.
sha1 and sha256	The hashes of the file as seen by the server. This can be used to verify that the file upload was performed correctly.

Errors

Please refer to Errors for more information.

Sample code (Node.js)

var http = require("https");
 
var options = {
  "method": "POST",
  "hostname": [
    "api",
    "metadefender",
    "com"
  ],
  "path": [
    "v4",
    "file"
  ],
  "headers": {
    "content-type": "multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW",
    "apikey": process.env.APIKEY,
    "Content-Type": "multipart/form-data"
  }
};
 
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.write("------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"\"; filename=\"C:\\Users\\user_name\\Downloads\\test_doc.pdf\"\r\nContent-Type: application/pdf\r\n\r\n\r\n------WebKitFormBoundary7MA4YWxkTrZu0gW--");
req.end();

Sample code (cURL)

curl -X POST https://api.metadefender.com/v4/file \
-H "apikey: ${APIKEY}" \
-H 'content-type: application/octet-stream' \
-H 'sandbox: windows10' \
-d @/path/to/data.file

Sample code (powershell)

# usage: upload-example.ps -path test.txt
 
param(
    $Path
)
 
$uri = 'https://api.metadefender.com/v4/file'
$file = Split-Path $Path -leaf
$apikey = $env:APIKEY
 
Write-Output $Path
Write-Output $file
 
$headers = @{}
$headers.Add('apikey', $apikey)
$headers.Add('filename', $file)
 
$result = Invoke-WebRequest -Uri $uri -Method Post -Headers $headers -Body $Path -ContentType 'application/octet-stream'
Write-Output $result.content

2.1 Scanning a file by file upload