Skip to main content

URI-to-hash search (TCA-0401)

The URI to Hash Search service provides a list of SHA1 hashes of files that, during static analysis, were found to contain the requested URI.

The following URI types are supported: email, URL, IPv4 address, and domain.

Sending requests using the GET method requires the SHA1 value of the URI string, while the POST method accepts the URI string value in plain text.

There are two available response formats: XML and JSON.

URI Query​

GET​

GET /api/uri_index/v1/query/{uri_sha1}/[next_page_sha1]?[format=xml|json]&[classification=KNOWN|MALICIOUS|SUSPICIOUS|UNKNOWN]

This query returns a response containing SHA1 hashes associated (through static analysis) with the requested URI. Using the GET method requires the URI to be submitted as a SHA1 hash value of the URI string.

  • uri_sha1
    • The SHA1 hash value of the URI string
    • Required
  • next_page_sha1
    • An optional parameter used for pagination. Each response contains the next_page_sha1 field needed for requesting the next page. To get the next page of results, provide the SHA1 hash returned in the next_page_sha1 response field as the next_page_sha1 parameter of the next request. If not supplied, the first page will be returned.
    • Optional
  • format
    • Response format. Accepts the following parameters: xml (default) and json
    • Optional
  • classification
    • If this parameter is provided in the request, the query will return a list of only those samples that match the requested classification. Possible values are: KNOWN, MALICIOUS, SUSPICIOUS, UNKNOWN
    • Optional

POST​

POST /api/uri_index/v1/query?[format=xml|json]

This query returns a response containing SHA1 hashes associated (through static analysis) with the requested URI string. Unlike the GET method, the URI string in the POST request body can be in plain text format.

The input format is specified using the Content-Type HTTP header field. It supports the following values:

  • text/xml
  • application/json

The response format defaults to the input format.

Request body:

{ "rl" : {
    "query" : {
      "uri" : "uri_string", 
      "next_page_sha1" : "SHA1_value"
     }
   }  
}
  • uri
  • next_page_sha1
    • An optional parameter used for pagination. Each response contains the next_page_sha1 field needed for requesting the next page. To get the next page of results, provide the SHA1_value hash returned in the next_page_sha1 response field as the next_page_sha1 parameter of the next request. If not supplied, the first page will be returned.
    • Optional

Response Format​

Response code 404 is returned when the URI isn't found in the ReversingLabs reputation database.

{
  "rl": {
    "uri_index": {
      "query_uri": "string",
      "next_page_sha1": "string",
      "sha1_list": [
        "string",
        "string",
        "string",
        "string",
        "string",
        "string"
      ]
    }
  }
}
  • A maximum of 1000 results per page will be returned
  • To get the next page of results, provide the SHA1 hash returned in the next_page_sha1 response field as the next_page_sha1 parameter in the next request

Examples​

Example 1​

Requesting SHA1 hashes associated with the 127.0.0.1 URI using JSON format for the request body. The response will also be in JSON format.

/api/uri_index/v1/query

Headers:

Content-Type:application/json

Request body:

{
  "rl": {
    "query": {
      "uri": "127.0.0.1"
    }
  }
}

Example 2​

Requesting the SHA1 hashes associated with the 127.0.0.1 URI using JSON format for the request body. The response will also be in JSON format.

Pagination system is used, with 4ca39b9be025792197c2dd17d63956d4089560fe used as a parameter to retrieve the next batch of results.

/api/uri_index/v1/query

Headers:

Content-Type:application/json

Request body:

{
  "rl": {
    "query": {
      "uri": "127.0.0.1",
      "next_page_sha1": "4ca39b9be025792197c2dd17d63956d4089560fe"
    }
  }
}

Example 3​

Requesting SHA1 hashes associated with 127.0.0.1 using GET. The "127.0.0.1" URI string has to be converted to SHA1 - 4b84b15bff6ee5796152495a230e45e3d7e947d9.

Response formats vary by type.

/api/uri_index/v1/query/4b84b15bff6ee5796152495a230e45e3d7e947d9?format=json
/api/uri_index/v1/query/4b84b15bff6ee5796152495a230e45e3d7e947d9?format=xml

Example 4​

Requesting SHA1 hashes associated with 127.0.0.1 using GET. The "127.0.0.1" URI string has to be converted to SHA1 - 4b84b15bff6ee5796152495a230e45e3d7e947d9.

Following example filters and returns only results that are classified as KNOWN.

/api/uri_index/v1/query/4b84b15bff6ee5796152495a230e45e3d7e947d9?classification=KNOWN

Multiple arguments can also be combined.

/api/uri_index/v1/query/4b84b15bff6ee5796152495a230e45e3d7e947d9?classification=MALICIOUS&format=json