API docs by Redocly

Threatray API (1.0.0)

Download OpenAPI specification:Download

The API adheres to the REST standard using resource-oriented URLs. All responses are JSON-encoded, follow standard HTTP response codes, and require authentication. The current API version is v1 and significant changes will increment the version number. The major version is part of the URL structure.

OAuth2 Bearer tokens authenticate API access. Tokens expire after 5 minutes and clients should retrieve a new token per request. Unauthorized access triggers a '401 Unauthorized' error The API exclusively operates over HTTPS, HTTP requests are rejected.

Standard HTTP response codes indicate API success or failure. Codes in the 2xx range signify success, while 4xx codes denote request-side errors like missing or invalid parameters. Codes in the 5xx range indicate server errors. Certain responses contain a nullable error field, revealing any issues on the request. Access the API example kit here for Python examples on file submission, fetching analysis results, executing searches, and more. The accompanying README explains environment setup, dependencies, and authentication.

Threatray relies on fundamental entities across both API and UI: sample, analysis, code region, and function. Analyzing a sample yields one or more analyses, with each analysis comprising one or more code regions. Each code regions may contain function for binary files with code. The term code region generically refers to a potential code-containing section within an analysis, such as memory dumps from dynamic analysis or the static analysis of a submitted file.

These base entities are uniquely identifiable:

  • sample: Identified by Hash (MD5, SHA1, SHA256)
  • analysis: Identified by UUID
  • code region: Identified by analysis identifier, hash (MD5, SHA1, SHA256), PID, base address
  • function: Identified by code region identifier, effective address

API endpoints return adequate information on these entities, enabling subsequent API calls, like fetching an analysis report after searching for analyses.

Certain API actions initiate tasks lasting seconds or minutes, notably file/URL submissions and signature modifications. These actions return a task ID used to track task status as follows:

  • queued: Awaiting processing
  • analyzing: Undergoing processing
  • done: Successfully completed
  • failed: Unsuccessful due to an error

Submission

The submission API allows to submit samples or URLs for analysis. Samples that already exist in the system can also be reanalyzed. Each submission will return a submission ID that uniquely identifies this submission. Each submission can start multiple tasks, for example when submitting an archive or submitting a sample to multiple environments. Each task is then again identified by its IDs. It is then possible to check the status of an entire submission or a single task.

/samples/{hash}/analyze

Reanalyze a previously submitted sample by its hash. Note: The parameters starting with raw_binary are only allowed and considered in combination with the parameter raw_binary_file_format set to unknown, raw or pe.

path Parameters
hash
required
string

Hash of the sample to be reanalyzed. Allowed hash types are MD5, SHA1, SHA256.

Request Body schema: application/json
required
analysis_mode
string
Default: "dynamic"

Mode of the analysis, can be dynamic (execution of in a sandbox) or static analysis. Allowed values: dynamic, static

enable_network
boolean
Default: "true"

Enable or disable network access for the dynamic analysis environment. This only applies to dynamic analyses.

environments
any
Default: "['win10_latest_x64']"

type: List[string]

The dynamic analysis operating systems to be used for the analysis. This only applies to dynamic analyses. Allowed array values: win10_latest_x64, win7_sp1_x64, win7_sp1_x86

label
string

Update the label of the sample to be reanalyzed.

priority
integer
Default: "5"

Priority of the analysis. Higher values indicate a higher priority for this submission in regards to other scheduled analyses. Allowed values: 0-9

raw_binary_cpu_architecture
string

The raw_binary_cpu_architecture tells Threatray which CPU architecture it should use to search for function entry points and to disassemble the sample. The value can be empty, x86-32 and x86-64

raw_binary_file_format
string

The raw binary file format indicates that the sender wants to send a custom binary file which potentially is not supported by default, the supported values here are: unknown, raw, pe

raw_binary_function_entry_point_detection_needed
boolean

If the flag is true, Threatray will try to find function entry points automatically. If it is false, the program expects the request to contain a function entry point

raw_binary_function_file_offset
string

