Skip to main content

Reanalyze file (TCA-0205)

The Rescan API provides a means to send sample(s) for rescanning. The service supports single and bulk queries.

This API is rate limited to 10 requests per second.

General Info about Requests/Responses​

  • The bulk query request supports the format query field which supports two options: xml and json
  • Default bulk query response 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 a 100
  • POST requests must set in HTTP header field Content-Type: application/octet-stream.

Rescan Single Query​

This query sends a sample with the requested hash for rescanning.

Request​

GET /api/rescan/v1/query/{hash_type}/{hash_value}

Path parameters:

  • hash_type accepts these options: md5, sha1, sha256
  • hash_value must be a valid hash defined by the hash_type parameter

Response​

  • Response code 404 is returned with data "Requested sample unavailable" when the sample with the given hash isn't available.
  • Response code 200 is returned with data "Sample sent for rescanning" when the sample with the requested hash is found in storage.

Rescan bulk query​

A bulk query will send multiple samples with requested hashes in a single request. There are also additional document elements describing ill-formatted hashes and hashes not found by the service.

Request​

POST /api/rescan/v1/bulk_query/{post_format}[?format=xml|json]

Path parameters:

  • post_format defines the request's payload format

Query parameters:

  • format accepts the options xml or json and defines the return format

Request body:

{
  "rl": {
    "query": {
      "hash_type": "string",
      "hashes": [
        "string"
      ]
    }
  }
}
  • hash_type value will be accepted if it matches one of the following options: md5, sha1, sha256

Response​

{
  "rl": {
    "sent_for_rescan": [
      "string"
    ],
    "sample_unavailable": [
      "string"
    ],
    "unknown_hashes": [
      "string"
    ],
    "invalid_hashes": [
      "string"
    ]
  }
}
  • sent_for_rescan
    • A list of hashes of samples sent for rescanning
  • sample_unavailable
    • A list of hashes of samples that are not available
  • unknown_hashes
    • A list of unknown hashes
  • invalid_hashes
    • A list of ill-formatted hashes provided in the request

Examples​

Rescan single query request​

These examples use different hash types:

/api/rescan/v1/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b
/api/rescan/v1/query/sha256/10dbb2b27208c5566d326b47950657bf6b3c9a59e302598a128ad7125d5fb4fd
/api/rescan/v1/query/md5/ca083f61113e1fb8f539ecfa7c725fc8

Rescan bulk query request​

These examples use different request body formats:

/api/rescan/v1/bulk_query/json
/api/rescan/v1/bulk_query/xml

With bulk queries, the output format will default to the post format. If you want the output format to be different from the post format, add the format query field:

/api/rescan/v1/bulk_query/xml?format=json

Bulk JSON request​

/api/rescan/v1/bulk_query/json
{
  "rl": {
    "query": {
      "hash_type": "md5",
      "hashes": [
        "4bb64c06b1a72539e6d3476891daf17b",
        "6353de8f339b7dcc6b25356f5fbffa4e",
        "59cb087c4c3d251474ded9e156964d5d",
        "6c2eb9d1a094d362bcc7631f2551f5a4",
        "a82c781ce0f43d06c28fe5fc8ebb1ca9",
        "920f5ba4d08f251541c5419ea5fb3fb3"
      ]
    }
  }
}
{
  "rl": {
    "query": {
      "hash_type": "sha1",
      "hashes": [
        "13e40f38427a55952359bfc5f52b5841ce1b46ba",
        "831fc2b9075b0a490adf15d2c5452e01e6feaa17",
        "42b05278a6f2ee006072af8830c103eab2ce045f"
      ]
    }
  }
}