# File Upload API (tca-0202/tca-0203) — Spectra Intelligence

> Upload file samples and metadata to Spectra Intelligence using tca-0202 and tca-0203; triggers automatic analysis pipeline and supports archive password and privacy settings.

# File upload (TCA-0202-0203)

This service allows users to upload a sample and its associated metadata to the Spectra Intelligence repository. Once uploaded, the sample is automatically analyzed by the ReversingLabs processing pipeline.

The upload process involves two separate requests:

1. The first request uploads the file contents.
2. The second request uploads the metadata.

### Submitting Archives

If the submission is an archive using a custom password, the password must be included in the metadata upload request. If the archive uses one of the standard passwords (`infected`, `password`, `1234`), the password does not need to be specified.

If the archive will later be forwarded to the [TCA-0207](../DynamicAnalysis/tca-0207.md) service for dynamic analysis, it must comply with the size and file count limits described in the [TCA-0207 Dynamic Analysis User Guide](../DynamicAnalysis/tca-0207.md). These limits do not apply to standard pipeline processing.

### Privacy

Whether submitted files will be shared with other ReversingLabs customers or not depends on the role configured for the Spectra Intelligence account used to upload files.

If the account is configured to upload all files as shareable (not private), then other ReversingLabs customers will be able to download the files and access their analysis results (metadata) through other ReversingLabs solutions.

If the account is configured to upload all files as not shareable (private), then other ReversingLabs customers may only be able to access analysis results for the files, but not retrieve the actual contents of the files. However, if the same files are uploaded to Spectra Intelligence as shareable from another source, they will cease to be treated as private. In that case, other ReversingLabs customers may be able to download the files.

### Processing limits

While there is no file size limit for the uploaded samples, larger files will take longer to upload and analyze, and may have less available metadata.

Files up to 400 MB are fully analyzed. Their metadata can be retrieved using the [TCA-0101 File Reputation](../FileThreatIntel/tca-0101.md), [TCA-0103 Historic Multi-AV Scan Records](../FileThreatIntel/tca-0103.md), [TCA-0104 File Analysis](../FileThreatIntel/tca-0104.md) services, and [TCA-0106 File Dynamic Analysis Report](../DynamicAnalysis/tca-0106.md). The complete metadata record includes, but is not limited to: classification, static analysis reports, behavior reports, dynamic analysis information, AV detections, container information, and file relationships. For more information, consult the official documentation for each of these services.

Files between 400 MB and 2 GB have a reduced metadata set: classification information from the [TCA-0101 File Reputation](../FileThreatIntel/tca-0101.md) service, AV detections from the [TCA-0103 Historic Multi-AV Scan Records](../FileThreatIntel/tca-0103.md) service, and source info from the [TCA-0104 File Analysis](../FileThreatIntel/tca-0104.md) service.
Files over 2 GB in size only have information about the file size and its source. If they came from a trusted source, [TCA-0101 File Reputation](../FileThreatIntel/tca-0101.md) classifies them as "KNOWN".

**This API is rate limited to 10 requests per second.**

## Sample upload request

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

### Request

```
POST /api/spex/upload/{sha1_value}
```

This request is used to upload a sample. To upload a sample, you first need to get its SHA1 hash.

``` bash
sha1sum example_file.tar.gz
```

Then, pass that hash as a **path parameter** (`sha1_value` in the URL above).

HTTP headers should contain `Content-Type: application/octet-stream` and the file must be sent as a stream of raw bytes in the body of the HTTP request.

## Metadata upload request

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

This request is used to upload metadata for the previously uploaded sample. If no metadata is uploaded, the sample won't be processed.

You can see the uploaded metadata in the `rl.sample.sources` field in the response of our file analysis services ([TCA-0104](../FileThreatIntel/tca-0104.md) and [TCA-0105](../FileThreatIntel/tca-0105.md)).

### Request

```
POST /api/spex/upload/{sha1_value}/meta[?subscribe=data_change]
```

#### Path parameters

- `sha1_value`
  - Must be a valid SHA1 hash of the sample that the metadata belongs to. The sample must be previously successfully uploaded.

#### Query parameters

- `subscribe`
  - If set, adds the sample to the user's **data_change** feed subscription list. The only accepted value for this parameter is `data_change`.

#### Headers

- `Content-Type: application/octet-stream`

#### Request body

Metadata must be provided in the XML format, while the request for the metadata must be sent using the `Content-Type: application/octet-stream` header. The metadata may include an optional XML declaration in the beginning, such as `<?xml version="1.0" encoding="UTF-8"?>`.

Metadata must contain the `domain` field and at least one `property` field.

The domain name should represent the web domain where the sample was found/downloaded. If the domain name is not known, the domain name should be set to an empty string.

The `property_name` and `property_value` can be any kind of string. They can represent some properties of the sample, such as its application name, version, file name of the sample, or tags.

For consistent results when using the [TCA-0207 Dynamic Analysis](../DynamicAnalysis/tca-0207.md) API, you must include a `filename` field in the metadata submission.

**Note: You can add metadata multiple times. If you add a metadata field and assign it some value X, but then change this value to Y in a new request, that field will not be overwritten. Instead, every metadata addition results in a new metadata entry, and you will see both X and Y in the response for that sample. The maximum number of metadata response fields is 10, and they are not sorted by the latest entry.**


``` xml
<rl>
  <properties>
    <property>
       <name>string</name>
       <value>string</value>
    </property>
  </properties>
  <domain>string</domain>
  <archive>
    <archive_type>string</archive_type>
    <archive_passwords>
      <password>string</password>
    </archive_passwords>
  </archive>
</rl>
```

#### XML POST body example

``` xml
<?xml version="1.0" encoding="UTF-8"?>
<rl>
  <properties>
    <property>
        <name>application_name</name>
        <value>MyApplication</value>
    </property>
    <property>
    <name>application_version</name>
        <value>7.0.3</value>
    </property>
    <property>
        <name>url</name>
        <value>http://myapplications.com/apps/utilities</value>
    </property>
    <property>
        <name>filename</name>
        <value>MyApplication_7.0.3_English.exe</value>
    </property>
    <property>
    <name>tags</name>
        <value>application, utilities</value>
    </property>
  </properties>
  <domain>myapplications.com</domain>
  <archive>
    <archive_passwords>
      <password>password123</password>
    </archive_passwords>
  </archive>
</rl>
```

## 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 |
| :--- | :---------- |
| 413  | The request contained more than the maximum allowed amount of hashes (100). |
