Rescan an uploaded file task (Sandbox)

Expand all | Collapse all

The /sandbox/tasks/file/{task ID} endpoint is used to repeat a file execution task in Kaspersky Sandbox.


Request method: PUT


Query parameters:

Expected parameters




Object execution task ID that you want to restart.

If necessary, you can change the object execution parameters. If the following parameters are not specified, previously specified values are used.

Optional expected parameters




Operating system that you want to use as an execution environment.

Available values can be obtained using the exec_env method.

If this parameter is not specified, Kaspersky Threat Intelligence Portal automatically determines the optimal operating system according to the type of uploaded file (Recommended option in web interface).


Object execution time in seconds. Available values: 30500.

If this parameter is not specified, Kaspersky Threat Intelligence Portal automatically determines the optimal execution time according to the type of uploaded file (Recommended option in web interface).


Object name. Required parameter.

Specify a file name, which Kaspersky Threat Intelligence Portal must use during execution in Kaspersky Sandbox. The specified file name will be assigned to the uploaded file or the file contained in the uploaded archive.

For correct processing of the file, do not specify its extension in the file_name parameter: Kaspersky Threat Intelligence Portal automatically determines the file type, and processes the file accordingly.

The value must not exceed 240 characters.


Object execution type. Available values:

exec-only—Object execution is performed.

unzip-and-exec—Object is unpacked before execution.


Password for an archived object.

This parameter is used only when processing_type = unzip-and-exec.


Boolean parameter. Specifies whether HTTPS traffic generated by the executed object must be decrypted. Available values:

true—HTTPS traffic generated by the object is decrypted.

false—HTTPS traffic generated by the object is not decrypted.

The HTTPS traffic decryption may decrease the malware detection probability.

By default, decrypt_https = true.

The parameter must not be specified, if you specify exec_env=WinXP.


Boolean parameter (optional). Specifies whether the links in the opened documents must be browsed. Available values:

true—Links in the opened documents are browsed.

false—Links in the opened documents are not browsed.

By default, click_on_links=true.


Region or individual country of a network channel that the object uses to access the internet. There are individual countries among the regions through which the executed file can access the internet.

Use the api/sandbox/channels method to obtain all available values.

Parameter values are case-sensitive.

Description of available values:

TOR—Internet channel belongs to any region and directs traffic through the TOR network.

Tarpit—File is executed without access to the internet.

<region or country name>—Internet channel belongs to any region and does not direct traffic through the TOR network (for example, RU, US, GB).


Password to open password-protected documents during execution.


You can use Windows environment variables by placing the % sign in front of and after the variable name, for example: %SYSTEMROOT%.

By default, the environment variables values are expanded on the user's host, before transferring and executing the object in the Sandbox. To transfer environment variables to the Sandbox as is, without expansion, use the %% sign, for example: %%SYSTEMROOT%%.

The command line may contain a $sample variable that will be replaced in the Sandbox with the actual path to the object in the operating system (for example, <notepad path> /A $sample).

The command in the command line must not exceed 1024 characters, otherwise Kaspersky Threat Intelligence Portal shortens it. Depending on the technical constraints of an operating system that is used as an execution environment in the Sandbox, the command may be further shortened.

Command line usage examples are described in the Appendices.

Request example:

To rescan an uploaded and executed file:

curl -u <user name> --cert <full path to the certificate on your computer> -X PUT --header 'Content-Length: 0' '<task ID>'


200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

451 Unavailable For Legal Reasons

Page top