1.2. Initiate Process File

Description

Initiate scan request

URL Path

/file

Method

POST

Summary

There are two ways of initiate processing a file. One is to upload file and the other is passing the file path (local to the server).

There are several important parameters should be passed along the request so that administrators can track such histories on the server side without relying on additional application logic on client sides.

HTTP header parameters

Parameter

Value

Required

Description

apikey

API key configured by administrator.

OPTIONAL

 

filename

Name of files to preserve extension during scan and meta data.

RECOMMENDED

filename should be encoded with URLencode and should not contains characters "<" and ">"

Otherwise, it will be removed from filename.

  • This will be sanitized and all invalid file_name characters will be removed.

  • If file type mismatch is enabled, needs filename to know original file extension. If not providing this header, it will cause mismatch.

filepath

Path of files that are accessible to Core server

OPTIONAL

  • filepath should be URLEncoded.

  • filepath should be accessible to core server.

  • When this head is set, no content need to be put in HTTP request body. Core server will try to process/scan using filepath directly

user_agent

A string to identify the client application

OPTIONAL

Administrator configures to map user agents to specific workflow.

rule

A string to define which workflow to use (i.e. workflow name)

OPTIONAL

This will supersede user_agent and both should not be used at the same time

Note: Workflow names can be retrieved from the Management Console Workflow list or REST API, Retrieve profiles (ID and name).

archivepwd

password of encrypted file

OPTIONAL

If submitted file is password protected archive.

original_file_path

File path of file scanned on local to the Metascan

OPTIONAL

original_file_path should not contains characters "<" and ">".

Otherwise, it will be removed from original_file_path.

Note: This will be sanitized and all invalid path and file name characters will be removed.

source

IP, hostname, or other client ID

RECOMMENDED

Helps identify where the file is originated from. This should be end-user information to trace where the file came from.

X-File-Size

Total size of the original file in Bytes (before splitting to chunks)

OPTIONAL

Used for chunk uploading.

Case insensitive.

For further information, jump to Chunked Uploading.

X-File-ID

ID number is retrieved after uploading the 1st chunk

OPTIONAL

Method: POST

HTTP body

Contents of the file for scan

REQUIRED

Response Codes

Code

Status Description

Notes

200

OK

File is uploaded to the server for initiation.

400

Bad Request

Invalid request format or server is not configured correctly for Metascan.

401

Invalid API key

Either missing API key or invalid API is passed.

403

scan limit reached, try again later

 

403

exceeded number of allowed clients

exceeded number of simultaneous clients

 

403

Invalid License

 

500

Not enough disk space

Not enough free space in the temp directory to upload the file.

500

License expired

 

500

Internal error

 

503

Failed to request scan. Try again later.

 

503

Server is too busy. Try again later.

 

Response

Example of successful scan request:

{
"data_id":"4f84e3b096d54908963d037b5457bf27" 
"rest_ip": "..."
}

Example of failed to upload:

"err": "Failed to upload - <error message>"
}

Descriptions of response:

Response

Description

data_id

Data ID used for retrieving scan results. Since there are potentially multiple scans for same files when any engine has different definition time or when there is an additional engine, this is identifier for per scan other 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.

Chunked uploading

Files exceeding the maximum request length can be uploaded in chunks through the REST interface using the X-File-Size and X-File-ID headers.

To use Chunked uploading:

  • Split the file into chunks with size less than the maximum request length.

  • Upload the first chunk via REST API with X-File-Size header containing the total size of the file in Bytes.

  • The upload will return a data_id - save this ID.

  • Use the previously saved data_id in the X-File-ID header for uploading the remaining chunks (without the X-File-Size header).
    Metadefender Core will accept chunks for the upload until the size given in the first chunk's X-File_Size header is met. Any further uploads with the same X-File-ID header will result in an error (not affecting the result of the scan).

  • After receiving the last chunk, Metadefender Core will rebuild the file, and calculate its hashes.
    Then, if the hash is already in the database, it will return the old data_id without scanning, otherwise it will scan the file and store the result with the data_id returned for the first request.