Control Center v2.6.0 Terms of Service Apache 2.0

Developer Guide

This is the API documentation for MetaDefender Cluster Control Center Public API. If you would like to evaluate or have any questions about this documentation, please contact us via our Contact Us form.

How to Interact with MetaDefender Cluster Control Center using REST API

The MetaDefender Cluster Control Center empowers administrators and system engineers to efficiently manage system operations, including:

Establishing and maintaining essential service connections.
Deploying and managing MetaDefender Core, MetaDefender Cluster API Gateway instances.
Managing licenses.
Administering user accounts and access controls.
Configuring and enforcing security protocols.
Monitoring the overall system health and system performance.

OPSWAT recommends using the JSON-based REST API. The available methods are documented below.

OPSWAT provides some sample codes on GitHub to make it easier to understand how the MetaDefender REST API works.

Server

http://localhost:8892

Authentication

apiKey apikey

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Fields

Key	In
apikey	Header

Auth

Authentication APIs

User authentication is done via username & password.

Login

Initiate a new session. Required for using protected REST APIs.

Auth

Request Body

object	object
user	string	Username
password	string	User's password

POST /login

 
curl --request POST \ --url 'http://localhost:8892/login' \ --data '{  "user": "admin",  "password": "admin"}'
Copy

Responses

200

object	object
oms-csrf-token	string	The randomly generated token used to prevent CSRF attacks
session_id	string	The apikey used to make API calls which requires authentication

403

Invalid credentials

500

Unexpected event on server

Response

 
{ "oms-csrf-token": "ZWU3NDJkNDcwMzQ4NWNlNGUzOTFjMGJiNDFkZDQ4ZWM=", "session_id": "a5dd6114dbd14a3b8f4577b7b54e6b0a"}
Copy

Logout

Destroy session for not using protected REST APIs.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

POST /logout

 
curl --request POST \ --url 'http://localhost:8892/logout' \ --header 'apikey: {apikey}'
Copy

Responses

200

object	object
response	string

400

Bad Request.

403

Invalid user information.

500

Unexpected event on server

Response

 
{ "response": "Logout success"}
Copy

User Management

User management APIs

The APIs for manage users and user directories.

/admin/user/{user_id}

POST

/user/changepassword

Create user

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object	User object in MetaDefender.
api_key	string	Associated apikey with this user
directory_id	integer	To which User Directories belongs to (LOCAL/System/etc.)
display_name	string	Which is the name showed in the Management Console
email	string	User's email address
name	string	User's full name
description	string	User's description, 256 characters maximum
roles	array[string]	A list of roles attached to this user
ui_settings	object	Configuration of Management Console for this user. `refresh_rate` the refresh rate of the Management Console in seconds. Must not be negative. `engine_time_period` the time period for Technology results on the Usage page, in hours. Must be non-negative. `processing_chart_time_period` the time period for the Processing chart on the Usage page, in hours. Must be non-negative. `summary_time_period` the time period for the Summary data on the Usage page, in hours. Must be non-negative.
password	string	The user's password

POST /admin/user

 
curl --request POST \ --url 'http://localhost:8892/admin/user' \ --header 'apikey: {apikey}' \ --data '{  "api_key": "b8a4b52f19de88e365aa4f7e403fa91b352f",  "directory_id": 1,  "display_name": "jsmith",  "email": "john.smith@company.com",  "name": "John Smith",  "description": "This is a user description",  "roles": [    "1",    "2",    "3",    "..."  ],  "ui_settings": {    "refresh_rate": {      "value": 30    },    "engine_time_period": {      "value": 24,      "unitsInHour": 1    },    "processing_chart_time_period": {      "value": 24,      "unitsInHour": 1    },    "summary_time_period": {      "value": 24,      "unitsInHour": 1    }  },  "password": "HG&B*!C!KLEF#RH*#*(($YB"}'
Copy

Responses

200

Request processed successfully.

object	object	User object in MetaDefender.
api_key	string	Associated apikey with this user
directory_id	integer	To which User Directories belongs to (LOCAL/System/etc.)
display_name	string	Which is the name showed in the Management Console
email	string	User's email address
name	string	User's full name
description	string	User's description, 256 characters maximum
roles	array[string]	A list of roles attached to this user
ui_settings	object	Configuration of Management Console for this user.

400

Bad Request (e.g. invalid header, invalid request body).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "api_key": "b8a4b52f19de88e365aa4f7e403fa91b352f", "directory_id": 1, "display_name": "jsmith", "email": "john.smith@company.com", "name": "John Smith", "description": "This is a user description", "roles": [  "1",  "2",  "3",  "..." ], "ui_settings": {  "refresh_rate": {   "value": 30  },  "engine_time_period": {   "value": 24,   "unitsInHour": 1  },  "processing_chart_time_period": {   "value": 24,   "unitsInHour": 1  },  "summary_time_period": {   "value": 24,   "unitsInHour": 1  } }}
Copy

