---
title: "Classify a URL or IP address"
method: POST
path: "/v1/check"
tags: ["check"]
---

# Classify a URL or IP address

`POST /v1/check`

## Request

- Base URL: `https://api.skanqrcode.com`
- URL: `https://api.skanqrcode.com/v1/check`
- Auth: HTTP bearer

Classifies one URL or IP address as `malicious`, `suspicious` or `not_malicious` and recommends an `action` (`block`, `warn` or `allow`). Call it before letting a user follow a link, open a QR-code destination or accept a connection from an IP you do not already trust. Consumes one unit of the tenant's monthly quota per successful call (cached results included); unparseable input (400) and blocked requests (429) are not billed. Quota and the per-minute limit are counted per tenant across all keys and IPs. It always returns a verdict. Sandbox (`sk_test_`) keys return `environment: sandbox` and `licensedForProduction: false`; use those results for integration testing only.

## Request body

- CheckRequest
  - `target` string, required: A URL or an IP address (v4 or v6) to classify. Decimal, hexadecimal and octal IPv4 forms are treated as IP addresses. Up to 4096 characters.
  - `userId` string: Optional opaque identifier of the end user on whose behalf the check runs. It enables per-user result caching. It is hashed before use and never stored or logged in clear.

## Response `200`

A verdict was produced.

- CheckResponse
  - `verdict` 'not_malicious' | 'suspicious' | 'malicious', required: The classification. See `action` for what to do about it: they are not the same field.
  - `action` 'allow' | 'warn' | 'block', required: The recommended action for the caller. Fixed mapping, identical on every plan: not_malicious -> allow, suspicious -> warn, malicious -> block.
  - `mode` 'url' | 'ip', required: Whether the target was evaluated as a URL or as an IP address.
  - `reasons` string[], required: Reason codes that contributed to the verdict. Codes name the category of evidence only, never a data source.
  - `finalUrl` string, nullable, required: The URL a shortened link resolved to, when a redirect was followed; otherwise null.
  - `cached` boolean, required: True only when the result came from this tenant's own per-user cache, which requires `userId`. Best-effort: false when the per-user cache can't answer within a few milliseconds of where the request is served (for example, far from its replicas). The verdict is the same either way.
  - `executionTimeMs` integer, required: Server-side processing time of the evaluation in milliseconds.
  - `environment` 'sandbox' | 'production', required: Derived from the calling key's plan, never from the request.
  - `licensedForProduction` boolean, required: False on the free sandbox plan. Static plan metadata: it never changes `verdict` or `action`, but sandbox results must not be relied on for production enforcement.
  - `requestId` string, required: Identifier to quote when contacting support.
  - `related` RelatedHost[]: IP mode only: up to 20 recently associated hosts, most recent first.
    - `host` string, required
    - `verdict` 'not_malicious' | 'suspicious' | 'malicious', required

## Other responses

- `400`: The request failed validation (malformed JSON, bad field, unparseable target, or a body over 8 KB).
- `401`: The API key is missing, malformed, unknown or revoked.
- `402`: The tenant is suspended for non-payment.
- `403`: The request is not allowed: the key lacks the required scope or the account has been blocked (`forbidden`), or the plan does not include the feature (`plan_feature_unavailable`).
- `429`: The per-minute rate limit (`rate_limited`) or the monthly quota (`quota_exceeded`) was exceeded. Blocked requests are not billed. Back off for `Retry-After` seconds.
- `500`: Unexpected failure. Never contains stack traces, internal hostnames or upstream error bodies.
- `503`: Authentication is temporarily unavailable for a key that has not been seen recently. Retry shortly.

---

[API](https://skmtc.dev/skanqrcode/apis/skanqrcode-api.md) · [All operations](https://skmtc.dev/skanqrcode/apis/skanqrcode-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skanqrcode/apis/skanqrcode-api/revisions/f307ade24b00?raw)