2. Initialize File Transfer

Description

This API allows a client to initialize a new file upload session where the file can be uploaded in chunks.

URL Path

/transfer_file

Method

GET

When using a diode without GET support

URL Path

/transfer_file_diode

Method

POST

Permissions Restrictions

The API is limited to the user roles listed above (i.e. CO, Administrator, User), but assuming that a valid set of parameters is provided, including a group_id, only the transfer owner will be able alter the transfer.

Example:

The user test1 initiates a group transfer (i.e. calls /transfer successfully) and it receives a transfer group ID - group_id.

The user test2 tries to append a file to transfer with ID group_id. A 403 - Forbidden error will be returned stating that the user that has made the request is not authorized to alter the transfer.

The user test1 tries to append a file to the transfer - operation successful.

The user test1 completes the transfer by calling POST /transfer - operation successful.

Transfer with ID group_id will be accessible to the user until its expiration date.

HTTP header parameters

Authorization

The API key of the caller

REQUIRED

This header should have the following format:
Bearer [API key obtained from the authenticate API]
Example: Bearer Cp01BwnXAIOLZXxn7yogjKqIZnZpQD

transfer_method

Specify the method of transferring chunks.

REQUIRED

Specify the method of transferring file chunks. Possible values are:

Stream - chunks are submitted in a synchronous orderly fashion
Chunk - multiple chunks can be transferred simultaneously; does not require any specific ordering of data

group_id

A unique transfer group id.

REQUIRED

A transfer group id obtains from the 1. Initialize Group Transfer call.

file_size

The total file size

REQUIRED

The size in bytes of the complete file to be transferred

file_name

Object file name

REQUIRED

The name of the file to be transferred

path

Path to the folder where you wish to upload the file

OPTIONAL

The full path to the folder where you wish to upload this file. Leave it empty if you wish to upload it in the root directory.
Example: my documents\images\phone

file_id

A unique file id

OPTIONAL

A unique file_id can be transmitted to support Diode scenarios. If no file id has been specified MetaDefender Vault will generate a unique id. Must be a valid v4 UUID (RFC4122 standard)

file_checksum

The MD5 hash of the file content

OPTIONAL

Used to verify data integrity when upload has been completed.

user_agent

Client identification to send to MetaDefender Core

OPTIONAL

See https://onlinehelp.opswat.com/corev4/Scan_A_File.html for more details
Leave this field empty in order to use the user_agent defined in Core Integration settings

core_rule

Name of the rule to send to MetaDefender Core

OPTIONAL

See https://onlinehelp.opswat.com/corev4/Scan_A_File.html for more details

archive_password

A password for the file (if it is an archive)

OPTIONAL

Leave this field empty when the file is not an archive or if it is not password protected

expires

Expiry date for transfer group

DEPRECATED

Note: This header has been deprecated please set it using 5. Complete Group Transfer

expires_after

Expiry time span for transfer group

DEPRECATED

Note: This header has been deprecated please set it using 5. Complete Group Transfer

Note

The following headers support URL encoding:

  • file_name

  • path

Example:

file_name*=UTF-8''foo-%c3%a4-%e2%82%ac.html


Request Codes

200

OK

successful request

400

Bad Request

Invalid HTTP request

401

Invalid parameter

An invalid header parameter was specified.

403

Forbidden

Authentication credentials incorrect

Tried to alter a transfer who has a different owner

500

Internal Server Error

Server is temporarily unavailable

Response

Example of a successful scan request:

{
"file_id" : "8840c7dca606418bbd2ba010e4649636"
}

Descriptions of response:

file_id

File id

The id of the file to be uploaded.