Reputation API

The v2 Reputation API returns urlquery's verdict for a URL and exports reputation indicators for use in your own blocklists and detections.

All routes are on https://api.urlquery.net and require x-apikey.

Method	Path	Quota class	Result
POST	/public/v2/reputation/lookup	reputation_lookup	Verdict for one URL.
GET	/public/v2/reputation/export	reputation_export	NDJSON download of reputation indicators. Requires the reputation_export capability.

Every call also consumes the account's overall v2 quota.

Treat reputation as one signal. A missing or clean result does not prove that an indicator is benign.

Look up a URL

POST /public/v2/reputation/lookup

Send one URL in a JSON body of at most 1 MiB; unknown fields are rejected with 400 BAD_REQUEST. The lookup evaluates exact URL and FQDN reputation over the last 30 days and returns the stronger verdict. Registrable-domain reputation is not applied, and the URL result wins ties. For an IP-hosted URL, only the exact URL verdict is considered.

curl --fail-with-body --request POST \
  --header "x-apikey: ${URLQUERY_API_KEY}" \
  --header 'content-type: application/json' \
  --data '{"url":"https://example.com/path"}' \
  https://api.urlquery.net/public/v2/reputation/lookup

{
  "success": true,
  "data": {
    "input": "https://example.com/path",
    "verdict": "suspicious",
    "applied_to": "fqdn"
  }
}

Field	Meaning
input	The submitted URL, unchanged.
verdict	malicious, suspicious, benign, or unknown.
applied_to	url or fqdn: which exact result supplied the verdict.

Export indicators

GET /public/v2/reputation/export

The export returns indicators with urlquery evidence in the selected window as a reputation-indicators.jsonl download. It is not wrapped in the v2 success envelope. A limited number of exports can run at the same time for each account.

Parameter	Values
timeframe	A positive number followed by h or d, or all; defaults to 30d.
as_of	RFC3339 timestamp the export is evaluated at; defaults to the request time.
type	Repeat to select indicator types: url, fqdn, domain, ip, or sha256. Defaults to all types.
detector	Optional. Only urlquery is accepted; other values return 400 BAD_REQUEST.

curl --fail-with-body \
  --header "x-apikey: ${URLQUERY_API_KEY}" \
  --header 'accept: application/x-ndjson' \
  --output reputation-indicators.jsonl \
  'https://api.urlquery.net/public/v2/reputation/export?timeframe=30d&type=url&type=domain'

The first line has kind=meta, declares the schema reputation-indicator-export/v2, and lists "detectors":["urlquery"]. It is followed by the declared number of kind=indicator lines:

{"kind":"indicator","data":{"type":"url","value":"example.test/login","verdict":"malicious","confidence":"high"}}

Each indicator contains its type, normalized value, verdict, and confidence (high, medium, low, or none). A complete stream ends with a matching kind=complete line containing the export ID, count, and SHA-256 digest. Exports are limited to 256 MiB of decoded data; a larger export is cut off after the 200 response has started.

Discard the download if the completion line is missing or does not match. An HTTP 200 alone does not prove that the stream completed.

Failures before the download starts use the normal v2 JSON error envelope:

Status	Error	When
400	BAD_REQUEST	as_of is not an RFC3339 timestamp, or detector is not urlquery.
400	INVALID_TIMEFRAME	timeframe is not a valid window, or as_of is in the future.
400	INVALID_INDICATOR	A type value is not supported.
400	RETENTION_WINDOW_EXCEEDED	The window starts before the retained data.
401	MISSING_API_KEY	No x-apikey header.
403	INVALID_API_KEY	The key is invalid or disabled.
403	FORBIDDEN	The account lacks the reputation_export capability.
422	EXPORT_TOO_LARGE	The selection has more indicators than one export allows. Narrow timeframe or type.
429	RATE_LIMIT_EXCEEDED	The quota, or the limit on concurrent exports, is reached. Wait Retry-After seconds.
502, 504	BAD_GATEWAY, GATEWAY_TIMEOUT	The reputation service failed, returned an invalid response, or timed out. Retry later.
503	RATE_LIMIT_UNAVAILABLE	Quota enforcement is temporarily unavailable. Retry later.