Skip to main content

Historic multi-AV scan records (TCA-0103)

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 scanning result string.

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": [
            {}
          ]
        }
      ]
    }
  }
}

Examples​

Different response formats​

These examples request different response formats:

/api/xref/v2/query/sha1/7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb?format=json
/api/xref/v2/query/sha1/7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb?format=xml

Different hash types​

These examples use different hash types:

/api/xref/v2/query/sha1/531249faab39b526fc0b5f38af5c22af83887151
/api/xref/v2/query/sha256/000051db594056505dafa98420221285a3b1701282a54091aad7c63aa19f9854

Different post formats​

These examples use different post formats:

/api/xref/v2/bulk_query/xml
/api/xref/v2/bulk_query/json

Example of JSON bulk POST payload​

{
  "rl": {
    "query": {
      "hash_type": "sha1",
      "hashes": [
        "13e40f38427a55952359bfc5f52b5841ce1b46ba",
        "831fc2b9075b0a490adf15d2c5452e01e6feaa17",
        "42b05278a6f2ee006072af8830c103eab2ce045f"
      ]
    }
  }
}

Custom Response Status Codes​

This API implements custom response status codes:

CODEDESCRIPTION
400Invalid usernameThe username sent in the Authorization header contained unrecognized characters, or was otherwise invalid.
Invalid hash valueThe requested hash value did not match the hash type, or was otherwise invalid.
Invalid hash typeThe requested hash type was not recognized. Accepted types are SHA1, SHA256, MD5.
Parsing error descriptionThere was a problem with parsing the request. Possible reasons: no JSON object could be decoded; a parameter name is missing; a required parameter is missing; a delimiter character is missing.
Unknown POST formatThe requested POST format was not recognized. Accepted formats are XML and JSON.
Empty requestThe request did not contain any values or parameters.
403ForbiddenThe server understood the request, but is refusing to fulfill it. The user account that sent the request is disabled.
User not allowedThe user account that sent the request does not have the required permissions.
404Missing multi-AV scan for sampleThe requested sample does not have an multi-AV scan record.