Skip to main content

URL Threat Scan API

developer
GET/v1/url/scan

Checks a URL host against Quad9 DNS threat blocking and evaluates URL-pattern heuristics. The endpoint does not fetch the page, execute its scripts, inspect downloaded files or certify that a URL is safe.

What It Does

Parses an HTTP(S) URL and evaluates patterns including embedded credentials, raw-IP hosts, suspicious paths, deep subdomains, URL shorteners and punycode. Combines these observations with a Quad9 host-level check and returns detections, heuristics and a threat level. match_scope is currently host for a Quad9 hit and none otherwise; the declared url value is reserved. URL heuristics influence threat_level but do not set is_malicious. DNS failures can reduce available evidence.

Why It's Useful

Add a bounded triage step for reported links, then investigate signals in context before blocking a shared host or trusting an unflagged URL.

Use Cases

Security Analyst

Reported Link Triage

Inspect a reported link before investigating the destination.

Distinguish host blocking from URL-pattern observations.

Parameters

NameLocationTypeRequiredDescription
urlquerystringRequiredHTTP(S) URL, up to 4096 characters; URL-encode it as a query value.Example: https://example.com/path

Response Fields

Result fields below are inside the JSON data object. Any row named meta describes the sibling response metadata object. See response and error handling for status codes and error responses. Optional observations may be absent or null; inspect warnings and partial-failure fields before treating a missing result as a negative finding.

FieldTypeDescription
urlstringQueried URL.
hoststringParsed hostname.
is_maliciousbooleanTrue only when a Quad9 host detection is present; URL heuristics alone do not set this flag. False does not prove safety.
threat_levelstringnone, low, medium, high or critical.
match_scopestringhost for a Quad9 hit, otherwise none. url is a reserved value not currently emitted.
detectionsarraysource, category and optional details for detections.
heuristicsarraysignal, severity and detail for each triggered URL pattern.
recommendationsstring[]Suggested investigation or handling steps.
last_updatedstringTimestamp of the analysis.

Code Examples

Replace YOUR_API_KEY with your API key. This endpoint requires the developer plan or higher; see plans and usage limits.

cURL
curl --request GET 'https://api.edgedns.dev/v1/url/scan?url=https%3A%2F%2Fexample.com%2Fpath' \
  --header "Authorization: Bearer YOUR_API_KEY"
JavaScript
const response = await fetch(
  "https://api.edgedns.dev/v1/url/scan?url=https%3A%2F%2Fexample.com%2Fpath",
  {
    "method": "GET",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

if (!response.ok) {
  throw new Error(`EdgeDNS returned HTTP ${response.status}`);
}
const data = await response.json();
console.log(data);
Python
import requests

response = requests.request(
    'GET',
    "https://api.edgedns.dev/v1/url/scan?url=https%3A%2F%2Fexample.com%2Fpath",
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    timeout=60,
)
response.raise_for_status()
data = response.json()
print(data)

Read the full URL Threat Scan guide

Learn the concepts, choose a practical workflow, and interpret the observations from URL Threat Scan before acting on them. Use the documented REST request for this operation.

Read the guide →

    Related Endpoints

    External References

    Learn more about the standards and protocols behind this endpoint.

    URL Threat Scan API Reference | EdgeDNS