List all users

Returns a list of all users in the server.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /admin/user

 
curl --get \ --url 'http://localhost:8892/admin/user' \ --header 'apikey: {apikey}'
Copy

Responses

200

List of users retrieved successfully.

array	array[object]
api_key	string	Associated apikey with this user
directory_id	integer	To which User Directories belongs to (LOCAL/System/etc.)
display_name	string	Which is the name showed in the Management Console
email	string	User's email address
id	integer	User's unique identifier
name	string	User's full name
description	string	User's description, 256 characters maximum
roles	array[string]	A list of roles attached to this user
ui_settings	object	Configuration of Management Console for this user.

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
[ {  "api_key": "b8a4b52f19de88e365aa4f7e403fa91b352f",  "directory_id": 1,  "display_name": "jsmith",  "email": "john.smith@company.com",  "id": 1,  "name": "John Smith",  "description": "This is a user description",  "roles": [   "1",   "2",   "3",   "..."  ],  "ui_settings": {   "refresh_rate": {    "value": 30   },   "time_period": {    "value": 24,    "unitsInHour": 1   }  } }]
Copy

Delete a user

Delete a user by id from the system.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

DELETE /admin/user/{user_id}

 
curl --request DELETE \ --url 'http://localhost:8892/admin/user/{user_id}' \ --header 'apikey: {apikey}'
Copy

Responses

200

Request processed successfully.

object object

403

Invalid user information or Not Allowed

404

Requests resource was not found.

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "result": "Success"}
Copy

Change Password for local user

Modify the current password for the user identified by apikey

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object
old_password	string	The current password in plain text
new_password	string	The new password in plain text

POST /user/changepassword

 
curl --request POST \ --url 'http://localhost:8892/user/changepassword' \ --header 'apikey: {apikey}' \ --data '{  "old_password": "admin",  "new_password": "123456"}'
Copy

Responses

200

Request processed successfully

object	object
result	string

400

Bad Request (e.g. invalid header, invalid request body).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "result": "Success"}
Copy

Admin

Admin specific API requests.

/admin/role/{role_id}

List all user directories

Retrieve a list of all user directories configured in the system.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /admin/userdirectory

 
curl --get \ --url 'http://localhost:8892/admin/userdirectory' \ --header 'apikey: {apikey}'
Copy

Responses

200

List of user directories retrieved successfully.

array	array[object]
id	integer	Internal used identifier
name	string	Name of the user directory
type	string	Type of the user directory (e.g., LDAP, Local, etc.)
enabled	boolean	If the user directory is enabled or not
lockout_attempts	integer	Number of failed login attempts before the user is locked out
lockout_timeout	integer	Time in seconds before the user can try to log in again after being locked out

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
[ {  "id": 1,  "name": "SYSTEM",  "type": "Local",  "enabled": true,  "lockout_attempts": 5,  "lockout_timeout": 300 }]
Copy

Create new role

