Skip to main content

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 single query​

This query deletes a single sample defined by the hash 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 query​

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.

Request​

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

Path parameters:

  • format
    • Defines the request body format and supports xml and json

Request body:

{
  "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​

{
  "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

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