Skip to content
TAO$188.32
BTC0.002928
MCap$2.22B
Vol$86.25M

API reference / Subnets

Whether up to 200 URLs may be shown as links (POST)

POST/api/v2/links/verdicts
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

The verdict on each URL, one item per requested URL in request order (a duplicate is answered as given): safe (it may be shown as a clickable link), caution (plain text with a warning), unsafe (never a link), or unchecked (not assessed yet: plain text). Each verdict carries its reason_categories and when the URL was last assessed and its verdict last changed. URLs are matched exactly as sent. A URL not assessed yet is unchecked with the category not_checked, never an error. The body is {urls} with 1..200 URLs of at most 2048 characters; the answer is not cached (no-store). Errors are application/problem+json: URLS_REQUIRED, BATCH_TOO_LARGE, INVALID_URL (each invalid entry named by its index), UNKNOWN_PARAMETER, VALIDATION_ERROR, SERVICE_UNAVAILABLE (503), SOURCE_NOT_READY (503: link verdicts are not served on this deployment yet).

Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).

Request body

A JSON object with these fields:

urlsarray of string

The URLs to look up, 1..200, each exactly as it is published (no normalisation: the string is matched as given), at most 2048 characters; answered in this order, a duplicate as given. An empty list is a 400 URLS_REQUIRED, more than 200 a 400 BATCH_TOO_LARGE, an empty or longer entry a 400 INVALID_URL naming its index (urls[i]); the request is atomic.

Response

data is a list of objects with these fields. Amounts are integer strings in their base unit, and null means unknown, never zero (see Units and formats). meta.at names the block the answer was read at.

One item per requested URL, in request order (a duplicate is answered as given).

urlstring

The requested URL, echoed exactly as sent.

verdictstring

How to render the URL: safe (assessed safe: it may be shown as a clickable link), caution (assessed suspicious: show it as plain text with a warning), unsafe (assessed harmful: never link it; hide it or show a warning in its place), unchecked (not assessed yet: show it as plain text, not clickable). New values may be added; show an unknown value as is (or generically).

reason_categoriesarray of string

The categories behind a verdict other than safe (empty when there are none): reported_phishing, reported_malware, lookalike_domain (imitates a known brand or domain), idn_homoglyph (look-alike international characters), insecure_transport (http://), unsafe_scheme (not a web scheme), credentials_in_url, ip_address_host, url_shortener, suspicious_tld, unparseable_url, check_incomplete (an assessment did not finish), other, and not_checked (the URL has not been assessed). New values may be added; show an unknown value as is (or generically).

checked_atstring (date-time) · can be null

The URL's last assessment, RFC 3339 UTC; null when it has not been assessed.

Format: date and time, ISO 8601 in UTC
verdict_changed_atstring (date-time) · can be null

When the verdict or its categories last changed, RFC 3339 UTC; null when it has not been assessed.

Format: date and time, ISO 8601 in UTC

Response headers

6 headers: Cache-Control, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Cache-Control

One of three classes: settled public, max-age=3600, stale-while-revalidate=86400 (pinned to a block that cannot move), slow public, max-age=300, stale-while-revalidate=600 (state that moves in minutes or days) or tip public, max-age=6, stale-while-revalidate=12 (follows the chain head); the label routes are cached until the next nightly copy (public, max-age=<seconds>, stale-while-revalidate=60). Never immutable. no-store on an earlier answer served because the data source failed (X-BTAI-Stale).

RateLimit-Policy

The tier's request quota of the current window (IETF draft), e.g. "tier";q=600.

RateLimit

Requests left in the current window and the seconds until it resets (IETF draft), e.g. "tier";r=597;t=42.

X-RateLimit-Limit

The tier's request quota of the current window.

X-RateLimit-Remaining

Requests left in the current window.

X-RateLimit-Reset

When the current window resets, Unix seconds.

Status codes

200 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503

Error codes

The codes this endpoint can return. Each links to what it means and what to do.

From the API's published specification, version 1.165.0.