# Historic Multi-AV Scan Records API (tca-0103) — Spectra Intelligence

> Retrieve current and historical multi-AV scan records for file hashes using Spectra Intelligence tca-0103; supports single and bulk queries of up to 100 hashes.

# 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

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/file-threat-intelligence/get/apixrefv2queryhash_typehash_value" />

### Request

```
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

`rl.sample`

``` json
{
  "rl": {
    "sample": {
      "sha1": "string",
      "sha256": "string",
      "sha384": "string",
      "sha512": "string",
      "ripemd160": "string",
      "md5": "string",
      "first_seen_on": "string",
      "last_seen_on": "string",
      "single_scan": false,
      "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 Bulk Report

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.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/file-threat-intelligence/post/apixrefv2bulk_querypost_format" />

### Request

```
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

``` json
{
  "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

``` json
{
  "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 Scan History

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.

### Request

```
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

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).

``` json
{
  "rl": {
    "sample": {
      "sha1": "string",
      "sha256": "string",
      "sha384": "string",
      "sha512": "string",
      "ripemd160": "string",
      "md5": "string",
      "first_seen_on": "string",
      "last_seen_on": "string",
      "single_scan": false,
      "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

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

## Custom Response Status Codes

This API implements custom response status codes. Find a complete list of possible HTTP response codes and their descriptions in the [General](../../index.md#response-status-codes) section of the documentation.

| CODE | MESSAGE                          | DESCRIPTION                                                                                                                                                                                      |
|:-----|:---------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 400  | Invalid username                 | The username sent in the Authorization header contained unrecognized characters, or was otherwise invalid.                                                                                       |
|      | Invalid hash value               | The requested hash value did not match the hash type, or was otherwise invalid.                                                                                                                  |
|      | Invalid hash type                | The requested hash type was not recognized. Accepted types are SHA1, SHA256, MD5.                                                                                                                |
|      | Parsing error description        | There 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 format              | The requested POST format was not recognized. Accepted formats are XML and JSON.                                                                                                                 |
|      | Empty request                    | The request did not contain any values or parameters.                                                                                                                                            |
| 403  |                                  | The server understood the request, but is refusing to fulfill it. The user account that sent the request is disabled.                                                                            |
|      | User not allowed                 | The user account that sent the request does not have the required permissions.                                                                                                                   |
| 404  | Missing multi-AV scan for sample | The requested sample does not have an multi-AV scan record.                                                                                                                                      |
