Initiate Process File

Description

Initiate scan request

URL Path

/file

Method

POST

Summary

There are two ways of initiate processing 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

Notes

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.

 

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.

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 (before splitted to chunks)

OPTIONAL

Used for chunk uploading.

  • Both MO and REST have already had these headers before. It still be used now.

  • Should expose, a big file can be uploaded as many parts.

  • Case insensitive.

  • This is data_id returned from 1st request and following request will return same data_id. Any further upload more than x-file-size will result in error (not affecting the scan). Checking progress until all file contents is uploaded will return "not found"

Limitation: returned data_id can be changed after last chunk uploaded, see this case: database already had scan result for file A, customer uses chunk upload and posts this file again, for the first chunk we return data_id_1 (since don't know that file already exist in DB with only first chunk), when all chunks are uploaded, we calculated hash and found the result in DB, then we return old data_id (different with data_id_1) without scanning.

 

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": "scan01.metascan-online.com/v2"
}

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.