8.1.3.1. Process a file

Scanning a file using a specified workflow.

Scan is done asynchronously and each scan request is tracked by data id of which result can be retrieved by API 8.1.3.2. Fetch processing result.

Chunked transfer encoding (applying header Transfer-Encoding: Chunked) is not supported.

Multipart form upload is not supported, instead please consider using batch submission 8.1.4. Processing files in batch

Since MetaDefender Core 4.19.0, the request will be refused immediately with HTTP(S) error code 400 when MetaDefender Core does not have sufficient free disk space to handle. This is to avoid upload time being wasted.

Request

Value

Method

POST

URL

/file

Request HTTP header parameters:

name

type

required

value

apikey

string

false

Session id, can be acquired by 8.1.1.1. Login / Create a Session

filename

string

false

name of file

filepath

string

false

if local file scan is enabled the path to the file (see Security rule configuration)

user_agent

string

false

client identification string

rule

string

false

name of the selected rule (see 8.1.3.5. Fetching available processing rules)

workflow

string

false

name of the selected workflow (deprecated, use "rule" header parameter instead)

archivepwd

string

false

password for archive ( URL encoded UTF-8 string)

Multiple passwords is also supported, format: archivepwd<X>

  • X: Could be empty

  • When having value, X must be a number >= 1

For example:

archivepwd1: "fox"

archivepwd2: "cow"

archivepwd3: "bear"

metadata

string (JSON format)

false

could be utilized for:

  • Additional parameter for pre-defined post actions and external scanners (as a part of STDIN input).

  • Customized macro variable for watermarking text (Proactive DLP engine feature).

  • Additional context / verbose information for each file submission (appended into JSON response scan result).

For example: {"client_ip":"10.0.1.100","custom_para":"ABC"}

callbackurl

string ( <protocol://><ip | domain>:<port></path>)

false

Client's URL where MetaDefender Core will notify scan result back to whenever scan is finished (webhooks model). See details at 8.1.11.1. Individual file processing

Note: Support both non-secure (HTTP) and secured protocol (HTTPS). In case of secured protocol HTTPS, only TLS 1.2 or above is accepted by Core on the data transportation encryption between Core and remote server (client).

For example:

Request body should contain the the content to be scanned.

Successful response

HTTP status code: 200

{
"data_id": "61dffeaa728844adbf49eb090e4ece0e"
}

Error response

API key is invalid (only applicable when apikey header is sent)

HTTP status code: 400

{
"err": "Invalid apikey given"
}

Callback URL is invalid (only applicable when callbackurl header is sent)

HTTP status code: 400

{
"err": "Callback url is invalid."
}

Body data and filepath header are provided at the same time (only applicable when filepath header is sent)

HTTP status code: 400

{
"err": "Both body data and local file path were given."
}

Internal error during processing batch (only applicable when callbackurl header is sent)

HTTP status code: 400

{
"err": "Can not scan in given batch."
}

Batch is closed when file is not uploaded properly (only applicable when callbackurl header is sent)

HTTP status code: 400

{
"err": "Batch closed during file upload."
}

Out of disk space for file upload request

HTTP status code: 400

{
"err": "File upload denied due to insufficient disk space."
}

Callbackurl header exists, but empty (only applicable when callbackurl header is sent)

HTTP status code: 403

{
"err": "No callback url given."
}

Content-Length header is missing from the request

HTTP status code: 411

{
"err": "Missing Content-Length header"
}

Body input is empty

HTTP status code: 422

{
"err": "File is empty"
}

Internal error

HTTP status code: 500

{
"err": "Failed to request scan. Try again later."
}

File size is larger than permitted maximum size

HTTP status code: 500

{
"err": "Failed to request scan. File size exceeded the maximum size permitted by your configuration."
}

Need to perform local file scan, however, the file defined in filepath header is inaccessible (only applicable when filepath header is sent)

HTTP status code: 500

{
"err": "File not found, invalid path or access."
}

License has been expired

HTTP status code: 500

{
"err": "License is expired"
}

There's no rule for scanning

HTTP status code: 500

{
"err": "No available rule is present for scanning."
}

Scan queue is full

HTTP status code: 503

{
"err": "Server is too busy. Try again later."
}

Unexpected event on server

HTTP status code: 500

{
"err": "<error message>"
}

Note: Check Metadefender Core server logs for more information.