# Delete File API (tca-0204) — Spectra Intelligence

> Delete user-owned samples from the Spectra Intelligence repository using tca-0204; accepts single or bulk hash requests (MD5, SHA1, SHA256) of up to 100 hashes.

# Delete file (TCA-0204)

The Delete Sample service provides the functionality of deleting samples submitted and owned exclusively by the requester. The service supports single and bulk queries.

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

## General Info about Requests/Responses

- All requests support the **format** query field which supports two options: **xml** or **json**
- Default response format is xml, except for bulk queries, where the default 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**

## Sample Delete Sample

This query deletes a single sample defined by the hash value.

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

### Request

```
DELETE /api/delete/sample/v1/query/{hash_type}/{hash_value}[?delete_on={timestamp}]
```

#### Path parameters

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

#### Query parameters

- `delete_on`
  - optional query parameter that specifies when the sample will be deleted, expressed as a timestamp in seconds

### Response

- Response code 404 is returned with a message **"requested data was not found"** when the hash is not found in the database
- Response code 200 is returned when the sample is successfully deleted

## Sample Delete Bulk

This query deletes multiple samples at once defined by the list of hash values in the request payload. It is more network-efficient compared to consecutive single queries.

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

### Request

```
DELETE /api/delete/sample/v1/bulk_query/{format}
```

#### Path parameters

- `format`
  - Defines the request body format and supports **xml** and **json**

#### Request body

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

- `hash_type` will be accepted if it matches one of the following options: `md5`, `sha1`, `sha256`
- `hash_value` must be a valid hash defined by the `hash_type` parameter
- `delete_on` is an optional parameter that specifies when the sample will be deleted, expressed as a timestamp in seconds

### Response

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

- `deleted_hashes`
  - A list of hashes of deleted samples
- `invalid_hashes`
  - A list of ill-formatted hashes provided in the request
- `unknown_hashes`
  - A list of hashes from the request that were not found in the database
- `forbidden_hashes`
  - A list of hashes the user is not allowed to delete

## Examples

### Format query field

These examples use a different query response format:

```
/api/delete/sample/v1/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=json
/api/delete/sample/v1/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=xml
```

### Hash type path variable

These examples use a different hash type:

```
/api/delete/sample/v1/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b
/api/delete/sample/v1/query/sha256/b2bad07d6a3df4b0ec0c8d5f9a4905c289f9348e9e18d41d1b6033576ddf655cf80bc405e059ded6742947d78e0bfeb8
```

### Delete sample, bulk_query

These examples use a different post format:

```
/api/delete/sample/v1/bulk_query/xml
/api/delete/sample/v1/bulk_query/json
```

### delete_on query field

```
/api/delete/sample/v1/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?delete_on=1437566446
```

### Bulk JSON

```
/api/delete/sample/v1/bulk_query/json
```

``` json
{
  "rl": {
    "query": {
      "hash_type": "md5",
      "hashes": [
        "4bb64c06b1a72539e6d3476891daf17b",
        "6353de8f339b7dcc6b25356f5fbffa4e",
        "59cb087c4c3d251474ded9e156964d5d"
      ]
    }
  }
}
```
