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 |
filepassword |
if the submitted file is a password-protected file (pdf, docx ...) |
|
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 |
multiscan, sanitize, 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 analized 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 |
-
When sanitizing a file we will keep a copy of the sanitized version of the file for 24 hours 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
Response
HTTP Status Codes
Please refer to Status Codes for more information.
Body
Errors
Please refer to Errors for more information.