MetaDefender Managed File Transfer 3.6.1

This chapter describes the REST API calls that can be used with MetaDefender Vault. Through the Application’s Interface, any 3rd party application can interact and communicate directly with MetaDefender Vault. This allows you to add MetaDefender Vault to your automated workflow. Each call should include an authentication key or user credentials (username and password) or use 8.4 API Keys.

About this REST API

The exposed endpoint is located by default at http://localhost:8010/vault_rest/ (i.e. for Initialize Group Transfer the endpoint is http://localhost:8010/vault_rest/transfer).

All endpoints require you to provide the Authorization header. The value for this header should be obtained by calling Request An API Key. Please note that an authentication key has a limited lifetime and it should be refreshed to avoid expiration policy.

In order to change the URL it is recommended to use the Protocol Configuration Tool(located by default in C:\Program Files\OPSWAT\MetaDefender Vault\Tools).

This URL can also be changed directly from the configuration file by following these steps:

Go to the installation directory (by default C:\Program Files\OPSWAT\MetaDefender Vault)
Navigate to the WebServer/conf folder
Open the file called dynamic.conf using administrative privileges

Edit the following section of the configuration file as you wish:

listen <ip_address>:<port>;
server_name "<machine_name>";

Or, in case of TLS/SSL:

listen <ip_address>:<port> ssl;
server_name "<machine_name>";
ssl_certificate "<certificate_path>";
ssl_certificate_key "<certificate_key_path>";
ssl_password_file "<password_file_path>";

Restart MetaDefender Vault Helper Service (vaultHelper) for changes to apply.

Server

http://localhost:8010

Authentication

http basicAuth

http bearerAuth

Authentication Management

Overview

These APIs provide functionality to create, update and delete API keys. The first step should be to Request an API key before continuing with other API calls.

GET

/vault_rest/authenticate

DELETE

/vault_rest/authenticate

/vault_rest/tokens/{start}/{count}

Request An API Key

Summary

This API allows a user to sign in and obtain an API key to use in subsequent API requests.

Use Cases (used by)

All clients accessing MetaDefender Vault REST must call this API first to obtain an API key.

The token required in the Authorization header is formed by joining the account's username and password, using the windows newline separator (CRLF - \r\n) as delimiter.

Example

Username: JohnDoe

Password: SecretPassword

Token: encodeBase64("JohnDoe\r\nSecretPassword")

Authorization: Basic Sm9obkRvZQ0KU2VjcmV0UGFzc3dvcmQ=

Auth

GET /vault_rest/authenticate

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/authenticate' \ --header 'Authorization: Basic {token}'
Copy

Responses

200

object object

Response

xxxxxxxxxx
 
{ "expires": "2017-05-10T09:36:09.5479468Z", "token": "rWx0PkJHv2G8C5FvvYCEqpj89SDct0", "user_id": 1}
Copy

Cancel Or Expire An API Key

Use Cases (used by)

Used by the user interface when the user logs out.

Auth

DELETE /vault_rest/authenticate

xxxxxxxxxx
 
curl --request DELETE \ --url 'http://localhost:8010/vault_rest/authenticate' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

object object

Response

xxxxxxxxxx
 
{ "token": "OrRnBd9J0AzTiUe4Xrevj6IUoHbdMs"}
Copy

Extend API Key

Summary

This API allows a user to extend an API key.

Use Cases (used by)

Used by clients that want to prevent an API to expire due to inactivity or change the expiration of an existing generated API key.

Auth

Headers

Token	string	The API key that you wish to extend. *Note: If this header is not present the API key from Authorization header will be used instead
ExtendBy	string	Parameter value must be a time span (hh:mm:ss) value how long to extend the API key. If this parameter is not specified a default server value is used. Max value is 24h: 23:59:59
ExtendUntil	number	Used to adjust 3rd party API key expiration date. Date should be specified in UTC, for example: 2016-01-02T12:00:00.0000000Z

Request Body

object object

PUT /vault_rest/token

xxxxxxxxxx
 
curl --request PUT \ --url 'http://localhost:8010/vault_rest/token' \ --header 'Token: RHjO1SH9GqjBAbGxFOh2jqI9HjNAJD' \ --header 'ExtendBy: 01:00:00' \ --header 'ExtendUntil: 2020-11-13T10:40:00.0000000Z' \ --header 'Authorization: Bearer {token}' \ --data '{}'
Copy

Responses

200

object object

Response

xxxxxxxxxx
 
{ "expires": "2017-05-09T13:31:44.7587334Z", "token": "f3I8Vss3cWAuh3EscB06QRDcQfMzHY", "user_id": 1}
Copy

Create A 3rd Party API Key

Summary

This API allows you to create API keys to be used by 3rd party applications.

Auth

Request Body

object object

POST /vault_rest/token

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/token' \ --header 'Authorization: Bearer {token}' \ --data '{  "expires": "2015-07-15T04:14:50.0000000Z",  "description": "Metadefender access token"}'
Copy

