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

Summary

Scan a file. It supports http multipart and binary uploads.

Initiate scan request

On MetaDefender Cloud, scans are performed asynchronously, and each scan request is tracked by a data id. After retrieving the data id, a long polling process needs to be started, to check if the scan has finished.

At the moment, there is no mechanism to notify the user back that the scanning has finished.

Request

Header Parameters

	Description	Allowed Values	Required
apikey	give rights to use the endpoint (token authentication) (API Authentication Mechanisms)	apikey	YES
filename	name of files to preserve extension and metadata during scan		NO
archivepwd	if submitted file is password-protected archive		NO
samplesharing	only working for paid users - allow file scans to be shared or not	0 / 1	NO
downloadfrom	link to download file, allow user to scan file by link before actually downloading it	Only direct downloads, no redirects	NO
user_agent	activate workflows	mcl-metadefender-rest-sanitize-disabled-unarchive, dlp	NO
content-type	specify the http content type	multipart/form-data (when doing multipart upload) application/octet-stream (when doing binary upload)	YES

Private scanning does not work with sanitization. When sanitizing a file, even if the file is uploaded with "samplesharing: 0" header, we will keep a copy of the sanitized version of the file for the user to download.
Always specify content type header for the correct upload of files.

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 successful scan request:

{
   "data_id": "ZzE2MTEyMlMxMkQ1U0dmR3hyeTZ3NVNHR01s",
   "status": "inqueue",
   "in_queue": 2,
   "queue_priority": "high",
   "rest_ip": "api.metadefender.com/v2"
}

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.
rest_ip	Requests for the scan progress using 'data_id' should be made to this address instead of the original address. Once a scan is finished, future requests for this 'data_id' can be made to the original address.
status	Status of the scan request. Value inqueue represents state, when 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 used go to high.

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": [
    "v2",
    "file"
  ],
  "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 POST \
  https://api.metadefender.com/v2/file \
  -H 'apikey: ${APIKEY}' 

Sample code (powershell)

# usage: upload-example.ps -path test.txt
 
param(
    $Path
)
 
$uri = 'https://api.metadefender.com/v2/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