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: |
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 |
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. |
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 SHA256 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/8.1.3.1._Process_a_file.html for more details |
core_rule |
Name of the rule to send to MetaDefender Core |
OPTIONAL |
See https://onlinehelp.opswat.com/corev4/8.1.3.1._Process_a_file.html for more details |
archivepwd<X> |
One or more passwords for the file |
OPTIONAL |
Multiple passwords is also supported, format: archivepwd<X>
archivepwd1: <password 1 > archivepwd2: <password 2 > archivepwd3: <password 3 > ... archivepwdN: <password N> Each archivepwd<X> is a separate header. You can use N headers in order to set multiple password for nested encrypted archive which contains encrypted files inside. Set only archivepwd if the file is encrypted with password or leave this field empty when the file is not password protected. |
|
|
DEPRECATED |
Note: This header has been deprecated please set it using archivepwd<X> format |
|
|
DEPRECATED |
Note: This header has been deprecated please set it using archivepwd<X> format |
|
|
DEPRECATED |
Note: This header has been deprecated please set it using 5. Complete Group Transfer |
|
|
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. |