2.1 Scanning a file by file upload

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