Skip to main content
ALTCHA®

Lookups & inspect

Sentinel exposes the lookups its classifier uses as standalone APIs: IP geolocation and threat data, language detection, User-Agent parsing, and time zone resolution. GET /v2/inspect shows how a security group sees the calling client, including risk, penalty, and, for debugging, the result of every security rule.

How it works

EndpointCredentialWhat it returns
POST /v2/iprestricted or full key (Basic)Geolocation, network type, and threat-intelligence matches of an IP
POST /v2/languagerestricted or full key (Basic)The up to 3 likeliest languages of a text
POST /v2/user-agentrestricted or full key (Basic)Browser, CPU, device, engine, and OS of a User-Agent string
POST /v2/time-zonerestricted or full key (Basic)Country and city coordinates of an IANA time zone
GET /v2/inspectpublic key (?apiKey= or Bearer), or restricted/full key (Basic)The caller's device, EDK, IP, network, location, risk, penalty, and optionally securityRules

The four lookups are stateless and take a JSON body. A public key gets 403 NON_PUBLIC_API_KEY_REQUIRED. GET /v2/inspect is a widget endpoint: it classifies the request itself, so call it from the browser or with the headers you want to test. All five belong to the functional API and need an active license. See the credential matrix.

The lookups use the same data as the classifier: /v2/ip the [ip_resolver] providers and threat intelligence, /v2/user-agent the parser of the device rules, and /v2/time-zone the time zone table of the location rules.

Enabling it

The lookups are always on. /v2/ip returns geolocation only with at least one IP resolver provider; without one, every provider field is null.

GET /v2/inspect is controlled by [inspect]:

[inspect]
enabled        = true    # false: GET /v2/inspect returns 404
security_rules = false   # true: include securityRules; debugging only

With security_rules = true, any caller with a key, including a browser holding a public key, sees which conditions its requests trip. Turn it on only on a test instance or while debugging. With [server.public_api], GET /v2/inspect is also served on the public listener. See [inspect].

Rules & signals

POST /v2/ip

Send { "ip": "…" } (IPv4 or IPv6). The response has the location fields (countryCode, country, region, city, lat, lon), asname, the network flags (mobile, hosting, proxy, tor, networks), threats, the threat verdict action, threatScore, and errors (providers whose lookup failed). Unknown fields are null; private IPs resolve to all null. The cloudflare and headers providers answer only for the caller's own IP. Field details are in IP resolvers.

POST /v2/language

Send text (1–16000 characters) and optional hints: up to 50 language codes (en, de-AT, …) of up to 35 characters each. The detector, based on Lingua, reads the first 400 characters and covers 30 languages:

ar bg cs da de el en es fi fr hi hu id it ja ko nl no pl pt ro ru sh sk sv th tr uk vi zh

no covers Bokmål and Nynorsk, and sh covers Serbian, Croatian, and Bosnian. languages holds at most 3 candidates with a probability from 0 to 1 (3 decimals). Hinted languages that are detected come first, then the rest by probability. There is no fallback: a text without letters returns languages: [], and a short or ambiguous text returns low probabilities rather than a guess of en.

POST /v2/user-agent

Send userAgent (1–8192 characters). The response follows the ua-parser-js result shape: ua, browser, cpu, device, engine, and os, with null for unknown parts.

POST /v2/time-zone

Send timeZone, an IANA name such as Europe/Vienna (1–200 characters). The response has countryCode, country, region (the middle segment of a three-segment zone like America/Argentina/Buenos_Aires, else null), city, lat, and lon. For a zone not in the table, every field except time is null.

GET /v2/inspect

FieldDescription
deviceDevice classification of the request headers: browser, OS, type, the device rules, edk (the EDK), edkSeed (header, cookie, or null; the seed itself is never returned), headerHash, headerEntropy (null without headerEntropy.limit), and userAgent (first 500 characters)
ipThe client IP, resolved per trusted_proxies
networkThe /v2/ip fields plus timedOut and the IP rules' scores
locationThe location rules of the IP's country, else of the timeZone query parameter's country; null without either
riskdevice.score + network.score + location.score, capped at 10, one decimal
triggeredRulesThe device, IP, and location rules that added to risk, highest first
penaltyThe client's penalty, 0–10, including this request's increments
securityRulesEvery security-group rule in order with how it evaluated; omitted unless [inspect] security_rules is true

