URL Threat Scan API
developer/v1/url/scanChecks 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
Reported Link Triage
Inspect a reported link before investigating the destination.
Distinguish host blocking from URL-pattern observations.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
url | query | string | Required | HTTP(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.
| Field | Type | Description |
|---|---|---|
url | string | Queried URL. |
host | string | Parsed hostname. |
is_malicious | boolean | True only when a Quad9 host detection is present; URL heuristics alone do not set this flag. False does not prove safety. |
threat_level | string | none, low, medium, high or critical. |
match_scope | string | host for a Quad9 hit, otherwise none. url is a reserved value not currently emitted. |
detections | array | source, category and optional details for detections. |
heuristics | array | signal, severity and detail for each triggered URL pattern. |
recommendations | string[] | Suggested investigation or handling steps. |
last_updated | string | Timestamp 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 --request GET 'https://api.edgedns.dev/v1/url/scan?url=https%3A%2F%2Fexample.com%2Fpath' \
--header "Authorization: Bearer YOUR_API_KEY"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);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.