Skip to main content

Versioning and changes

The current API version is v2, served under https://api.urlquery.net/public/v2. Build new integrations on v2.

What v2 guarantees​

Within v2, changes are additive:

  • New endpoints, optional parameters, response fields, and enum values can be added.
  • Existing fields are not removed or renamed, and their meaning does not change.
  • The response envelope, error envelope, and stable error codes stay the same.

Write clients that tolerate additions: ignore response fields you do not recognize, and handle an unknown enum value, such as a new verdict or relation type, without failing.

The full report document is the exception to field-level stability. It reflects what the analysis environment records, and sections can grow as new evidence types are captured. Treat fields you depend on defensively and check for their presence.

Breaking changes​

A change that would break existing clients, such as removing a field or changing a default, goes into a new API version. The previous version stays available while integrations move.

Earlier versions​

The v1 API is deprecated. It is not documented here and should not be used for new work. Existing v1 integrations should move to v2; the v2 Submission API, Report API, Reputation API, Host Profile API, and YARA Detection API cover submitting URLs, reading reports, search, reputation, infrastructure pivots, and managing YARA rules.

When moving submissions from v1, note that v2 rejects invalid fields instead of dropping them, requires an http or https scheme, does not accept priority, exit_node, or referer, and shows a submission's progress only to the account or team that made it.

OpenAPI description​

The API reference is generated from the OpenAPI description of v2, which you can download to generate clients or import into API tools. It is updated with every documented change.