type: int/string

This option only allowed in combination with raw_binary_function_entry_point_detection_needed=false. Threatray expects a file offset beginning from the image base address. The parameter accepts decimal or hexadecimal numbers as integer or string e.g 1234 or "0x1234"

raw_binary_image_base_address
string

type: int/string

The parameter allows to define the image base address as decimal or hexadecimal number as integer or string e.g 1234 or "0x1234"

timeout
integer
Default: "180"

Timeout of the dynamic analysis in seconds. This only applies to dynamic analyses. Allowed values: 15-1500

Responses

Request samples

Content type
application/json
{
  • "analysis_mode": "dynamic",
  • "enable_network": "true",
  • "environments": "['win10_latest_x64']",
  • "label": "string",
  • "priority": "5",
  • "raw_binary_cpu_architecture": "string",
  • "raw_binary_file_format": "string",
  • "raw_binary_function_entry_point_detection_needed": true,
  • "raw_binary_function_file_offset": "string",
  • "raw_binary_image_base_address": "string",
  • "timeout": "180"
}

Response samples

Content type
application/json
{
  • "error": [
    ],
  • "submissions": [
    ]
}

/submissions

Get the latest file submissions to the system.

query Parameters
user_submissions
number
Default: "0"

Only return my submissions if set to 1.

status_filter
string
Enum: "queued" "analyzing" "failed" "done" "unsupported"

Only return submissions in this status. This must be a comma-separated list.

Responses

Response samples

Content type
application/json
{
  • "submissions": [
    ]
}

/submissions/endpoint-scan

Get the latest endpoint scan submissions to the system.

query Parameters
status_filter
string
Enum: "queued" "analyzing" "failed" "done" "unsupported"

Only return submissions in this status. This must be a comma-separated list.

Responses

Response samples

Content type
application/json
{
  • "submissions": [
    ]
}

/submissions/endpoint-scan-archive

Submit an endpoint scan archive for analysis.

Request Body schema: application/json
required
archive
required
object

type: file-object

The archive to be submitted for analysis.

label
string

Label of the submitted archive.

priority
integer
Default: "1"

Priority of the analysis. Higher values indicate a higher priority for this submission in regards to other scheduled analyses. Allowed values: 0-9

send_notification_to
string

If notifications are configured, this parameter can be used to trigger a notification via email on a suspicious or malicious hit. Currently supported values are: email. To configure notifications and recipients for email notifications, please contact our customer support at support@threatray.com.

Responses

Request samples

Content type
application/json
{
  • "archive": { },
  • "label": "string",
  • "priority": "1",
  • "send_notification_to": "string"
}

Response samples

Content type
application/json
{
  • "submissions": [
    ]
}

/submissions/mans-file

Submit a Mandiant MANS file for analysis.

Request Body schema: application/json
required
file
required
object

type: file-object

The file to be submitted for analysis.

label
string

Label of the submitted archive.

priority
integer
Default: "1"

Priority of the analysis. Higher values indicate a higher priority for this submission in regards to other scheduled analyses. Allowed values: 0-9

send_notification_to
string

If notifications are configured, this parameter can be used to trigger a notification via email on a suspicious or malicious hit. Currently supported values are: email. To configure notifications and recipients for email notifications, please contact our customer support at support@threatray.com.

Responses

Request samples

Content type
application/json
{
  • "file": { },
  • "label": "string",
  • "priority": "1",
  • "send_notification_to": "string"
}

Response samples

Content type
application/json
{
  • "submissions": [
    ]
}

/submissions/minidump

Submit a minidump file for analysis.

Request Body schema: application/json
required
file
required
object

type: file-object

The minidump file to be submitted for analysis.

label
string

Label of the submitted archive.

priority
integer
Default: "1"

Priority of the analysis. Higher values indicate a higher priority for this submission in regards to other scheduled analyses. Allowed values: 0-9

Responses

Request samples

Content type
application/json
{
  • "file": { },
  • "label": "string",
  • "priority": "1"
}

Response samples

