File download (TCA-0201)

This service allows a user to download a sample from the Spectra Intelligence repository.

The download request requires the MD5/SHA1/SHA256 value of the sample to download, and receives a byte stream containing the requested sample.

Faster downloads are supported through multithreading. It is suggested to use at most 4 parallel threads. If there is a need for additional threads, please contact your sales representative.

This API is rate limited to 100 requests per minute.

Sample Download

This query returns the contents of a sample matching the requested hash. The contents are returned as a byte stream.

Request

GET /api/spex/download/v2/query/{hash_type}/{hash_value}

Path parameters:

• hash_type must be one of the following: md5, sha1, sha256
• hash_value must be a valid hash of the sample that should be downloaded

Sample Download Status

This query returns the file size of samples matching the requested hash values, but only if they are available for download.

If the requested samples are not available for download, their size in the response will be returned as -1. Sample download status requests don't count towards the API usage quota and can be sent as long as the sample download quota isn't exceeded.

Invalid and unknown hashes will be grouped into separate unknown_hashes and invalid_hashes objects in the report. unknown_hashes may include files that have been deleted.

Request

POST /api/spex/download/v2/status/bulk_query/{post_format}[?format={xml|json}]

Path parameters:

• post_format
  • Defines the request format (xml or json)

Query parameters:

• format
  • Defines the response format (xml or json)

Headers:

• Headers must contain Content-Type: application/octet-stream

Request body:

• The request must contain a list of at most 1000 valid hashes matching the valid_hash_type specified in the request - MD5, SHA1, SHA256.

{
  "rl": {
    "query": {
      "hash_type": "string",
      "hashes": [
        "string",
        "string"
      ]
    }
  }
}

Response

• the default response format is xml
• sizes of samples that are unavailable for download are reported as -1
• unknown and invalid hashes are grouped in unknown_hashes and invalid_hashes objects, respectively
• sample size is expressed in bytes (integer)

{
  "rl": {
    "entries": [],
    "unknown_hashes": [
      "string"
    ],
    "invalid_hashes": [
      "string"
    ]
  }
}

rl.entries[]:

{
  "sha1": "string",
  "size": "string"
}

Custom Response Status Codes

This API implements custom response status codes:

CODE	DESCRIPTION
403	The sample is private and therefore not available for download. You can use the TCA-0206 Alert on Reputation and Metadata API to get the notification when the sample becomes available. This error can also occur when the account doesn't have the necessary access rights. If this error persists, contact ReversingLabs support.
409	Can't complete the request. Try to resume upload.