Historic multi-AV scan records
The Historic Multi-AV Scan Records service provides multi-AV scan reports for a given sample. Additionally, the service allows fetching historic multi-AV scan results. Single or bulk queries are supported.
This API is rate limited to 400 requests per second.
General Info about Requests/Responses
- All requests support the format query field which supports two options: xml or json.
- Default response format is xml, except for bulk queries, where default format is the same as the post_format.
- All bulk query rules will accept post payload of the same format (described below).
- The number of hashes in a bulk request must not be larger than 100.
- POST requests must set Content-Type: application/octet-stream in the HTTP header field.
- Scanners that failed while scanning the sample are not shown in the results field. If the whole results field is missing from the xref field, all scanners failed to scan the sample.
Multi-AV Scan Report (Single Query)
GET /api/xref/v2/query/{hash_type}/{hash_value}{?format=xml|json}
- hash_type can be: md5, sha1, sha256
- hash_value must be a valid hash defined by hash_type
- format can be: xml or json
- If the entry is not found, the API will return an HTTP 404 response
Response format
rl.sample
{
"rl": {
"sample": {
"sha1": "string",
"sha256": "string",
"sha384": "string",
"sha512": "string",
"ripemd160": "string",
"md5": "string",
"first_seen_on": "string",
"last_seen_on": "string",
"single_scan": 0,
"first_scanned_on": "string",
"last_scanned_on": "string",
"sample_type": "string",
"sample_size": 0,
"xref": [
{
"scanned_on": "string",
"scanner_match": 0,
"scanner_count": 0,
"results": [
{
"scanner": "string",
"result": "string"
}
],
"scanners": [
{
"name": "string",
"version": "string",
"timestamp": "string"
}
]
}
]
}
}
}
sha1
- SHA1 value; this field is mandatory and can be used as a primary key
first_seen_on
- Indicates the date and time when the file was first uploaded to the system, or when it was scanned for the first time
last_seen_on
- Indicates the date and time when the file was last uploaded to the system, or when it was scanned for the last time
single_scan
- True if the sample has only one multi-AV scan report; otherwise it's false
first_scanned_on
- The date and time of the first scan result
last_scanned_on
- The date and time of the last scan result
sample_type
- File type description e.g. MS Windows Shortcut, PE32 executable (GUI) Intel 80386, for MS Windows, ...
sample_size
- Sample size (in bytes)
xref
- Multi-AV scan records (The latest AV scanning report about the given sample, no historical results because history=false)
rl.xref.item
scanned_on
- The UTC timestamp when the sample was scanned (if history exists - in this case it's the latest result)
scanner_match
- The number of AV scanners with results
scanner_count
- The overall number of AV scanners that scanned the sample
results
- A list of results per scanner for this report
rl.xref.item.results
item
- The scanner-specific scanning report, contains two objects: the
scanner
name and the scanningresult
string.
- The scanner-specific scanning report, contains two objects: the
The scanners object contains scanner information. Each scanner is in a separate item
object.
rl.xref.scanners.item
name
- Scanner name.
version
- The name of the antivirus engine file (or its update) used for this scanning report.
timestamp
- The scanner update timestamp. This update can refer either to an update in the AV database or an update to the AV engine itself.
Multi-AV Scan Report (Bulk Query)
This query retrieves the same data as single query does, but for multiple hashes within single response. It is more network-efficient compared to multiple single queries.
POST /api/xref/v2/bulk_query/{post_format}
- post_format is a required parameter that defines the POST payload format. The parameter accepts the following formats: xml and json
Request body:
{
"rl": {
"query": {
"hash_type": "string",
"hashes": [
"string",
"string"
]
}
}
}
- hash_type must be one of the following options: md5, sha1, sha256
- hash values must be valid hashes defined by
hash_type
Response format
{
"rl": {
"samples": [],
"invalid_hashes": [
"string"
],
"unknown_hashes": [
"string"
]
}
}
invalid_hashes
- A list of ill-formatted hashes provided in request
unknown_hashes
- A list of hashes from the request that were not found in the database or don't have multi-AV data
Multi-AV History Query Option
Both single and bulk multi-AV queries support an additional query parameter history which can be either true or false. If not specified, the default value is false. When set to true, the service will provide the last 20 multi-AV records.
GET /api/xref/v2/query/hash_type/hash_value?history=true&format=xml
POST /api/xref/v2/bulk_query/post_format?history=true&format=json
- history defines whether the response should contain multi-AV records from history (when true) or latest one only (when false, default)
- format defines the response format: xml or json
Response format
When history
is true, everything is the same as in the single query, except the rl.sample.xref
object which now contains the history of scan results (if there are more than one).
{
"rl": {
"sample": {
"sha1": "string",
"sha256": "string",
"sha384": "string",
"sha512": "string",
"ripemd160": "string",
"md5": "string",
"first_seen_on": "string",
"last_seen_on": "string",
"single_scan": 0,
"first_scanned_on": "string",
"last_scanned_on": "string",
"sample_type": "string",
"sample_size": 0,
"xref": [
{
"scanned_on": "string",
"scanner_match": "string",
"scanner_count": "string",
"results": [
{}
],
"scanners": [
{}
]
}
]
}
}
}