Content type
application/json
{
  • "submissions": [
    ]
}

/submissions/samples

Submit a file or a ZIP file for analysis. A set of parameters can be given to specify how the file should be analyzed. Note: The parameters starting with raw_binary are only allowed and considered in combination with the parameter raw_binary_file_format set to unknown, raw or pe.

Request Body schema: application/json
required
analysis_mode
string
Default: "dynamic"

Mode of the analysis, can be dynamic (execution in a sandbox) or static analysis. Allowed values: dynamic, static

enable_network
boolean
Default: "true"

Enable or disable network access to the internet (unfiltered) for the dynamic analysis environment. This only applies to dynamic analyses.

environments
any
Default: "['win10_latest_x64']"

type: List[string]

The dynamic analysis operating systems to be used for the analysis. This only applies to dynamic analyses. Allowed array values: win10_latest_x64, win7_sp1_x64, win7_sp1_x86

file
required
object

type: file-object

File to be submitted for analysis.

first_seen
integer
Default: "now"

First seen timestamp in UNIX-epoch format of the submitted sample.

label
string

Label of the submitted file.

priority
integer
Default: "1"

Priority of the analysis. Higher values indicate a higher priority for this submission in regards to other scheduled analyses. Allowed values: 0-9

raw_binary_cpu_architecture
string

The raw_binary_cpu_architecture tells Threatray which CPU architecture it should use to search for function entry points and to disassemble the sample. The value can be empty, x86-32 and x86-64

raw_binary_file_format
string

The raw binary file format indicates that the sender wants to send a custom binary file which potentially is not supported by default, the supported values here are: unknown, raw, pe

raw_binary_function_entry_point_detection_needed
boolean

If the flag is true, Threatray will try to find function entry points automatically. If it is false, the program expects the request to contain a function entry point

raw_binary_function_file_offset
string

type: int/string

This option only allowed in combination with raw_binary_function_entry_point_detection_needed=false. Threatray expects a file offset beginning from the image base address. The parameter accepts decimal or hexadecimal numbers as integer or string e.g 1234 or "0x1234"

raw_binary_image_base_address
string

type: int/string

The parameter allows to define the image base address as decimal or hexadecimal number as integer or string e.g 1234 or "0x1234"

source
string

Source of the file.

timeout
integer
Default: "180"

Timeout of the dynamic analysis in seconds. This only applies to dynamic analyses. Allowed values: 15-1500

dll_exports
Array of strings

A list of DLL exports that shall be called during execution. For each export, an argument needs to be specified, the argument can be an empty string.

dll_arguments
Array of strings

A list of DLL arguments passed to the DLL exports during execution. For each argument, an export needs to be specified.

Responses

Request samples

Content type
application/json
{
  • "analysis_mode": "dynamic",
  • "enable_network": "true",
  • "environments": "['win10_latest_x64']",
  • "file": { },
  • "first_seen": "now",
  • "label": "string",
  • "priority": "1",
  • "raw_binary_cpu_architecture": "string",
  • "raw_binary_file_format": "string",
  • "raw_binary_function_entry_point_detection_needed": true,
  • "raw_binary_function_file_offset": "string",
  • "raw_binary_image_base_address": "string",
  • "source": "string",
  • "timeout": "180",
  • "dll_exports": [
    ],
  • "dll_arguments": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "submissions": [
    ]
}

/submissions/urls

Submit a URL for analysis. All files downloaded from the URL are dynamically analyzed based on the parameters given.

Request Body schema: application/json
required
enable_network
boolean
Default: "true"

Enable or disable network access for the dynamic analysis environment. This only applies to dynamic analyses.

environments
any
Default: "['win10_latest_x64']"

type: List[string]

The dynamic analysis operating systems to be used for the analysis. This only applies to dynamic analyses. Allowed array values: win10_latest_x64, win7_sp1_x64, win7_sp1_x86

first_seen
integer
Default: "now"

First seen timestamp in UNIX-epoch format of the submitted URL.

label
string

