2.1 Scanning a file by file upload

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.

Request

Header Parameters

 

Description

Allowed Values

Required

apikey

Gives 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 the submitted file is a 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 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

sanitize, unarchive

NO

sandbox

Also request a sandbox scan for the uploaded file

windows7, windows10

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)

 

NO

  • 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 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": "ZzE2MTEyMlMxMkQ1U0dmR3hyeTZ3NVNHR01s",
"status": "inqueue",
"in_queue": 2,
"queue_priority": "high"
}

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.

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' \
-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