# File Download API (tca-0201) — Spectra Intelligence

> Download file samples from the Spectra Intelligence repository by MD5, SHA1, or SHA256 hash using tca-0201; supports multi-threaded downloads at up to 100 req/min.

# 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, 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.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/automation/get/apispexdownloadv2queryhash_typehash_value" />

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

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/automation/post/apispexdownloadv2statusbulk_querypost_format" />

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

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

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

`rl.entries[]`:

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

## 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 | DESCRIPTION |
| :--- | :---------- |
| 403  | The sample is private and therefore not available for download. You can use the [TCA-0206 Alert on Reputation and Metadata](./tca-0206.md) 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. |