Label of the URL and its downloaded files.

priority
integer
Default: "5"

Priority of the analysis. Higher values indicate a higher priority for this submission in regards to other scheduled analyses. Allowed values: 0-9

source
string

Source of the URL and its downloaded files.

timeout
integer
Default: "180"

Timeout of the dynamic analysis in seconds. This only applies to dynamic analyses. Allowed values: 15-1500

url
required
string

URL to be submitted for analysis.

Responses

Request samples

Content type
application/json
{
  • "enable_network": "true",
  • "environments": "['win10_latest_x64']",
  • "first_seen": "now",
  • "label": "string",
  • "priority": "5",
  • "source": "string",
  • "timeout": "180",
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "submissions": [
    ]
}

/tasks

Get a list of tasks, optionally filtered by parameters.

query Parameters
file_hash
string

Only return tasks matching this file hash (MD5, SHA1, SHA256).

submission_id
string

type: uuid

Only return tasks from this submission ID.

limit
integer
Default: "1000"

Limit the number of tasks to return.

Responses

Response samples

Content type
application/json
{
  • "tasks": [
    ]
}

/tasks/by-analysis/{analysis_id}

Get a task by Analysis ID.

path Parameters
analysis_id
required
string <UUID>

ID of the analysis for which the task should be returned.

Responses

Response samples

Content type
application/json
{
  • "analysis": {
    },
  • "created_at": 0,
  • "execution_report": [
    ],
  • "extracted_from": "string",
  • "modified_at": 0,
  • "priority": 0,
  • "sample": {
    },
  • "status": "queued",
  • "submission_id": "string",
  • "task_id": 0,
  • "username": "string"
}

/tasks/{task_id}

Get a task by its ID.

path Parameters
task_id
required
integer

ID of the task to return.

Responses

Response samples

Content type
application/json
{
  • "analysis": {
    },
  • "created_at": 0,
  • "execution_report": [
    ],
  • "extracted_from": "string",
  • "modified_at": 0,
  • "priority": 0,
  • "sample": {
    },
  • "status": "queued",
  • "submission_id": "string",
  • "task_id": 0,
  • "username": "string"
}

Analysis Report

The analysis report of a sample contains the following parts:

['General metadata on the sample and analysis.', 'Detection and identification verdicts, with a list of threats found.', 'On dynamic analyses: A list of processes and dumped memory regions from the execution.', 'On dynamic analyses: A set of behavioral artifacts collected during execution.']

Compared to the UI, the report does not include prevalence or OSINT information. You can use the /v1/search API to fetch prevalence information.

/analyses/{analysis_id}

Delete an analysis identified its analysis ID.

path Parameters
analysis_id
required
string <UUID>

ID of the analysis to delete.

Responses

/analyses/{analysis_id}

Get an analysis of a sample identified by its analysis ID.

path Parameters
analysis_id
required
string <UUID>

ID of the analysis to return.

Responses

Response samples

Content type
application/json
{
  • "analysis": {
    },
  • "ioc": {
    },
  • "processes": [
    ],
  • "sample": {
    }
}

/analyses/endpoint-scans

Get a list of endpoint scan analyzes with the option to apply a filter to the query.

query Parameters
verdicts
Array of strings non-empty
Default: "unknown&verdicts=suspicious&verdicts=malicious"
Items Enum: "malicious" "suspicious" "unknown"

Only select analyses with the specified verdicts.

from_finished_at
string or null <date-time>

Only select analyses that were finished on or after the specified date.

to_finished_at
string or null <date-time>

Only select analyses that were finished before or on the specified date.

limit
integer [ 1 .. 1000 ]
Default: 1000

Limit the number of selected analyses.

cursor
integer or null
Default: null

Represents a position within the dataset. Include this cursor token in subsequent requests to retrieve the next page of data. If the data is exhausted, the cursor returned by the server is null.

Responses

Response samples

Content type
application/json
{
  • "analyses": [
    ]
}

/files/{hash}/data

Download the binary data of a code region (a memory dump or sample) identified by its hash (MD5, SHA1, SHA256).

