Whether up to 200 URLs may be shown as links (POST)
https://api.bittensor.ai/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 400BATCH_TOO_LARGE, an empty or longer entry a 400INVALID_URLnaming 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, andnot_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), slowpublic, max-age=300, stale-while-revalidate=600(state that moves in minutes or days) or tippublic, 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). Neverimmutable.no-storeon 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.
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BATCH_TOO_LARGE
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_PARAMETER
- INVALID_URL
- PAYMENT_REQUIRED
- RATE_LIMITED
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- URLS_REQUIRED
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.