# URL-to-File Association API (TCA-0407) — Spectra Intelligence

> Query TCA-0407 for reputation data on URLs, domains, and IP addresses with third-party detections from Spectra Intelligence.

The Network Reputation service provides information regarding the reputation of a requested URL, domain, or IP address. When a URL is submitted, the service provides its ReversingLabs classification, along with an overview of detections from our partners. It also includes the category of the URL (for example phishing, gambling, adult content) and indicates whether we have encountered any malware samples associated with the submitted URL.

When a domain or IP address is submitted, the response does not include the ReversingLabs classification. The remaining information in the response remains the same as for URLs.

The service supports both single and bulk queries. Bulk queries allow for a combination of URLs, domains, and IP addresses to be processed in the same request.

### Privacy and Data Handling

Domains submitted for analysis using [TCA-0404 Analyze URL](/SpectraIntelligence/API/NetworkThreatIntel/tca-0404) are treated as public data and accessible to all Spectra Intelligence users.

For other queries (such as retrieving threat intelligence without submitting for analysis), information may be shared with third-party reputation sources as part of the lookup process. For comprehensive privacy considerations and best practices when using networking APIs, see [Privacy & Data Sharing](/General/SecurityAndAccessControl/Privacy#urls).

## General Info about Requests/Responses

- All requests require the **post_format** parameter which supports two options: **xml** or **json**.
- Default response format is **xml**
- The number of URLs, domains or IP addresses in the request must not be greater than **100**.

## Network Reputation Query

This query returns reputation information about queried URLs, domains and IP addresses.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/network-threat-intelligence/post/apinetworkingreputationv1querypost_format" />
  
### Request

```
POST /api/networking/reputation/v1/query/{post_format}
```

Path parameters:

- `post_format`
  - Required parameter that defines the POST payload format. Supported options are **xml** and **json**.

#### Request body

``` json
{
  "rl": {
    "query": {
      "network_locations": [
        {
          "network_location": "string"
        },
        {
          "network_location": "string",
          "type": "string"
        }
      ],
      "response_format": "string"
    }
  }
}
```

- `network_locations`
  - A list of one or more network locations to be queried.
  - For every `network_location`, users can optionally set the `type` of the requested URI: `URL`, `IP` or `DOMAIN`. If the type isn't provided, the service will detect the URI type.
  - **Expected domain format:** fully qualified domain name using dots as separators, without any prefixes or suffixes.
  - **Expected URL format:** Submissions prefixed with a protocol name (`http://` and `https://`).
  - **Expected IP format:** IP address without any prefixes or suffixes (`1.2.3.4`).
  - Submissions that do not follow the expected formatting will be interpreted as follows:
    - A domain or IP with a slash (`domain.suffix/` or `1.2.3.4/`) will be treated as a URL.
    - Entries with multiple slashes at the end or prefixed by protocols (e.g., `https://1.2.3.4`, `1.2.3.4//` ) are also URLs.
  - Required
- `response_format`
  - Defines the response format. Supported options are `xml` and `json`. The default is **xml**.
  - Optional

### Response

The response contains reputation information for all valid requested network locations, along with the list of invalid network locations.

```json
{
  "rl": {
    "entries": []
  }
}
```

-----------------------------------------------------------------------

`rl.entries[]`

```json
{
  "type": "string",
  "requested_network_location": "string",
  "associated_malware": "bool",
  "last_seen": "string",
  "first_seen": "string",
  "third_party_reputations": {},
  "classification": "string",
  "reason": "string",
  "threat_level": 0,
  "threat_name": "string",
  "categories": []
}
```

- `requested_network_location`
  - The requested URL, domain or IP address
- `type`
  - The type of requested network location
- `classification`
  - ReversingLabs classification, available only for URLs. Possible values are malicious, suspicious, known, or unknown.
- `categories`
  - List of categories that the URI in question belongs to (for example, phishing, news, retail, government, business_and_economy). List items are strings. The strings are arbitrary values obtained from third-party sources or from user overrides (using TCA-0408).
- `first_seen`
  - Indicates the initial detection of the requested URL/domain/IP by a third-party source, the first instance of obtaining metadata for the requested URL/domain/IP from ReversingLabs static/dynamic file processing services (related files), or the first time the requested URL has been crawled or analyzed by the Spectra Sandbox.
- `last_seen`
  - The last time when the requested URL/domain/IP received an indicator that updated its report. This can be the last time when we checked the URL/domain/IP reputation against third-party sources, the last time we obtained metadata for the requested URL/domain/IP from ReversingLabs static/dynamic file processing services (related files), or the last time the requested URL/domain/IP has been crawled or analyzed by the Spectra Sandbox.
- `third_party_reputations`
  - Third party URL/domain/IP reputation counters showing the number of third party sources that detected the item as malicious/clean/undetected.
- `associated_malware`
  - A boolean indicator showing if ReversingLabs downloaded malware from the submitted URL/domain/IP directly. The value does not rely on third-party results.
- `reason`
  - The reason why the URL was given a classification. This parameter is only shown if the classification is not `unknown`. If the classification reason was propagated from a URL redirection, it will be prefixed with `redirect_` (e.g `redirect_file_reputation`). Possible values are
    - `whitelist`, `blacklist` - The URL was found on a ReversingLabs curated whitelist/blacklist.
    - `file_reputation` - Classification based on the downloaded content.
    - `sandbox` - Classification based on dynamic analysis (ReversingLabs Cloud Sandbox).
    - `third_party_reputation`, `domain_third_party_reputation` - Classification based on third-party reputation sources.
    - `user_override` - Classification overridden by you, or a user belonging to your organization.
    - `analyst_override` - Classification overridden by a ReversingLabs analyst.
- `threat_level`
  - Malware severity indicator expressed as an integer between 0 and 5. Values from `1` to `5` indicate threats from lowest to highest severity, `0` is reserved for known URIs. For unknown URIs, this value is omitted. **Applies to malicious and suspicious samples only**
  - In real-world situations, threat level values are typically interpreted in the following way:
    - Threat Level 4, 5 - immediate response required (e.g., different types of Trojans, URI found on a blocklist or matches a known malware regex)
    - Threat Level 2, 3 - should be examined within 24 hours (e.g., first stage exploits, URLs with homoglyph variations)
    - Threat Level 1 - not urgent, but should be periodically reviewed (e.g. Adware / PUA, misleading subdomains).
- `threat_name`
  - Standardized malware name indicating the type, platform, and family of the threat associated with the URL. Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). **Applies to malicious and suspicious URIs only**

