Skip to main content

Network Reputation API (TCA-0407) — Spectra Intelligence

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

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.

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.

Privacy and Data Handling​

This API retrieves reputation information for URLs, domains, and IP addresses. It does not submit network locations for analysis.

When querying this API, the queried network location may be shared with third-party reputation sources as part of the lookup process. To prevent this data sharing, use the private parameter in your request. When set to true, the queried network location and results are not shared with third-party sources and not included in public feeds.

For comprehensive privacy considerations and best practices when using networking APIs, see Privacy & Data Sharing.

Network Reputation Query​

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

View OpenAPI Specification

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​

{
  "rl": {
    "query": {
      "network_locations": [
        {
          "network_location": "string"
        },
        {
          "network_location": "string",
          "type": "string"
        }
      ],
      "response_format": "string",
      "private": false
    }
  }
}
  • 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
  • private
    • Boolean flag to process the query privately. When set to true, the submitted network location and query results are not shared with third-party sources and not included in public feeds. Default is false.
    • Optional

Response​

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

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

rl.entries[]

{
  "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. 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 network location was given a classification. This parameter is only shown if the classification is not unknown. Possible values are
      • whitelist, blacklist - The network location was found on a ReversingLabs curated whitelist/blacklist.
      • 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.
    • Additional values for URLs:
      • file_reputation - Classification based on the downloaded content.
      • sandbox - Classification based on dynamic analysis (ReversingLabs Cloud Sandbox).
      • third_party_reputation - Classification based on third-party reputation sources.
      • Note: If the classification reason was propagated from a URL redirection, it will be prefixed with redirect_ (e.g redirect_file_reputation).
    • Additional values for domains:
      • asn_blacklisted - Classification based on the ASN being blacklisted.
  • 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. Applies to malicious and suspicious URIs only

Credits​

Domain classification data uses information from third-party sources:

© 2026 The Spamhaus Project SLU - https://www.spamhaus.org/drop/terms/

Examples​

Example 1​

A JSON URL query request and response.

/api/networking/reputation/v1/query/json
{
  "rl": {
    "query": {
      "network_locations": [
        {
          "network_location": "http://icayus.com/wTpWgvg"
        }
      ],
      "response_format": "json"
    }
  }
}
Response
{
  "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
        }
      }
    ]
  }
}

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
{
  "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"
    }
  }
}
Response
{
  "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
        }
      }
    ]
  }
}

Example 3​

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

/api/networking/reputation/v1/query/json
{
  "rl": {
    "query": {
      "network_locations": [
        {
          "network_location": "https://override-my-example.com"
        }
      ],
      "response_format": "json"
    }
  }
}
Response
{
  "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
        }
      }
    ]
  }
}

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 section of the documentation.

CODEDESCRIPTION
413The request contained more than the maximum allowed amount of network locations (100).