# Daily File Indicators Feed (TCF-0109) — Spectra Intelligence

> Consume TCF-0109 to receive a continuous list of Spectra Intelligence samples showing detection changes between multi-AV scan reports; records retained for 365 days.

# Files with detection changes (TCF-0109)

This service provides a continuous list of records about samples in the Spectra Intelligence system that have been scanned for the first time, or that show detection changes in their multi-AV reports.

The feed stores records for the last 365 days.

## Continuous Malware Scan Change Feed Query

This query returns a list of sample hashes that have been scanned for the first time, or those that show detection changes between the two last multi-AV scanning system reports.

The feed returns up to 1000 records and any surplus records sharing the same timestamp. To fetch the next batch of records, use the timestamp from the response increased by 1.

If the requested timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/malicious-file-indicators/get/api/feed/malware/scan/change/v1/query/{time_format}/{time_value}" />

### Request

```
GET /api/feed/malware/scan/change/v1/query/{time_format}/{time_value}[?format=xml|json|tsv][&sample_available=true|false][&limit=N]
```

- ``time_format``
  - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format
  - Required
- ``time_value``
  - Accepts values in the format set by time_format
  - Required
- ``format``
  - Parameter defining the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **tsv** (Tab Separated Values, delimiter character t 0x09).
  - Optional
- ``sample_available``
  - If this parameter is set to `true` in the request, filtering will be applied and the response will contain only samples that are present in the ReversingLabs storage and available for download. When set to `false`, the query will return all samples, regardless of their download availability status. The default is `false`, meaning that if the parameter is not provided in the request, filtering is not applied.
  - Optional
- ``limit``
  - The number of records to return in the response. The maximum and default value is 1000. Note that the response may include more records than requested to ensure that all records with the same timestamp are returned.
  - Optional

### Response

For the requested timestamp, the response contains a list of records. Every item in the list includes SHA1, MD5, and SHA256 hashes associated with the malware sample, as well as the information about the sample file type. If there are detection changes between the sample's last two multi-AV scanning system reports, every item will also contain a list of scanners for which changes have been recorded. Samples scanned for the first time will not contain this list of scanner changes.

An empty response is returned if no records for the requested timestamp are available.

``` json
{"rl": {
  "malware_scan_change_feed": {
    "time_range": {
      "from": "YYYY-MM-DDTHH:MM:SS",
      "to": "YYYY-MM-DDTHH:MM:SS"
    },
    "entries": [
      {
        "sha1" : "sha1_value",
        "md5" : "md5_value",
        "sha256" : "sha256_value",
        "sample_type" : "sample_type_value",
        "record_on" : "YYYY-MM-DDTHH:MM:SS",
        "changed_result_scanners" : [
          "scanner1_name",
          "scanner2_name",
          ...
        ]
      },
      {...},
      …
    ],
    "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp",
    }
  }
}
```

## PULL Query

For a given point in time, this query returns a list of sample hashes which have been scanned for the first time, or which show detection changes between their two last multi-AV scanning system reports.

The starting point for this query is defined using the `start-query`. If the user has not previously requested this query, nor has the START query been called, it will return records starting with the current timestamp. Every subsequent call will continue from the timestamp where the previous call ended. In case that the timestamp of the previous call is older than 365 days, the subsequent call will autocorrect this timestamp to the oldest available (i.e. `current - 365 days`), and corresponding records will be returned.

When using the pull query continuously, it is useful to implement a pause between API requests to allow more results to accumulate in the feed, increasing the number of results returned per API request and reducing the total number of API calls needed. However, when catching up from a distant past timestamp, minimizing the pause between requests will speed up the process. Once the timestamp from the latest API response matches the current time, both methods (with and without pause) yield a similar number of records per unit of time.

If you want to keep fetching the latest available records as they appear in the feed, you can use a short pause (e.g., 1 second) between requests. And if you need to catch up on a large backlog of data from the past, it is better to make continuous API calls without pausing.

Unless the **limit** parameter is specified, the feed returns up to 1000 records and any surplus records sharing the same timestamp. That ensures all the records with the same timestamp will be included in the recordset. The **limit** parameter must not be greater than 1000.

This endpoint is built to be queried by a single thread (single instance). Any concurrent requests will be blocked until the previous request is fulfilled.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/malicious-file-indicators/get/api/feed/malware/scan/change/v1/query/pull" />

### Request

```
GET /api/feed/malware/scan/change/v1/query/pull[?format=xml|json|tsv][&limit=N][&sample_available=false|true]
```

- ``format``
  - Parameter defining the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **tsv** (Tab Separated Values, delimiter character t 0x09).
  - Optional
- ``sample_available``
  - If this parameter is set to `true` in the request, filtering will be applied and the response will contain only samples that are present in the ReversingLabs storage and available for download. When set to `false`, the query will return all samples, regardless of their download availability status. The default is `false`, meaning that if the parameter is not provided in the request, filtering is not applied.
  - Optional
- ``limit``
  - The number of records to return in the response. The maximum and default value is 1000. Note that the response may include more records than requested to ensure that all records with the same timestamp are returned.
  - Optional

### Response

The response format is the same as in the `feed-query`.

## START Query

This query sets the starting timestamp for the previously described `pull-query`. It is used to reprocess an already pulled time span, obtain data from an older period that was not previously retrieved, or skip ahead to a more recent timestamp when older data is no longer relevant. Resetting the start time in these cases helps manage the data retrieval process effectively.

The starting timestamp must be within the last 365 days, otherwise the service will respond with the status code **400 Bad Request**.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/malicious-file-indicators/put/api/feed/malware/scan/change/v1/query/start/{time_format}/{time_value}" />

### Request

```
PUT /api/feed/malware/scan/change/v1/query/start/[time_format]/[time_value]
```

- ``time_format``
  - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format
  - Required
- ``time_value``
  - Accepts values in the format set by time_format
  - Required

### Response

A successful query returns an **HTTP 200 OK** message with an empty response body.

## Examples

**Retrieving all first-scanned samples or samples with changed scan results from 2019-10-04 14:00:00:**

```
api/feed/malware/scan/change/v1/query/timestamp/1570197600
api/feed/malware/scan/change/v1/query/utc/2019-10-04T14:00:00
```

**Retrieving all first-scanned samples or samples with changed scan results from 2019-10-04 14:00:00 that are available for download:**

```
/api/feed/malware/scan/change/v1/query/timestamp/1570197600?sample_available=true
/api/feed/malware/scan/change/v1/query/timestamp/1570197600?sample_available=true&format=json
```

**Retrieving all first-scanned samples or samples with changed scan results from 2019-10-04 14:00:00 in JSON and XML format:**

```
/api/feed/malware/scan/change/v1/query/timestamp/1570197600?format=json
/api/feed/malware/scan/change/v1/query/timestamp/1570197600?format=xml
```