Responses

200

object object

Response

xxxxxxxxxx
 
{ "expires": "2018-07-15T04:14:50.0000000Z", "token": "OrRnBd9J0AzTiUe4Xrevj6IUoHbdMs", "user_id": 1}
Copy

Enumerate API Keys

Summary

Returns a list of API keys generated by this user to allow 3rd party applications to connect to MetaDefender Vault .

Use Cases

Used by the web user interface to display generated API keys.

Auth

Headers

sort_column	string	Possible values: Token, Created, Expires, Description, Role
sort_direction	string	Possible values, asc, desc
find	string	Searches Token & Description
findB64	string	Free text search string (Base64 encoded to support all charsets). Will override any value specified in 'find' header.

Path Params

start	integer	[required] Zero based position in list from where to start returning data
count	integer	[required] Maximum number of list entries to return

GET /vault_rest/tokens/{start}/{count}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/tokens/0/10' \ --header 'sort_column: Name of column to use when sorting ' \ --header 'sort_direction: Sorting direction' \ --header 'find: Free text search string' \ --header 'findB64: Free text search string (Base64 encoded)' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

object object

Response

xxxxxxxxxx
 
{ "filter_count": 2, "items": [  {   "token_id": 1,   "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",   "description": "Metadefender access token",   "status": "valid",   "created": "2015-07-02T12:00:00.0000000Z",   "expires": "2016-01-01T12:00:00.0000000Z",   "role": "guest"  },  {   "token_id": 2,   "token": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",   "description": "3rd party access token",   "status": "expired",   "created": "2015-01-02T12:00:00.0000000Z",   "expires": "2015-06-01T12:00:00.0000000Z",   "role": "user"  } ], "total_count": 2}
Copy

File Management

Overview

These APIs enable developers to check information about files uploaded in MetaDefender Vault.

GET

/vault_rest/file/{file_id}

DELETE

/vault_rest/file/{file_id}

PUT

/vault_rest/v2/move_files

PUT

/vault_rest/rename_file

POST

/vault_rest/update_file_share

GET

/vault_rest/file/status/{file_id}

GET

/vault_rest/files/{type}/{start}/{count}

DELETE

/vault_rest/files

GET

/vault_rest/file_tags/{file_id}

PUT

/vault_rest/file_tags

Download a file

Summary

This API call allows you to download the files stored in MetaDefender Vault.

The call should be made to vault_rest/file/{file_id} through a GET request. Please note that you need to obtain {file_id} in order to retrieve the file.

Auth

Path Params

file_id

string

[required] Id of the file you wish to download

GET /vault_rest/file/{file_id}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/file/%7Bfile_id%7D' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

file file

Response

xxxxxxxxxx
 
File Content
Copy

Delete A File

Summary

Delete a file from the MetaDefender Vault storage. This API will only mark the file for deletion. The file will be physically deleted by the background worker.

Permissions Restrictions

Administrators can delete any file, including other user's files. Users can only delete their own files.

Auth

Path Params

file_id

string

[required] ID of file to delete

DELETE /vault_rest/file/{file_id}

xxxxxxxxxx
 
curl --request DELETE \ --url 'http://localhost:8010/vault_rest/file/%7Bfile_id%7D' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Move A File

Summary

This API allows moving one or multiple files in MetaDefender Vault.

Auth

Request Body

object object

PUT /vault_rest/v2/move_files

xxxxxxxxxx
 
curl --request PUT \ --url 'http://localhost:8010/vault_rest/v2/move_files' \ --header 'Authorization: Bearer {token}' \ --data '{  "files": [    {      "file_id": "de5ae8d09fa5478aad61b3451b04bf57",      "name": "file1.pdf"    },    {      "file_id": "ee870ff020564d88bb46cd421711c968",      "name": "file2.txt"    },    {      "file_id": "849137c80bd443cca3c49328f4a32fe9",      "name": "file3.jpg"    }  ],  "new_path": "test"}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "successful_results": {  "entities": [   []  ],  "success_counter": 1 }, "failed_results": {  "entities": [],  "failed_counter": 0 }, "total_counter": 1}
Copy

Rename A File

Summary

This API allows renaming a file in MetaDefender Vault.

Auth

Request Body

object object

PUT /vault_rest/rename_file

xxxxxxxxxx
 
curl --request PUT \ --url 'http://localhost:8010/vault_rest/rename_file' \ --header 'Authorization: Bearer {token}' \ --data '{  "file_id": "849137c80bd443cca3c49328f4a32fe9",  "new_file_name": "test"}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Share A File

Summary

This API allows sharing a file in MetaDefender Vault.

Auth

Request Body

object object

POST /vault_rest/update_file_share

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/update_file_share' \ --header 'Authorization: Bearer {token}' \ --data '{  "fileId": "849137c80bd443cca3c49328f4a32fe9",  "groupIds": [    19  ],  "userIds": [    24  ]}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Query File status

Summary

This API lets you query the current status of a file in MetaDefender Vault.

Auth

Path Params

file_id

string

[required] File ID of MetaDefender Vault file returned by Upload file call.

GET /vault_rest/file/status/{file_id}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/file/status/%7Bfile_id%7D' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

object object

Response

xxxxxxxxxx
 
{ "administrator_approval_state": "ApprovalDisabled", "availability_state": "Available", "availability_state_key": "FILE_STATE_SANITIZED", "can_access_scan_results": true, "can_be_archived": true, "can_be_deleted": true, "can_be_downloaded": true, "can_be_moved": true, "can_be_permanently_deleted": true, "can_be_previewed": true, "can_be_rescanned": true, "can_update_file_password": true, "cdr_result_key": "Sanitized", "current_approval_count": 0, "dlp_result_key": "DLP_SENSITIVE_DATA_NOT_DETECTED", "duration": 920, "engines_verdict": {  "infected_engines": 0,  "total_engines": 17 }, "file_id": "7963c14842274e519d0fae185bf4aee7", "file_type": "OpenDocument Sheet", "is_blocked_by_core": false, "is_converted": true, "is_dlp_processed": false, "is_filescanned": false, "is_locked": false, "is_sanitized": true, "md5": "fd32786eb1865218da9b726c703c0841", "name": "Metadefender_MFT_a9d1a45fe6e0454da52207de71e6ab7a.ods", "processing_state": "Available", "processing_state_key": "PROCESSING_STATE_Available", "required_approval_count": 2, "sandbox_result_key": "FILE_INFO_SANDBOX_NOT_CONFIGURED", "scan_result": {  "actions_failed": "",  "blocked_reason": "",  "workflow_result": "Allowed" }, "scan_result_key": "METASCAN_RESULT_CORE_THREAT_NOT_FOUND", "sha1": "ddc07013e8bf3790312f5313674943912396a47e", "sha256": "ccde3c2e62245f9c6e998bb19a57c520b4b7d7572119219fd8f0979399ee6765", "supervisor_approval_state": "ApprovalDisabled", "supervisor_approval_state_key": "SUPERVISOR_APPROVAL_STATE_DISABLED", "supervisor_reason": "", "workflow": "MetaDefender Vault", "first_upload_time": "2024-01-10T11:41:57.0000000", "folder_id": "e801a217bd7c49189e01e3f1e8b9ada4", "is_file_owned": true, "path": "", "size": 3956}
Copy

Expand

Enumerate Files

Summary

Retrieve a list of the user's files.

Auth

Headers

sort_column	string	Possible values: expires, name, size
sort_direction	string	Possible values: asc, desc
find	string	Free text search string (Use only with English characters)
findB64	string	Free text search string (Base64 encoded to support all charsets). Will override any value specified in 'find' header.
columns	string	Possible values: SearchId, FileTransferId, Subject, Body, Sender, Recepiet, FileName
AvailabilityState	string	By default Files of all availability states are returned. To return files of certain states, specify them in the header (separate multiple states with a , (comma)) Possible states: Composing QueuedForProcessing BeingProcessed Available Expired Deleted Blocked BlockedNoSanitization ProcessingFailed

Path Params

type	string	[required] Return entries of this specific type. Possible values: my, all
start	string	[required] Zero based position in list from where to start returning data
count	string	[required] Maximum number of list entries to return

GET /vault_rest/files/{type}/{start}/{count}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/files/%7Btype%7D/%7Bstart%7D/%7Bcount%7D' \ --header 'sort_column: Name of column to use when sorting data' \ --header 'sort_direction: Sorting direction' \ --header 'find: Free text search string' \ --header 'findB64: Free text search string (Base64 encoded)' \ --header 'columns: Columns to search' \ --header 'AvailabilityState: Select one or more availability states' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

object object

Response

xxxxxxxxxx
 
{
 "filter_count": 4, "items": [...],
 "total_count": 4}
Copy

Delete Multiple Files

Summary

Delete a group of files from the MetaDefender Managed File Transfer storage. This API will only mark the files for deletion. The files will be physically removed by a background worker.

Permissions Restrictions

Administrators can delete any file, including other user's files. Users can only delete their own files.

Auth

Request Body

DELETE /vault_rest/files

xxxxxxxxxx
 
curl --request DELETE \ --url 'http://localhost:8010/vault_rest/files' \ --header 'Authorization: Bearer {token}' \ --data '[  "{file_id}",  "{other_file_id}"]'
Copy

Responses

200

object object

Response

xxxxxxxxxx
 
{ "successful_results": {  "entities": [   [],   []  ],  "success_counter": 2 }, "failed_results": {  "entities": [],  "failed_counter": 0 }, "total_count": 2}
Copy

Get file tags

This API endpoint, provides a list of {file_id} file's tags

Auth

GET /vault_rest/file_tags/{file_id}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/file_tags/{file_id}' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

string string

Response

xxxxxxxxxx
 
{ "tags": [  "file_tag1",  "file_tag2" ]}
Copy

Add/Modify file tags

This API endpoint, allows user to modify file tags

Auth

Request Body

object object

PUT /vault_rest/file_tags

xxxxxxxxxx
 
curl --request PUT \ --url 'http://localhost:8010/vault_rest/file_tags' \ --header 'Authorization: Bearer {token}' \ --data '{  "file_guid": "7743da0c40f645a48ae39caf1f454f6e",  "tags": [    "tag1",    "tag2"  ]}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

User Management

Overview

Manage users inside MetaDefender Vault.

/vault_rest/accounts/{type}/{start}/{count}

POST

/vault_rest/account

PUT

/vault_rest/accounts/{id}

DELETE

/vault_rest/accounts

GET

/vault_rest/account/{id}

Modify a guest account

This API endpoint, allows the user to remove guest account.

Auth

Request Body

object object

PUT /vault_rest/guest

xxxxxxxxxx
 
curl --request PUT \ --url 'http://localhost:8010/vault_rest/guest' \ --header 'Authorization: Bearer {token}' \ --data '{  "pin_code": "2a&XmQu7Q5ek",  "old_pin_code": "2a&XmQu7Q5ek",  "display_name": "",  "email": "",  "target_vault_id": 0,  "expires": "2024-02-10T11:07:00.0000000Z"}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "message": "null", "ui_message_key": "null"}
Copy

Create a guest account

This API endpoint, allows user to create guest account

Auth

Request Body

object object

POST /vault_rest/guest

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/guest' \ --header 'Authorization: Bearer {token}' \ --data '{  "expires": "2024-01-31T11:07:00.0000000Z",  "pin_code": "2a&XmQu7Q5ek",  "display_name": "",  "email": "",  "target_vault_id": 0}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Enumerate accounts

This API endpoint, with the {type} parameter supporting options like local, external, guest, or active directory, provides a response containing a list of accounts.

Auth

Headers

find	string	Free text search string
findB64	string	Free text search string (Base64 encoded to support all charsets). Will override any value specified in 'find' header.
sort_column	string	Allows users to specify the column by which the query results should be sorted.
sort_direction	string	Allows them to specify whether the results should be in ascending or descending order.

Path Params

start	string	[required] Zero based position in list from where to start returning data
count	string	[required] Maximum number of list entries to return
type	string	[required] Account type

GET /vault_rest/accounts/{type}/{start}/{count}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/accounts/%7Btype%7D/%7Bstart%7D/%7Bcount%7D' \ --header 'find: {find}' \ --header 'findB64: {findB64}' \ --header 'sort_column: {sort_column}' \ --header 'sort_direction: {sort_direction}' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

string string

Response

xxxxxxxxxx
 
{ "message": "null", "ui_message_key": "null", "filter_count": 1, "items": [  {   "message": "null",   "ui_message_key": "null",   "active_directory": "",   "can_be_deleted": false,   "can_be_edited": true,   "can_change_status": false,   "can_force_password_reset": true,   "company": "",   "core_rule": "null",   "created": "2024-01-24T09:26:08.0000000Z",   "display_name": "null",   "email": "admin@amin.com",   "expires": "9999-12-31T23:59:59.0000000Z",   "first_name": "admin",   "force_password_reset": false,   "groups": "",   "has_bound_keys": false,   "last_name": "admin",   "owner": "null",   "role": "Administrator",   "status": "Enabled",   "target_vault_id": 0,   "template_test_email": "null",   "user_id": 1,   "user_name": "admin"  } ], "total_count": 1}
Copy

Create an account

This API endpoint, allows user to create an account

Auth

Request Body

object object

POST /vault_rest/account

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/account' \ --header 'Authorization: Bearer {token}' \ --data '{  "first_name": "John",  "last_name": "Doe",  "display_name": "John Doe",  "user_name": "JohnD",  "password": "password",  "email": "jdoe@opswat.com",  "role": "user",  "expires": "2019-07-15T04:14:50.0000000Z"}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
{ "message": "null", "ui_message_key": "null"}
Copy

Modify an account

This API endpoint, allows user to modify an account

Auth

Path Params

string

Account id

Request Body

object object

PUT /vault_rest/accounts/{id}

xxxxxxxxxx
 
curl --request PUT \ --url 'http://localhost:8010/vault_rest/accounts/%7Bid%7D' \ --header 'Authorization: Bearer {token}' \ --data '{  "first_name": "John",  "last_name": "Doe",  "user_name": "johnDoe",  "email": "john@doe.com",  "expires": "2024-03-22T13:21:24.000Z",  "role": "{Account Type}",  "force_password_reset": false,  "core_rule": ""}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "message": "null", "ui_message_key": "null"}
Copy

Delete account(s)

This API endpoint, allows the removal of a user account, permanently erasing associated data and terminating access.

Auth

Request Body

object object

DELETE /vault_rest/accounts

xxxxxxxxxx
 
curl --request DELETE \ --url 'http://localhost:8010/vault_rest/accounts' \ --header 'Authorization: Bearer {token}' \ --data '{  "account_ids": [    "account_id"  ]}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "successful_results": {  "entities": [],  "success_counter": 2 }, "failed_results": {  "entities": [],  "failed_counter": 0 }, "total_count": 2}
Copy

Get account details

This API endpoint, allows user to get an account's detailed info

Auth

GET /vault_rest/account/{id}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/account/{id}' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
{ "active_directory": "", "can_be_deleted": true, "can_be_edited": true, "can_change_status": true, "can_force_password_reset": false, "company": "", "core_rule": "", "created": "2024-03-14T14:32:53.0000000Z", "display_name": "MFT Admin", "email": "admin@mft.test", "expires": "9999-12-31T23:59:59.0000000Z", "first_name": "MFT", "force_password_reset": false, "groups": "", "has_bound_keys": false, "is_excluded_from_supervision_flow": false, "is_third_party_user": true, "last_name": "Admin", "owner": 1, "role": "ThirdPartyUser", "status": "Enabled", "target_mft_ids": [], "template_test_email": "", "user_id": 19, "user_name": "mft.admin"}
Copy

Archive Download

Overview

These APIs enable downloading of multiple files or folders as an archive from MetaDefender Vault.

Workflow

In order to start the process please follow these steps:

Create an archive by calling Create Archive
Wait until the archive is created by polling Get Archive Status
Once the archive is available, you can obtain it by calling Download Archive

Error Handling

If an error prevents you from downloading the archive or you simply wish to stop the process or discard the archive, you can call Cancel Archive Download. Please note that it’s not mandatory to call this endpoint after a successful download because there is an automatic cleanup mechanism that will remove archives after they are downloaded.

PUT

/vault_rest/cancel_archive_download/{id}

POST

/vault_rest/create_archive_download

GET

/vault_rest/archive_download/{id}

GET

/vault_rest/archive_download_status/{id}

Cancel Archive Download

Summary

This API allows the cancelation of a previously created archive.

Auth

Path Params

string

[required] Unique identifier of the archive to be canceled

Request Body

object object

PUT /vault_rest/cancel_archive_download/{id}

xxxxxxxxxx
 
curl --request PUT \ --url 'http://localhost:8010/vault_rest/cancel_archive_download/%7Bid%7D' \ --header 'Authorization: Bearer {token}' \ --data '{}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Create Archive

Summary

This API allows creating an archive containing multiple folders and files from MetaDefender Vault. This API will only initiate the archiving process, you need to use Get Archive Status to obtain the status of the archiving process and then download it.

Auth

Request Body

object object

POST /vault_rest/create_archive_download

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/create_archive_download' \ --header 'Authorization: Bearer {token}' \ --data '{  "file_ids": [    "83018a5dd3164c65a5f75aaad073d7fb",    "1887462f7bd4492092ff55381cf03421"  ],  "folder_ids": [    "a8132e0e01d34ee187ba85017fc413c7",    "048c5e1e939c4c388554d81809af09cd"  ]}'
Copy

Responses

200

string string

Response

xxxxxxxxxx
 
{    "archive": {        "guid": "9b0e005b063a4e71b2c1531f15f1a361",        "total_file_count": 11    }}
Copy

Download Archive

Summary

This API downloads an archive from MetaDefender Vault.

Auth

Path Params

string

[required] Unique identifier of the public archive.

GET /vault_rest/archive_download/{id}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/archive_download/%7Bid%7D' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Get Archive Status

Auth

Path Params

string

[required] Unique identifier of the archive.

GET /vault_rest/archive_download_status/{id}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/archive_download_status/%7Bid%7D' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Audit Events

Overview

View and export audit events.

GET

/vault_rest/audit/{start}/{count}

GET

/vault_rest/audit/export

Enumerate Audit Events

Auth

Headers

sort_column	string	Possible values: date, description, event, location, status, user
sort_direction	string	Possible values: asc, desc
find	string	Free text search string
findB64	string	Free text search string (Base64 encoded to support all charsets). Will override any value specified in 'find' header.

Path Params

start	string	[required] Zero based position in list from where to start returning data
count	string	[required] Maximum number of list entries to return

GET /vault_rest/audit/{start}/{count}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/audit/%7Bstart%7D/%7Bcount%7D' \ --header 'sort_column: Name of column to use when sorting data' \ --header 'sort_direction: Sorting direction' \ --header 'find: Free text search string' \ --header 'findB64: Free text search string (Base64 encoded)'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Export Audit Events

Auth

Query String

locale string

GET /vault_rest/audit/export

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/audit/export' \ --header 'Authorization: Bearer {token}' \ --data locale=locale-en_US
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

File Upload

Workflow

To upload one or more files in chunks to MetaDefender Vault , follow the workflow below:

Create a transfer group by calling Initialize Group Transfer
Create a file transfer by calling Initialize File Transfer
Upload file chunks by calling Upload file chunk until the complete file is uploaded
Call Complete File Transfer to commit the uploaded file in MetaDefender Vault .
Repeat step 2 - 4 to upload additional files in the same group.
Call Complete Group Transfer to commit the transfer in MetaDefender Vault and make it available for download.

Error Handling

During steps 3 to 5, it is possible to delete a partially/completely uploaded file by calling Delete File From File Transfer

During steps 2 to 5, it is possible to delete a group transfer (including any uploaded files) by calling Delete Group Transfer

/vault_rest/transfer_file

POST

/vault_rest/transfer_file

DELETE

/vault_rest/transfer_file

PATCH

/vault_rest/transfer_file

Initialize group transfer

Permissions Restrictions

Even if the current API method is open to multiple user roles (i.e. Administrator and User), only the Administrator has a full set of permissions.

Administrators can impersonate users, or even other administrators.

For the User role, the permissions apply an even more strict rules set: they can only upload files in their own account - they don't have any impersonation rights. Although it's not something that applies directly to the current API method, it is worth mentioning that after a transfer has been started (i.e. this method has been called successfully), the other transfer methods (e.g. Init file transfer, Patch file, Complete File, etc.) will only be accessible to the user that has initiated the transfer (the one who's API key was used to make this request). No other user can alter a transfer that's in progress.

Auth

Headers

group_id	string	A unique transfer group id can be transmitted to support Diode scenarios. If no id has been specified MetaDefender Vault will generate a unique id. Must be a valid v4 UUID (RFC4122 standard).
impersonate_as	string	Must be a valid user or email address Note: please use impersonate_as header because send_as will be deprecated.
share_with	string	Must be one or more valid users or email addresses. Separate multiple entries with a comma (,). Note: please use share_with header because recipients will be deprecated.
subject	string
message	string
source	string	0 = REST (default) 1 = Kiosk 2 = WebUI

GET /vault_rest/transfer

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/transfer' \ --header 'group_id: A unique transfer group id.' \ --header 'impersonate_as: A username that you wish to impersonate and send files on behalf of.' \ --header 'share_with: A list of usernames or email addresses to share the files with.' \ --header 'subject: File Transfer Subject' \ --header 'message: File Transfer Body Message' \ --header 'source: Origin of transfer' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "group_id": "2b6dea8f2fed49f5a5bb61c766394f45", "owner": {  "email": "testuser@email.com",  "first_name": "Levi",  "is_impersonated": false,  "last_name": "Kim",  "username": "Levi" }, "shared_with": [  {   "email": "testuser@email.com",   "id": 1,   "username": "Levi"  } ]}
Copy

Complete group transfer

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.

Auth

Headers

group_id

string

A transfer group id obtained from the Initialize Group Transfer call.

expires_after

string

Specify in DD:HH:MM:SS. Cannot be combined with 'expires' property.

The value ranges are the following:

Days, ranging from 1 to 9999;
Hours, ranging from 0 to 23;
Minutes, ranging from 0 to 59;
Optional seconds, ranging from 0 to 59.

POST /vault_rest/transfer

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/transfer' \ --header 'group_id: Transfer group ID.' \ --header 'expires_after: Expiration for each file in this transfer.' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "files": []}
Copy

Delete Group Transfer

Permissions Restrictions

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.

Auth

Headers

group_id

string

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

DELETE /vault_rest/transfer

xxxxxxxxxx
 
curl --request DELETE \ --url 'http://localhost:8010/vault_rest/transfer' \ --header 'group_id: A unique transfer group id.' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "result": "Success", "group_id": "735a13155d044f869953832973c76d81"}
Copy

Initialize File Transfer

Permissions Restrictions

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.

Auth

Headers

transfer_method	string	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	string	A transfer group id obtains from the 1. Initialize Group Transfer call.
file_size	string	The size in bytes of the complete file to be transferred.
file_name	string	The name of the file to be transferred. The file name can't contain special characters such as / or \.
path	string	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	string	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	string	Used to verify data integrity when upload has been completed. The hashing algorithm used is SHA256.
user_agent	string	See https://onlinehelp.opswat.com/corev4/8.1.3.1._Process_a_file.html for more details. Leave this field empty in order to use the user_agent defined in Core Integration settings.
core_rule	string	See https://onlinehelp.opswat.com/corev4/8.1.3.1._Process_a_file.html for more details.
archivepwdX	string	Multiple passwords is also supported, format: archivepwd X: Could be empty When having value, X must be a number >= 1 archivepwd1: <password 1> archivepwd2: <password 2> archivepwd3: <password 3> ... archivepwdN: Each archivepwd 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.

Expand

GET /vault_rest/transfer_file

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/transfer_file' \ --header 'transfer_method: Specify the method of transferring chunks.' \ --header 'group_id: A unique transfer group id.' \ --header 'file_size: The total file size.' \ --header 'file_name: Object file name' \ --header 'path: Path to the folder where you wish to upload the file.' \ --header 'file_id: A unique file id.' \ --header 'file_checksum: The SHA256 hash of the file content.' \ --header 'user_agent: Client identification to send to MetaDefender Core.' \ --header 'core_rule: Name of the rule to send to MetaDefender Core.' \ --header 'archivepwdX: One or more passwords for the file.' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "message": "File record created", "file_id": "17bc10b5c0dd438aa263ad0c9042c30e"}
Copy

Complete file transfer

Permissions Restrictions

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.

Auth

Headers

group_id	string	A transfer group id obtained from the Initialize Group Transfer call.
file_id	string	A file ID obtained from the Initialize File Transfer call.

POST /vault_rest/transfer_file

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/transfer_file' \ --header 'group_id: Transfer group ID.' \ --header 'file_id: File ID.' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "result": "Success"}
Copy

Delete File From File Transfer

Permissions Restrictions

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.

Auth

Headers

group_id	string	A transfer group id obtains from the Initialize Group Transfer call.
file_id	string	A file id obtained from the Initialize File Transfer call.

DELETE /vault_rest/transfer_file

xxxxxxxxxx
 
curl --request DELETE \ --url 'http://localhost:8010/vault_rest/transfer_file' \ --header 'group_id: A unique transfer group id.' \ --header 'file_id: A unique file id.' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "result": "Success", "file_id": "00000000000000000000000000000000"}
Copy

Upload File Chunk

Permissions Restrictions

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.

Auth

Headers

group_id	string	A transfer group id obtained from the 1. Initialize Group Transfer call.
file_id	string	A file ID obtained from a call to "Initialize File Transfer".
chunk_offset	string	The offset (location) of the chunk in the reassembled file.
chunk_checksum	string	Used to verify data integrity when chunk has been received. If no value is provided no checksum will be performed.

Request Body

object object

PATCH /vault_rest/transfer_file

xxxxxxxxxx
 
curl --request PATCH \ --url 'http://localhost:8010/vault_rest/transfer_file' \ --header 'group_id: Transfer group id.' \ --header 'file_id: File id.' \ --header 'chunk_offset: Chunk offset.' \ --header 'chunk_checksum: The SHA256 hash of the chunk data.' \ --header 'Authorization: Bearer {token}' \ --data-binary '{}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "result": "Success"}
Copy

Folder Management

Overview

These APIs enable developers to check information about folders in MetaDefender Vault.

DELETE

/vault_rest/folder/{folder_id}

DELETE

/vault_rest/folders

GET

/vault_rest/folder_content/{id}/{start}/{count}

GET

/vault_rest/folder_search/{id}/{start}/{count}

GET

/vault_rest/root_folder

PUT

/vault_rest/v2/move_folders

PUT

/vault_rest/rename_folder

POST

/vault_rest/update_folder_share

POST

/vault_rest/folder

Delete A Folder

Summary

Delete a folder from the MetaDefender Vault storage. This API will only mark the folder for deletion. The folder will be physically deleted by the background worker.

Permissions Restrictions

Administrators can delete any folder, including other user's folders. Users can only delete their own folders.

Auth

Path Params

folder_id

string

[required]

DELETE /vault_rest/folder/{folder_id}

xxxxxxxxxx
 
curl --request DELETE \ --url 'http://localhost:8010/vault_rest/folder/ID%20of%20folder%20to%20delete.' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Delete Multiple Folders

Summary

Delete a group of folders from the MetaDefender Vault storage. This API will only mark the folders for deletion. The folders will be physically removed by a background worker.

Permissions Restrictions

Administrators can delete any folder, including other user's folders. Users can only delete their own folders.

Auth

DELETE /vault_rest/folders

xxxxxxxxxx
 
curl --request DELETE \ --url 'http://localhost:8010/vault_rest/folders' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Enumerate Folder Content

Summary

Retrieve a list of the user's files.

Auth

Headers

sort_column	string	Possible values: name, size, datecreated.
sort_direction	string	Possible values: asc, desc.
find	string	Free text search string (Use only with English characters).
findB64	string	Free text search string (Base64 encoded to support all charsets). Will override any value specified in 'find' header.

Path Params

id	string	[required]
start	string	[required]
count	string	[required]

GET /vault_rest/folder_content/{id}/{start}/{count}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/folder_content/Unique%20identifier%20of%20the%20folder/Zero%20based%20position%20in%20list%20from%20where%20to%20start%20returning%20data./Maximum%20number%20of%20list%20entries%20to%20return.' \ --header 'sort_column: Name of column to use when sorting data.' \ --header 'sort_direction: Sorting direction.' \ --header 'find: Free text search string.' \ --header 'findB64: Free text search string (Base64 encoded).' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Folder Search

Summary

Retrieve a list of the user's folders and files starting from a specified folder and filtered by a search string.

Auth

Headers

sort_column	string	Possible values: name, size, datecreated.
sort_direction	string	Possible values: asc, desc.
find	string	Free text search string (Use only with English characters).
findB64	string	Free text search string (Base64 encoded to support all charsets). Will override any value specified in 'find' header.

Path Params

id	string	[required]
start	string	[required]
count	string	[required]

GET /vault_rest/folder_search/{id}/{start}/{count}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/folder_search/Unique%20identifier%20of%20folder%3B%20this%20is%20the%20starting%20place%20for%20the%20search./Zero%20based%20position%20in%20list%20from%20where%20to%20start%20returning%20data./Maximum%20number%20of%20list%20entries%20to%20return.' \ --header 'sort_column: Name of column to use when sorting data.' \ --header 'sort_direction: Sorting direction.' \ --header 'find: Free text search string.' \ --header 'findB64: Free text search string (Base64 encoded).' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Get Root Folder

Summary

List information about the 'root' folder.

Auth

GET /vault_rest/root_folder

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/root_folder' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "availability_state": "Available", "can_update_sharing": true, "folder_id": "755d264f42d146d29641594c689ccb16", "name": "", "owner": "John Doe", "owner_id": 1, "path": "", "folder_path_list": [  {   "availability_state": "Available",   "can_update_sharing": true,   "folder_id": "755d264f42d146d29641594c689ccb16",   "name": "",   "owner": "John Doe",   "owner_id": 1,   "path": ""  } ]}
Copy

Move Folders

Summary

This API allows moving one or multiple folders in MetaDefender Vault.

Auth

Request Body

object object

PUT /vault_rest/v2/move_folders

xxxxxxxxxx
 
curl --request PUT \ --url 'http://localhost:8010/vault_rest/v2/move_folders' \ --header 'Authorization: Bearer {token}' \ --data '{  "folders": [    {      "folder_id": "c5133a2deb5a4f4798b45731cc1bcda9",      "name": "folder3",      "path": "test\\folder3"    },    {      "folder_id": "433beb56d2c94effb24bccdce6823a7b",      "name": "folder2",      "path": "test\\folder2"    },    {      "folder_id": "4db39640b3ef4f068b66ead001f5bbd2",      "name": "folder1",      "path": "test\\folder1"    }  ],  "new_path": ""}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "successful_results": {  "entities": [   []  ],  "success_counter": 1 }, "failed_results": {  "entities": [   {    "message": "The destination folder already contains a folder with the same name",    "ui_message_key": "API_FOLDER_MOVE_DESTINATION_HAS_FOLDER_WITH_SAME_NAME"   }  ],  "failed_counter": 1 }, "total_count": 2}
Copy

Rename A Folder

Summary

This API allows renaming a folder in MetaDefender Vault.

Auth

Request Body

object object

PUT /vault_rest/rename_folder

xxxxxxxxxx
 
curl --request PUT \ --url 'http://localhost:8010/vault_rest/rename_folder' \ --header 'Authorization: Bearer {token}' \ --data '{  "folder_id": "2927ac9127dd472198f30f907c67bdac",  "new_folder_name": "test"}'
Copy

Responses

200

Successful response

No response body

409

Conflict

Response

xxxxxxxxxx
 
No response
Copy

Share A Folder

Summary

This API allows sharing a folder in MetaDefender Vault.

Auth

Request Body

object object

POST /vault_rest/update_folder_share

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/update_folder_share' \ --header 'Authorization: Bearer {token}' \ --data '{  "folderId": "2927ac9127dd472198f30f907c67bdac",  "userIds": [    26  ]}'
Copy

Responses

200

Successful response

No response body

Response

xxxxxxxxxx
 
No response
Copy

Create A Folder

Summary

This API allows creating a folder in MetaDefender Vault.

Auth

Request Body

object object

POST /vault_rest/folder

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/folder' \ --header 'Authorization: Bearer {token}' \ --data '{  "name": "vault",  "path": "test\\folder1"}'
Copy

Responses

200

Successful response

object object

400

Bad Request

409

Conflict

Response

xxxxxxxxxx
 
{ "folder_guid": "6d57cca3f1134f7ca914186e642389d1", "folder_name": "vault"}
Copy

Default

GET

/vault_rest/version

Version

Auth

Headers

Authorization string

GET /vault_rest/version

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/version' \ --header 'Authorization: Bearer {{BearerToken}}'
Copy

Responses

200

Successful response

object object

Response

xxxxxxxxxx
 
{ "version": "1.0.0.0"}
Copy