## Examples

### Example 1

A JSON URL query request and response.

```
/api/networking/reputation/v1/query/json
```

``` json
{
  "rl": {
    "query": {
      "network_locations": [
        {
          "network_location": "http://icayus.com/wTpWgvg"
        }
      ],
      "response_format": "json"
    }
  }
}
```

<details>
<summary>Response</summary>

``` json
{
  "rl": {
    "entries": [
      {
        "type": "url",
        "requested_network_location": "http://icayus.com/wTpWgvg",
        "associated_malware": false,
        "last_seen": "2024-04-16T07:12:50",
        "first_seen": "2024-03-11T19:15:10",
        "classification": "malicious",
        "reason": "third_party_reputation",
        "categories": [
          "phishing",
          "spam",
          "suspicious",
          "scam_illegal_unethical",
          "uncategorized"
        ],
        "third_party_reputations": {
          "total": 19,
          "undetected": 17,
          "malicious": 2,
	        "suspicious": 0,
          "clean": 0
        }
      }
    ]
  }
}
```

</details>

### Example 2

A JSON query including all supported types: URL, domain and IP address. Some are provided without the optional `type` field.

```
/api/networking/reputation/v1/query/json
```

<details>
<summary>Response 1</summary>

``` json
{
  "rl": {
    "query": {
      "network_locations": [
        {
          "network_location": "https://psychology-degree-programs-us.today/"
        },
        {
          "network_location": "https://international-partnerships.ec.europa.eu/index_en",
          "type": "url"
        },
        {
          "network_location": "www.stemalservice.it",
          "type": "domain"
        },
        {
          "network_location": "216.239.34.36",
          "type": "ip"
        }
      ],
      "response_format": "json"
    }
  }
}
```

</details>

<details>
<summary>Response 2</summary>

``` json
{
  "rl": {
    "entries": [
      {
        "type": "url",
        "requested_network_location": "https://psychology-degree-programs-us.today/",
        "associated_malware": false,
        "last_seen": "2024-04-16T07:19:54",
        "first_seen": "2024-01-24T19:17:44",
        "classification": "known",
        "reason": "file_reputation",
        "categories": [
          "business_and_economy",
          "uncategorized"
        ],
        "third_party_reputations": {
          "total": 19,
          "undetected": 19,
          "malicious": 0,
	        "suspicious": 0,
          "clean": 0
        }
      },
      {
        "type": "url",
        "requested_network_location": "https://international-partnerships.ec.europa.eu/index_en",
        "associated_malware": false,
        "last_seen": "2024-04-16T06:07:36",
        "first_seen": "2024-04-15T08:45:36",
        "classification": "known",
        "reason": "file_reputation",
        "categories": [
          "government_legal",
          "government"
        ],
        "third_party_reputations": {
          "total": 19,
          "undetected": 19,
          "malicious": 0,
	        "suspicious": 0,
          "clean": 0
        }
      },
      {
        "type": "domain",
        "requested_network_location": "www.stemalservice.it",
        "associated_malware": false,
        "last_seen": "2024-04-10T05:29:50",
        "first_seen": "2024-04-10T05:29:50",
        "third_party_reputations": {
          "total": 12,
          "undetected": 12,
          "malicious": 0,
	        "suspicious": 0,
          "clean": 0
        }
      },
      {
        "type": "ip",
        "requested_network_location": "216.239.34.36",
        "associated_malware": false,
        "last_seen": "2024-04-15T10:42:56",
        "first_seen": "2024-02-16T22:41:05",
        "third_party_reputations": {
          "total": 11,
          "undetected": 11,
          "malicious": 0,
	        "suspicious": 0,
          "clean": 0
        }
      }
    ]
  }
}
```
</details>

### Example 3

A JSON URL query, the result has a user classification override.

```
/api/networking/reputation/v1/query/json
```

``` json
{
  "rl": {
    "query": {
      "network_locations": [
        {
          "network_location": "https://override-my-example.com"
        }
      ],
      "response_format": "json"
    }
  }
}
```

<details>
<summary>Response</summary>

``` json
{
  "rl": {
    "entries": [
      {
        "type": "url",
        "requested_network_location": "https://override-my-example.com",
        "associated_malware": false,
        "last_seen": "2024-04-16T08:08:04",
        "first_seen": "2024-04-16T08:08:04",
        "classification": "malicious",
        "reason": "user_override",
        "categories": [
          "Proxy Avoidance and Anonymizers"
        ],
        "third_party_reputations": {
          "total": 19,
          "undetected": 19,
          "malicious": 0,
	        "suspicious": 0,
          "clean": 0
        }
      }
    ]
  }
}
```

</details>

## 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 network locations (100). |
