HTTP API overview

The urlquery HTTP API submits URLs for analysis and returns analysis reports, URL reputation, and Host Profile infrastructure observations for applications, scripts, and data pipelines. It also manages your YARA detection rules.

Area	Use it to
Submissions	Submit a URL for analysis and follow it until the report is ready.
Reports	Read reports and their evidence, list recent and related reports, and search historical reports.
Reputation	Look up a URL's verdict and export reputation indicators.
Host Profile	Profile hosts and pivot through shared infrastructure and relationships.
YARA Detection	Create and maintain your YARA rule sets and rules, for example from CI, and test rules against reports before saving them.

Start with the workflows for complete investigations. The API reference lists every endpoint with its parameters, response fields, and code samples, and lets you send read requests with your own API key.

Base URL and authentication

https://api.urlquery.net/public/v2

Send your API key in the x-apikey header on every request. JSON request bodies must use content-type: application/json. See authentication for how to handle keys.

curl --fail-with-body \
  --header "x-apikey: ${URLQUERY_API_KEY}" \
  "https://api.urlquery.net/public/v2/reports/recent?limit=5"

Responses

JSON responses use one envelope. A successful response carries the result in data:

{
  "success": true,
  "data": {}
}

Binary endpoints, such as report screenshots and resource downloads, return raw bytes on success. The reputation export returns an NDJSON download. Errors from every endpoint use the JSON error envelope.

New fields can be added to responses within v2. Ignore fields you do not recognize.

Errors

{
  "success": false,
  "error": {
    "http_code": 400,
    "error": "BAD_REQUEST",
    "message": "limit must be between 1 and 100"
  }
}

http_code always equals the HTTP status. Match on the stable error code; message is for people and can change. The reputation export adds its own codes, listed on the Reputation API page.

Status	Error	What to do
400	BAD_REQUEST	Fix the request. message names the problem.
401	MISSING_API_KEY	Send the x-apikey header.
403	INVALID_API_KEY	The key is invalid or disabled, or could not be verified. Check the key; if it is correct, retry later.
403	FORBIDDEN	The key may not use this operation, for example an export without the reputation_export capability.
404	NOT_FOUND	The resource does not exist, or your key cannot see it.
405	METHOD_NOT_ALLOWED	Use the method shown in the reference.
413	SOURCE_TOO_LARGE	A YARA source exceeds 1 MiB. Split it into several rules.
422	UNPROCESSABLE_ENTITY	A YARA source does not compile. message lists the compiler errors.
429	RATE_LIMIT_EXCEEDED	Wait Retry-After seconds, then retry.
500	INTERNAL_ERROR	An unexpected failure. Retry later, and contact support if it persists.
502	BAD_GATEWAY	A urlquery service failed. Retry later with backoff.
503	RATE_LIMIT_UNAVAILABLE	Quota enforcement is temporarily unavailable. Retry later with backoff.
503	COMPILER_BUSY	The YARA compiler is busy. Retry after a few seconds.
504	GATEWAY_TIMEOUT	A urlquery service timed out. Retry later with backoff.

Pagination

Collections return items and a page object under data. An empty collection returns 200 OK with items: [].

• Cursor pages: report lists and Host Profile collections return page.next_cursor while page.has_more is true. Send it unchanged as cursor with the same parameters to read the next page. Cursors are opaque; do not parse or modify them.
• Offset pages: report search returns page.offset, page.limit, and page.total_hits. Add limit to offset to read the next page.
• Unpaged lists: YARA rule sets and a set's rules return every item in items, with no page.

Rate limits

Every admitted request counts against two quotas: the quota class of its route and your account's overall v2 quota. A request counts even if it then fails, for example with 400 or 404. Requests rejected with 429 or 503 are not counted. Members of a team share one quota, with the limits of each member's own plan.

Quota class	Routes
submission_create	Submitting a URL.
submission_lookup	Submission progress.
report_lookup	Single-report routes: overview, full report, screenshot, resource content, and delete.
report_collection	Recent and related report lists.
report_search	Report search.
reputation_lookup	Reputation lookup.
reputation_export	Reputation export, which also limits concurrent exports.
host_lookup	Host profiles.
host_collection	Host pivots and relation lists.
host_search	Host search.
yara_read	Reading YARA rule sets and rules.
yara_write	Creating, updating, and deleting YARA rule sets and rules, validating sources, and testing them against a report. Lower than the other classes, because each call compiles the source.

Each quota has minute, hour, and day windows aligned to the clock. Responses describe the window that limits you most:

RateLimit-Policy: 50;w=60, 500;w=3600, 500;w=86400
RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 27

RateLimit-Reset is the number of seconds until that window resets. A 429 RATE_LIMIT_EXCEEDED response also sends Retry-After; when the limit on concurrent reputation exports is reached, Retry-After reflects when a running export ends. Limits depend on your account tier.

Retries

The API does not retry for you.

• Retry 429 after Retry-After, and 502, 503, and 504 with exponential backoff.
• Do not retry 400, 401, 404, or 422 without changing the request, or 403 unless it is INVALID_API_KEY for a key you know is valid.
• Reads are safe to retry. Deleting a report that is already gone returns 404.
• Do not retry a submission automatically after a timeout, 502, or 504: it may already be queued. See retries and duplicates.

Recommended flow

1. List your recent reports, or search for reports with specific fields and a date range.
2. If no report covers the URL, submit it and poll until it is done.
3. Fetch a report overview before requesting the full report or binary evidence.
4. Check URL reputation as one signal alongside the report evidence.
5. List related reports by IP address, ASN, or domain, and use Host Profile pivots to find shared infrastructure.
6. Corroborate candidates with report evidence before drawing conclusions.