path Parameters
hash
required
string

Hash of the sample/memory dump.

query Parameters
zipped
boolean
Default: "false"

Download the file as a password protected ZIP file. The password is 'infected'.

Responses

/files/{hash}/metadata

Get PE metadata (if its a PE file) and strings on a code region identified by hash (MD5, SHA1, SHA256).

path Parameters
hash
required
string

Hash of a sample/memory dump.

Responses

Response samples

Content type
application/json
{
  • "exports": [
    ],
  • "first_seen": 0,
  • "hash_md5": "string",
  • "hash_sha1": "string",
  • "hash_sha256": "string",
  • "header": {
    },
  • "imports": [
    ],
  • "magic": "string",
  • "resources": [
    ],
  • "rich_header": {
    },
  • "scope": "string",
  • "sections": [
    ],
  • "size": 0,
  • "strings": [
    ],
  • "version_info": [
    ]
}

/osint/{analysis_id}

Get OSINT results for an analysis.

path Parameters
analysis_id
required
string <UUID>

ID of the analysis.

Responses

Response samples

Content type
application/json
{
  • "osint": [
    ]
}

/samples/{hash}

Delete a sample and all its analyses identified by hash (MD5, SHA1, SHA256).

path Parameters
hash
required
string

Hash of a sample to return.

Responses

/samples/{hash}

Get an analysis of a sample identified by hash (MD5, SHA1, SHA256). Always returns the latest analysis of the sample. The contents of the response depends on the type of the analysis, which can be dynamic or static. For static analyses, the keys 'processes' and 'ioc' are set to 'null'.

path Parameters
hash
required
string

Hash of a sample to return.

Responses

Response samples

Content type
application/json
{
  • "analysis": {
    },
  • "ioc": {
    },
  • "processes": [
    ],
  • "sample": {
    }
}

/samples/{hash}/analyses/{analysis_id}

Delete an analysis identified by hash and analysis ID.

path Parameters
hash
required
string

Hash of the sample of interest.

analysis_id
required
string <UUID>

ID of the analysis to delete.

Responses

/samples/{hash}/analyses/{analysis_id}

Get an analysis of a sample identified by hash (MD5, SHA1, SHA256). Returns the analysis indicated by the analysis ID. parameter.

path Parameters
hash
required
string

Hash of the sample of interest.

analysis_id
required
string <UUID>

ID of the analysis to return.

Responses

Response samples

Content type
application/json
{
  • "analysis": {
    },
  • "ioc": {
    },
  • "processes": [
    ],
  • "sample": {
    }
}

/signature-inspection

Get a list of functions of the binary file with their respective threats.

Request Body schema: application/json
required
analysis_id
string <UUID>

The analysis ID containing the binary file.

base
integer

If the binary file is a memory dump, then this specifies its base address in memory.

hash
required
string

The hash (MD5, SHA1, SHA256) of the binary file.

pid
integer

If the binary file is a memory dump, then this specifies the PID of the process.

Responses

Request samples

Content type
application/json
{
  • "analysis_id": "string",
  • "base": 0,
  • "hash": "string",
  • "pid": 0
}

Response samples

Content type
application/json
{
  • "functions": [
    ]
}

Search

Threatray provides a powerful search engine running over all private and public analyses. Refer to the user guide for the search syntax.

/search

Submit a search query, e.g. 'ip:"10.11.12.13".

query Parameters
query
required
string

Search query to submit. The query is validated and invalid queries will return an error.

date
number
Default: "0"

Only return samples from the last x days, based on first_seen dates. Options: Xd, e.g. 7d, 30d or 0d (=all).

max_results
number
Default: "1000"

Maximum number of resulting samples to return.

scope
string
Default: "both"

Limit the search query to a certain search scope. By default it is both, which means it looks up for samples in your private and in the public repository. Accepted values: both, private or public.

Responses

Response samples

Content type
application/json
{
  • "aggregations": {
    },
  • "analyses": [
    ]
}