The optional timeZone query parameter (the client's IANA time zone, at most 200 characters) enables TIMEZONE_MISMATCH and supplies location when the IP has no known country. How risk and penalty are computed is in Scores, risk & penalty.

Using the API

Look up an IP with a backend key:

curl https://sentinel.example.com/v2/ip \
  -u 'key_…:sec_…' \
  -H 'Content-Type: application/json' \
  -d '{ "ip": "8.8.8.8" }'
{
  "data": {
    "countryCode": "us",
    "country": "United States",
    "region": null,
    "city": null,
    "lat": null,
    "lon": null,
    "asname": "Google LLC",
    "mobile": null,
    "hosting": null,
    "proxy": null,
    "tor": null,
    "networks": [],
    "threats": [],
    "action": null,
    "threatScore": null,
    "errors": [],
    "time": 1.37
  }
}

The other lookups work the same way:

curl https://sentinel.example.com/v2/language \
  -u 'key_…:sec_…' \
  -H 'Content-Type: application/json' \
  -d '{ "text": "Dobrý den, jak se máte? Doufám, že je vše v pořádku." }'
{ "data": { "languages": [{ "language": "cs", "probability": 0.963 }, { "language": "sk", "probability": 0.036 }], "time": 7.8 } }

Debugging rules with inspect

Call GET /v2/inspect with the key whose security group you're testing. Here the group denies risk >= 8, and a monitored rule raises the proof-of-work cost for penalty >= 3. A curl client from a listed IP is denied, and the inspect data comes back next to the error:

curl 'https://sentinel.example.com/v2/inspect?apiKey=key_…'
{
  "code": "ACCESS_DENIED",
  "error": "Request blocked.",
  "statusCode": 403,
  "data": {
    "ip": "81.2.69.36",
    "risk": 8.0,
    "penalty": 0.0,
    "triggeredRules": ["MALICIOUS", "ACCEPT_LANGUAGE_HEADER_MISSING", "USER_AGENT_HEADER_UNCOMMON", "CLI"],
    "securityRules": [
      {
        "index": 0,
        "name": "high-risk",
        "action": "deny",
        "monitor": false,
        "evaluated": true,
        "matched": true,
        "outcome": "deny",
        "risk": 8.0,
        "riskRules": ["MALICIOUS", "ACCEPT_LANGUAGE_HEADER_MISSING", "USER_AGENT_HEADER_UNCOMMON", "CLI"],
        "penalty": null,
        "conditions": [{ "field": "risk", "matched": true, "signals": null }]
      },
      {
        "index": 1,
        "name": "penalized",
        "action": "set",
        "monitor": true,
        "evaluated": false,
        "matched": null,
        "outcome": null,
        …
      }
    ],
    "device": { … },
    "network": { … },
    "location": null
  }
}

Rules after the deciding one have evaluated: false. The securityRules fields and how to simulate origins, languages, and devices with request headers are explained in Writing security rules.

Full schemas: POST /v2/ip, POST /v2/language, POST /v2/user-agent, POST /v2/time-zone, and GET /v2/inspect.

Tuning

  • Language hints. Pass the languages your form expects in hints so they sort first when detected; they don't change probabilities. Treat probabilities below about 0.5 as uncertain, especially for short texts.
  • IP data quality. City, coordinates, and network flags depend on your providers. Check errors for failing providers, and see IP resolvers for provider order and caching.
  • Inspect as a client check. Without security_rules, GET /v2/inspect is safe to call from your frontend, for example to show a stricter flow when risk is high. Calls count like other requests: they add to headerEntropy, a client over headerEntropy.limit gets 429 HEADER_ENTROPY, and the security group's rules apply.

Limitations

  • /v2/language detects only the 30 languages listed and reads only the first 400 characters.
  • /v2/time-zone resolves location-based IANA names (Region/City) only. Offset and legacy zones such as CET, UTC, or Etc/GMT+1 return null fields.
  • /v2/ip with the cloudflare or headers provider returns data only for the caller's own IP.
  • GET /v2/inspect evaluates the request it receives; it can't inspect another client's IP or headers.

Start typing to search...

↑ ↓ Navigate ↵ Select