Add a new user role to the system.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object	MetaDefender user role describing object.
name	string	The name identifier of the role
display_name	string	The extended name showed in the Management Console.
rights	object	A list of rights for each permission
cert	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
configlog	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
engines	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
license	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
retention	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
rule	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
scanlog	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
update	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
updatelog	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
users	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
workflow	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
zone	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
healthcheck	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
fetch	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
download	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
deployment	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
service	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
packageupload	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`

POST /admin/role

 
curl --request POST \ --url 'http://localhost:8892/admin/role' \ --header 'apikey: {apikey}' \ --data '{  "name": "new_role",  "display_name": "New MetaDefender User Role",  "rights": {    "cert": [      "read",      "write"    ],    "configlog": [      "read",      "write"    ],    "engines": [      "read",      "write"    ],    "license": [      "read",      "write"    ],    "retention": [      "read",      "write"    ],    "rule": [      "read",      "write"    ],    "scanlog": [      "read",      "write"    ],    "update": [      "read",      "write"    ],    "updatelog": [      "read",      "write"    ],    "users": [      "read",      "write"    ],    "workflow": [      "read",      "write"    ],    "zone": [      "read",      "write"    ],    "healthcheck": [      "read",      "write"    ],    "fetch": [      "read",      "write"    ],    "download": [      "read",      "write"    ],    "deployment": [      "read",      "write"    ],    "service": [      "read",      "write"    ],    "packageupload": [      "read",      "write"    ]  }}'
Copy

Responses

200

Request processed successfully

object	object	MetaDefender user role describing object.
name	string	The name identifier of the role
display_name	string	The extended name showed in the Management Console.
rights	object	A list of rights for each permission
cert	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
configlog	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
engines	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
license	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
retention	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
rule	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
scanlog	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
update	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
updatelog	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
users	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
workflow	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
zone	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
healthcheck	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
fetch	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
download	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
deployment	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
service	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
packageupload	array[string]	An object defining the permission set allowed on MetaDefender individual role. Enum: `read`,`write`
editable	boolean	If the role can be altered or not.
id	integer	Internal used identifier

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "name": "new_role", "display_name": "New MetaDefender User Role", "rights": {  "cert": [   "read",   "write"  ],  "configlog": [   "read",   "write"  ],  "engines": [   "read",   "write"  ],  "license": [   "read",   "write"  ],  "retention": [   "read",   "write"  ],  "rule": [   "read",   "write"  ],  "scanlog": [   "read",   "write"  ],  "update": [   "read",   "write"  ],  "updatelog": [   "read",   "write"  ],  "users": [   "read",   "write"  ],  "workflow": [   "read",   "write"  ],  "zone": [   "read",   "write"  ],  "healthcheck": [   "read",   "write"  ],  "fetch": [   "read",   "write"  ],  "download": [   "read",   "write"  ],  "deployment": [   "read",   "write"  ],  "service": [   "read",   "write"  ],  "packageupload": [   "read",   "write"  ] }, "editable": true, "id": 6}
Copy

Delete a role

Delete a role by id from the system.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

DELETE /admin/role/{role_id}

 
curl --request DELETE \ --url 'http://localhost:8892/admin/role/{role_id}' \ --header 'apikey: {apikey}'
Copy

Responses

200

Request processed successfully.

object object

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "result": "Success"}
Copy

Config

Configure the product through APIs (especially the Settings). Will require admin apikey..

PUT

/admin/config/auditlog/cleanup

PUT

/admin/config/filestorage/cleanup

PUT

/admin/config/warehouse/cleanup

PUT

/admin/config/scanhistory/cleanup

PUT

/admin/config/session

GET

/admin/config/sessioncookie

PUT

/admin/config/sessioncookie

Audit clean up

Setting audit record cleanup time ( cleanup records older than).

Note: The cleanup range is defined in hours.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object
cleanuprange	integer	The number of hours of data retention. Anything older than this number will be deleted. Note: If `cleanuprange` is `0`, the cleanup functionality will be disabled.

PUT /admin/config/auditlog/cleanup

 
curl --request PUT \ --url 'http://localhost:8892/admin/config/auditlog/cleanup' \ --header 'apikey: {apikey}' \ --data '{  "cleanuprange": 24}'
Copy

Responses

200

Request processed successfully

object	object
cleanuprange	integer	The number of hours of data retention. Anything older than this number will be deleted.

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "cleanuprange": 24}
Copy

File storage clean up

Setting file storage clean up time (clean up records older than).

Note:The clean up range is defined in hours.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object
cleanuprange	integer	The number of hours of data retention. Anything older than this number will be deleted. Note: If `cleanuprange` is `0`, the cleanup functionality will be disabled.

PUT /admin/config/filestorage/cleanup

 
curl --request PUT \ --url 'http://localhost:8892/admin/config/filestorage/cleanup' \ --header 'apikey: {apikey}' \ --data '{  "cleanuprange": 24}'
Copy

Responses

200

Request processed successfully

object	object
cleanuprange	integer	The number of hours of data retention. Anything older than this number will be deleted.

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "cleanuprange": 24}
Copy

Executive report clean up

Setting executive report clean up time (clean up records older than).

Note:The clean up range is defined in hours.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object
cleanuprange	integer	The number of hours of data retention. Anything older than this number will be deleted. Note: If `cleanuprange` is `0`, the cleanup functionality will be disabled.

PUT /admin/config/warehouse/cleanup

 
curl --request PUT \ --url 'http://localhost:8892/admin/config/warehouse/cleanup' \ --header 'apikey: {apikey}' \ --data '{  "cleanuprange": 24}'
Copy

Responses

200

Request processed successfully

object	object
cleanuprange	integer	The number of hours of data retention. Anything older than this number will be deleted.

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "cleanuprange": 24}
Copy

Processing history clean up

Setting processing history clean up time (clean up records older than).

Note:The clean up range is defined in hours.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object
cleanuprange	integer	The number of hours of data retention. Anything older than this number will be deleted. Note: If `cleanuprange` is `0`, the cleanup functionality will be disabled.

PUT /admin/config/scanhistory/cleanup

 
curl --request PUT \ --url 'http://localhost:8892/admin/config/scanhistory/cleanup' \ --header 'apikey: {apikey}' \ --data '{  "cleanuprange": 24}'
Copy

Responses

200

Request processed successfully

object	object
cleanuprange	integer	The number of hours of data retention. Anything older than this number will be deleted.

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "cleanuprange": 24}
Copy

Session settings

Configure settings for session generated upon a successful login See more at Login

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object	API object for /admin/config/session
absoluteSessionTimeout	integer	The interval (in milliseconds) for overall session length timeout (regardless of activity).
allowCrossIpSessions	boolean	Allow requests from the same user to come from different IPs.
allowDuplicateSession	boolean	Allow same user to have multiple active sessions.
sessionTimeout	integer	The interval (in milliseconds) for the user's session timeout, based on last activity. Timer starts after the last activity for the apikey.

PUT /admin/config/session

 
curl --request PUT \ --url 'http://localhost:8892/admin/config/session' \ --header 'apikey: {apikey}' \ --data '{  "absoluteSessionTimeout": 0,  "allowCrossIpSessions": true,  "allowDuplicateSession": true,  "sessionTimeout": 300000}'
Copy

Responses

200

Request processed successfully

object	object	API object for /admin/config/session
absoluteSessionTimeout	integer	The interval (in milliseconds) for overall session length timeout (regardless of activity).
allowCrossIpSessions	boolean	Allow requests from the same user to come from different IPs.
allowDuplicateSession	boolean	Allow same user to have multiple active sessions.
sessionTimeout	integer	The interval (in milliseconds) for the user's session timeout, based on last activity. Timer starts after the last activity for the apikey.

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "absoluteSessionTimeout": 0, "allowCrossIpSessions": true, "allowDuplicateSession": true, "sessionTimeout": 300000}
Copy

Get session cookie attributes

Getting session cookie attributes

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /admin/config/sessioncookie

 
curl --get \ --url 'http://localhost:8892/admin/config/sessioncookie' \ --header 'apikey: {apikey}'
Copy

Responses

200

Request processed successfully.

object

Session cookie configuration details.

samesite

number

SameSite attribute accepts three values:

Strict - cookies will only be sent in a first-party context, not be sent along with requests initiated by third party websites.
Lax - cookies are not sent on normal cross-site subrequests, but are sent when a user is navigating to the origin site.
None - cookies will be sent in all contexts.

Default value: Lax

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "samesite": "Strict"}
Copy

Update session cookie attributes

Modifying session cookie attributes

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object

Session cookie configuration details.

samesite

number

SameSite attribute accepts three values:

Strict - cookies will only be sent in a first-party context, not be sent along with requests initiated by third party websites.
Lax - cookies are not sent on normal cross-site subrequests, but are sent when a user is navigating to the origin site.
None - cookies will be sent in all contexts.

Default value: Lax

PUT /admin/config/sessioncookie

 
curl --request PUT \ --url 'http://localhost:8892/admin/config/sessioncookie' \ --header 'apikey: {apikey}' \ --data '{  "samesite": "Strict"}'
Copy

Responses

200

Request processed successfully.

object

Session cookie configuration details.

samesite

number

SameSite attribute accepts three values:

Strict - cookies will only be sent in a first-party context, not be sent along with requests initiated by third party websites.
Lax - cookies are not sent on normal cross-site subrequests, but are sent when a user is navigating to the origin site.
None - cookies will be sent in all contexts.

Default value: Lax

403

Invalid user information or Not Allowed

404

Requests resource was not found.

500

Unexpected event on server

Response

 
{ "samesite": "Strict"}
Copy

Workers

Connect, deploy, undeploy and manage workers.

/admin/worker/instance/deploy/available/{installer_id}

POST

/admin/worker/instance/deploy

DELETE

/admin/worker/instance/deploy

POST

/admin/worker/instance/upgrade

GET

/admin/worker/instance/upgrade/version

Connect to workers

Connect to MetaDefender Cluster Worker services.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

array	array[object]	A list of workers and their connection details.
display_name	string	Display name for the worker.
host	string	The address of the worker.
port	number	The port on which the worker is listening.
connection_key	string	The connection key for the worker.

POST /admin/worker

 
curl --request POST \ --url 'http://localhost:8892/admin/worker' \ --header 'apikey: {apikey}' \ --data '[  {    "display_name": "Worker 1",    "host": "192.168.1.1",    "port": 8893,    "connection_key": "1234abcd"  }]'
Copy

Responses

200

Request to add service was successful

array	array[object]	list of worker status.
display_name	string	Display name for the worker.
host	string	The address of the worker.
port	number	The port on which the worker is listening.
result	string	Connection attempt result. Enum: `ok`,`failed`
worker_id	string	Present only when result = ok. Unique identifier of the worker.
error	string	Present only when result = failed. Error message.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
[ {  "display_name": "worker 1",  "host": "192.168.10.11",  "port": 8893,  "result": "ok",  "worker_id": "929d2bb8e0a83b49821f81b3f2d34b92" }]
Copy

List connected workers

Retrieve a list of currently connected MetaDefender Cluster Worker services.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /admin/worker

 
curl --get \ --url 'http://localhost:8892/admin/worker' \ --header 'apikey: {apikey}'
Copy

Responses

200

A list of connected workers.

array	array[object]	A list of connected workers and their details.
worker_id	string	Unique identifier of the worker.
display_name	string	Display name for the worker.
platform	string	Operating system / platform of the worker.
os	string	Operating system details of the worker.
package_type	string	The deployment package type.
hardware	object	Hardware information.
cpu	object
count	integer	Number of CPU cores.
model	string	CPU model name.
usage	number	CPU usage percentage.
disk	object
available_bytes	integer	Available disk space in bytes.
total_bytes	integer	Total disk space in bytes.
memory	object
available_bytes	integer	Available memory in bytes.
total_bytes	integer	Total memory in bytes.
user_name	string	Name of the user who added the worker.
host	string	The address (IP or hostname) of the worker.
port	integer	Port on which the worker is listening.
status	string	Current status of worker.
status_description	string	The description of worker's status
version	string	The version of the worker.
deployment_info	object	Deployment related information. This field is only available when instance is deployed.
type	string	Deployment type, can be `ometascan` or `api-gateway`.
installer_id	string	Identifier of the installer.
version	string	The instance version.
user_name	string	Name of the user who deployed the instance.
custom_config	object	Custom configuration for deployed instance.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
[ {  "worker_id": "8b099db9314a2845b2a29f21de134741",  "display_name": "Worker 1",  "platform": "Windows",  "os": "Windows 10.0.17763 (x64)",  "package_type": "windows_amd_msi",  "hardware": {   "cpu": {    "count": 10,    "model": "12th Gen Intel(R) Core(TM) i7-1270P",    "usage": 3.536   },   "disk": {    "available_bytes": 4292378624,    "total_bytes": 72872882176   },   "memory": {    "available_bytes": 542523392,    "total_bytes": 4244164608   }  },  "user_name": "LOCAL/user1",  "host": "192.168.10.11",  "port": 8893,  "status": "running",  "status_description": "",  "version": "2.3.0",  "deployment_info": {   "type": "ometascan",   "installer_id": "16ac760db70b3642b880d0e46b8de7b3",   "version": "5.15.1",   "user_name": "LOCAL/user1",   "custom_config": {    "connection_per_file_service": 4,    "log_level": "info"   }  } }]
Copy

Disconnect from workers

Disconnect from specified MetaDefender Cluster Worker services.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

array

array[string]

A list of worker IDs to disconnect.

DELETE /admin/worker

 
curl --request DELETE \ --url 'http://localhost:8892/admin/worker' \ --header 'apikey: {apikey}' \ --data '[  "8ff354cb076e154893dbf61734f3cf8e",  "a1b2c3d4e5f60718293a4b5c6d7e8f90"]'
Copy

Responses

200

Request to disconnect workers was successful

object

Map of worker IDs to disconnection (deletion) status.

worker_id

string

Disconnection status of the worker.

Enum: Deleted

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "8ff354cb076e154893dbf61734f3cf8e": "Deleted", "a1b2c3d4e5f60718293a4b5c6d7e8f90": "Deleted"}
Copy

Get available workers by installer_id.

Retrieve the list of available workers eligible for deployment for the specified installer ID.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /admin/worker/instance/deploy/available/{installer_id}

 
curl --get \ --url 'http://localhost:8892/admin/worker/instance/deploy/available/{installer_id}' \ --header 'apikey: {apikey}'
Copy

Responses

200

Request to get available workers was successful

array	array[object]	A list of connected workers and their details.
worker_id	string	Unique identifier of the worker.
display_name	string	Display name for the worker.
platform	string	Operating system / platform of the worker.
os	string	Operating system details of the worker.
package_type	string	The deployment package type.
hardware	object	Hardware information.
cpu	object
count	integer	Number of CPU cores.
model	string	CPU model name.
usage	number	CPU usage percentage.
disk	object
available_bytes	integer	Available disk space in bytes.
total_bytes	integer	Total disk space in bytes.
memory	object
available_bytes	integer	Available memory in bytes.
total_bytes	integer	Total memory in bytes.
user_name	string	Name of the user who added the worker.
host	string	The address (IP or hostname) of the worker.
port	integer	Port on which the worker is listening.
status	string	Current status of worker.
status_description	string	The description of worker's status
version	string	The version of the worker.
deployment_info	object	Deployment related information. This field is only available when instance is deployed.
type	string	Deployment type, can be `ometascan` or `api-gateway`.
installer_id	string	Identifier of the installer.
version	string	The instance version.
user_name	string	Name of the user who deployed the instance.
custom_config	object	Custom configuration for deployed instance.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
[ {  "worker_id": "8b099db9314a2845b2a29f21de134741",  "display_name": "Worker 1",  "platform": "Windows",  "os": "Windows 10.0.17763 (x64)",  "package_type": "windows_amd_msi",  "hardware": {   "cpu": {    "count": 10,    "model": "12th Gen Intel(R) Core(TM) i7-1270P",    "usage": 3.536   },   "disk": {    "available_bytes": 4292378624,    "total_bytes": 72872882176   },   "memory": {    "available_bytes": 542523392,    "total_bytes": 4244164608   }  },  "user_name": "LOCAL/user1",  "host": "192.168.10.11",  "port": 8893,  "status": "running",  "status_description": "",  "version": "2.3.0",  "deployment_info": {   "type": "ometascan",   "installer_id": "16ac760db70b3642b880d0e46b8de7b3",   "version": "5.15.1",   "user_name": "LOCAL/user1",   "custom_config": {    "connection_per_file_service": 4,    "log_level": "info"   }  } }]
Copy

Deploy workers

Deploy the selected installer on one or more selected workers.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object
type	string	Enum: `ometascan`
installer_id	string	Identifier of the installer.
worker	array[string]	List of worker IDs to deploy to.
config	object	Optional configuration for ometascan worker.
log_level	string	Enum: `debug`,`info`,`warning`,`error` Default: info
connection_per_file_service	integer	minimum: 1 Default: 4

POST /admin/worker/instance/deploy

 
curl --request POST \ --url 'http://localhost:8892/admin/worker/instance/deploy' \ --header 'apikey: {apikey}' \ --data '{  "type": "{string}",  "installer_id": "16ac760db70b3642b880d0e46b8de7b3",  "worker": [    "8b099db9314a2845b2a29f21de134741",    "3f4c2a9e7d1b48c2b7e6f019d8a5c123",    "c1d2e3f4567890ab12cd34ef56ab7890"  ],  "config": {    "log_level": "{string}",    "connection_per_file_service": "{integer}"  }}'
Copy

Responses

200

Request to add service was successful

object	object	Map of worker IDs to deployment status ("Deploying") or an error message.
*	string	"Deploying" if deployment initiated successfully; otherwise an error message.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "8b099db9314a2845b2a29f21de134741": "Deploying", "3f4c2a9e7d1b48c2b7e6f019d8a5c123": "Deploying", "c1d2e3f4567890ab12cd34ef56ab7890": "Deploying"}
Copy

Undeploy workers

Undeploy the specified workers.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

array array[string]

DELETE /admin/worker/instance/deploy

 
curl --request DELETE \ --url 'http://localhost:8892/admin/worker/instance/deploy' \ --header 'apikey: {apikey}' \ --data '[  "8b099db9314a2845b2a29f21de134741",  "3f4c2a9e7d1b48c2b7e6f019d8a5c123",  "c1d2e3f4567890ab12cd34ef56ab7890"]'
Copy

Responses

200

Request to undeploy workers was successful

object	object	Map of worker IDs to undeployment status ("Undeploying") or an error message.
*	string	"Undeploying" if undeployment initiated successfully; otherwise an error message.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "8b099db9314a2845b2a29f21de134741": "Undeploying", "3f4c2a9e7d1b48c2b7e6f019d8a5c123": "Undeploying", "c1d2e3f4567890ab12cd34ef56ab7890": "Undeploying"}
Copy

Upgrade deployed instances

Upgrade the deployed instances managed by the worker to a newer version

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object

Parameters to upgrade deployed worker instances.

version

string

Target version to upgrade to.

type

string

Worker deployment type.

Enum: ometascan,api-gateway,callback-service

POST /admin/worker/instance/upgrade

 
curl --request POST \ --url 'http://localhost:8892/admin/worker/instance/upgrade' \ --header 'apikey: {apikey}' \ --data '{  "version": "2.3.0",  "type": "{string}"}'
Copy

Responses

200

Request to upgrade workers was successful

object	object	Upgrade request accepted.
result	string

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "result": "The process to upgrade workers has started. Please wait until it completes to confirm success"}
Copy

Get upgradable instance version

Retrieve a list of available versions of MetaDefender Core and MetaDefender Cluster API Gateway for upgrading.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /admin/worker/instance/upgrade/version

 
curl --get \ --url 'http://localhost:8892/admin/worker/instance/upgrade/version' \ --header 'apikey: {apikey}'
Copy

Responses

200

A list of available versions for upgrading.

object	object
ometascan	array[string]
api-gateway	array[string]
callback-service	array[string]

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
{ "ometascan": [  "5.15.2",  "5.16.0" ], "api-gateway": [  "2.1.0",  "2.2.0" ], "callback-service": [  "2.5.0" ]}
Copy

Services

Add essential services and view connection status.

/admin/service/{service_id}

DELETE

/admin/service/{service_id}

GET

/admin/service/{service_type}

PUT

/admin/service/{service_type}/setting

GET

/admin/service/{service_type}/setting

Connect and check essential services status.

Establish connections and retrieve the status of essential services within the MetaDefender Cluster system.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object	service type `filestorage` configuration details
host	string	the host address of the service.
port	integer	the port number of the service.
connection_key	string	the connection key for the service.

POST /admin/service

 
curl --request POST \ --url 'http://localhost:8892/admin/service' \ --header 'apikey: {apikey}' \ --data '{  "host": "{string}",  "port": "{integer}",  "connection_key": "{string}"}'
Copy

Responses

200

Request to add service was successful

array	array[object]	A list of service id and their status.
result	string	the result of the service addition, can be either "ok" or "error"
service_id	string	The unique identifier of the service if result is "ok"
detail	string	The error details if result is "error"

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

 
[ {  "result": "ok",  "service_id": "8ff354cb076e154893dbf61734f3cf8e",  "detail": "{string}" }]
Copy

Get the status of all essential services.

Retrieve the status of all added services within the MetaDefender Cluster system.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /admin/service

 
curl --get \ --url 'http://localhost:8892/admin/service' \ --header 'apikey: {apikey}'
Copy

Responses

200

Details of all added services and their status.

object	object	Keyed by service type (e.g. broker, caching, datalake, filestorage, warehouse).
service_type	object	service type (e.g. broker, caching, datalake, filestorage, warehouse)
healthy_instances	number	Number of healthy instances for the service.
overall_status	string	Aggregated status across all instances of the service.
overall_status_description	string	Description of the overall status.
instances	array[object]	List of all replicated instances for the service.
service_id	string	Unique service identifier.
message	string	Optional status/message.
display_name	string	Human friendly name. Defaults to "host:port" if absent.
status_description	string	Human readable status explanation.
host	string	Hostname or IP.
port	number	Service's port.
version	string	Service version (semantic or other).
added_by	string	User or system that registered the service.
last_update	number	Unix epoch milliseconds of last update.
last_healthy	number	Unix epoch milliseconds of last confirmed healthy state.
detail	object	Service specific diagnostic details (structure varies by service).
cpu_usage	number	CPU usage (implementation specific units).
platform	string	Operating system/platform the service is running on.
role	string	Service role (e.g. primary, secondary).
db_size	number	Database size in bytes.
ram	object	Memory usage details.
total_bytes	number	Total RAM available.
used_bytes	number	RAM currently in use.
disk	object	Disk usage details.
total_bytes	number	Total disk space available.
used_bytes	number	Disk space currently in use.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

xxxxxxxxxx
 
{
 "broker": {...},
 "caching": {...},
 "datalake": {...},
 "filestorage": {...},
 "warehouse": {...}
}
Copy

Edit service details.

Update the display name and/or configuration details for a specific service. Note: Service configuration cannot be modified after instances have been deployed.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object	Request payload to connect a service and optionally set display name and configuration.
display_name	string	Display name for the service.
config	object	service configuration details
host	string	the host address of the service
port	integer	the port number of the service
user	string	the user name for the service. Applicable for type `caching`, `broker`, `datalake`, and `warehouse`
password	string	the password for the service. Applicable for type `caching`, `broker`, `datalake`, and `warehouse`
connection_key	string	the connection key for the service. Applicable for type `filestorage`

PUT /admin/service/{service_id}

Responses

200

Request to add service was successful

object	object	Service record plus last known health/status info.
service_id	string	Unique service identifier.
message	string	Optional status/message.
display_name	string	Human friendly name. Defaults to "host:port" if absent.
status_description	string	Human readable status explanation.
host	string	Hostname or IP.
port	number	Service's port.
version	string	Service version (semantic or other).
added_by	string	User or system that registered the service.
last_update	number	Unix epoch milliseconds of last update.
last_healthy	number	Unix epoch milliseconds of last confirmed healthy state.
detail	object	Service specific diagnostic details (structure varies by service).
cpu_usage	number	CPU usage (implementation specific units).
platform	string	Operating system/platform the service is running on.
role	string	Service role (e.g. primary, secondary).
db_size	number	Database size in bytes.
ram	object	Memory usage details.
total_bytes	number	Total RAM available.
used_bytes	number	RAM currently in use.
disk	object	Disk usage details.
total_bytes	number	Total disk space available.
used_bytes	number	Disk space currently in use.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

405

The user has no rights for this operation.

500

Unexpected event on server

Response

Disconnect to service and remove their configurations.

Remove the connection and configuration details for a specific service. Note: Service configuration cannot be deleted after instances have been deployed.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

DELETE /admin/service/{service_id}

Responses

200

Request to remove service was successful

object	object	Response indicating the service has been removed.
service_id	string

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

405

The user has no rights for this operation.

500

Unexpected event on server

Response

Get status for a specific service.

Retrieve the current status of a specific service, including all instance details. Note: The service_type must be one of: datalake, warehouse, caching, broker, filestorage.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /admin/service/{service_type}

Responses

200

Request to get service type was successful

object	object	Status information for a specific service type including instance details.
overall_status	string	Aggregated status for the service type (e.g. healthy, degraded, down)
overall_status_description	string	Human readable description of the aggregated status
healthy_instances	number	Count of instances currently considered healthy
instances	array[object]	List of discovered service instances
service_id	string	Unique service identifier.
message	string	Optional status/message.
display_name	string	Human friendly name. Defaults to "host:port" if absent.
status_description	string	Human readable status explanation.
host	string	Hostname or IP.
port	number	Service's port.
version	string	Service version (semantic or other).
added_by	string	User or system that registered the service.
last_update	number	Unix epoch milliseconds of last update.
last_healthy	number	Unix epoch milliseconds of last confirmed healthy state.
detail	object	Service specific diagnostic details (structure varies by service).
cpu_usage	number	CPU usage (implementation specific units).
platform	string	Operating system/platform the service is running on.
role	string	Service role (e.g. primary, secondary).
db_size	number	Database size in bytes.
ram	object	Memory usage details.
total_bytes	number	Total RAM available.
used_bytes	number	RAM currently in use.
disk	object	Disk usage details.
total_bytes	number	Total disk space available.
used_bytes	number	Disk space currently in use.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

405

The user has no rights for this operation.

500

Unexpected event on server

Response

Edit setting of service

Update the configuration settings for a specific service. Note: Supported only for the filestorage service type.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

Request Body

object	object
max_replica	number	Maximum number of replicas, default is 1
min_replica	number	Minimum number of replicas, default is 1
cleanuprange	number	Cleanup interval in hours, default is 0
storage	object	At-rest data protection
type	string	Storage backend type, can be `salt` or `none`
config	object	Backend specific configuration

PUT /admin/service/{service_type}/setting

Responses

200

Request to add service was successful

object	object	Response schema for successful service setting update
result	string	Success message

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

405

The user has no rights for this operation.

500

Unexpected event on server

Response

Get service settings

Retrieve the current configuration settings for a specific service. Note: Supported only for the filestorage service type.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /admin/service/{service_type}/setting

Responses

200

Request to retrieve service settings was successful

object	object
max_replica	number	Maximum number of replicas, default is 1
min_replica	number	Minimum number of replicas, default is 1
cleanuprange	number	Cleanup interval in hours, default is 0
storage	object	At-rest data protection
type	string	Storage backend type, can be `salt` or `none`
config	object	Backend specific configuration

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

405

The user has no rights for this operation.

500

Unexpected event on server

Response

Installers

Upload and manage installers for the MetaDefender Core and MetaDefender Cluster API Gateway.

/admin/installer/{installer_id}

Upload installer

Upload installers for the MetaDefender Core, MetaDefender Cluster API Gateway and MetaDefender Cluster Callback Service.

Auth

Headers

apikey	string	Generated `session_id` from Login call can be used as an `apikey` for API calls that require authentication.
filename	string	The name of the installer file to upload. Note: Ensure the filename remains same with the original MY OPSWAT download (e.g: ometascan-5.15.0-1-x64.msi)

Request Body

file

Optional installer file content (binary). Send raw bytes of the installer.

POST /admin/installer

Responses

200

Request processed successfully

object	object
installer_id	string	Unique identifier of the uploaded installer.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

405

The user has no rights for this operation.

500

Unexpected event on server

Response

Get uploaded installers

Retrieve information about an uploaded installer.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

GET /admin/installer

Responses

200

Request processed successfully

object	object	Map of installer IDs to installer details.
*	object
checksum	string	SHA256 checksum of the installer file.
name	string	Original file name of the installer.
platform	string	Target platform / package type.
size	number	Size of the installer file in bytes.
type	string	Product type of the installer.
upload_by	string	Identifier of the user or node that uploaded the installer.
upload_timestamp	number	Upload time as Unix epoch milliseconds.
version	string	Version extracted from the installer.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

500

Unexpected event on server

Response

Delete an uploaded installer

Delete an uploaded installer.

Auth

Headers

apikey

string

Generated session_id from Login call can be used as an apikey for API calls that require authentication.

DELETE /admin/installer/{installer_id}

Responses

200

Request processed successfully

object	object
result	string	Success message.

400

Bad Request (e.g. header is invalid, apikey is missing or invalid, parameter value is invalid or out of range, etc).

403

Invalid user information or Not Allowed

404

Requests resource was not found.

405

The user has no rights for this operation.

500

Unexpected event on server

Response

Control Center v2.6.0Terms of ServiceApache 2.0

Developer Guide

How to Interact with MetaDefender Cluster Control Center using REST API

Authentication

Auth

Authentication APIs

Login

Logout

User Management

User management APIs

Create user

List all users

Delete a user

Change Password for local user

Admin

List all user directories

Create new role

Delete a role

Config

Audit clean up

File storage clean up

Executive report clean up

Processing history clean up

Session settings

Get session cookie attributes

Update session cookie attributes

Workers

Connect to workers

List connected workers

Disconnect from workers

Get available workers by installer_id.

Deploy workers

Undeploy workers

Upgrade deployed instances

Get upgradable instance version

Services

Connect and check essential services status.

Get the status of all essential services.

Edit service details.

Disconnect to service and remove their configurations.

Get status for a specific service.

Edit setting of service

Get service settings

Installers

Upload installer

Get uploaded installers

Delete an uploaded installer

Control Center v2.6.0 Terms of Service Apache 2.0