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
| Endpoint | Credential | What it returns |
|---|---|---|
POST /v2/ip | restricted or full key (Basic) | Geolocation, network type, and threat-intelligence matches of an IP |
POST /v2/language | restricted or full key (Basic) | The up to 3 likeliest languages of a text |
POST /v2/user-agent | restricted or full key (Basic) | Browser, CPU, device, engine, and OS of a User-Agent string |
POST /v2/time-zone | restricted or full key (Basic) | Country and city coordinates of an IANA time zone |
GET /v2/inspect | public 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 onlyWith 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
| Field | Description |
|---|---|
device | Device 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) |
ip | The client IP, resolved per trusted_proxies |
network | The /v2/ip fields plus timedOut and the IP rules' scores |
location | The location rules of the IP's country, else of the timeZone query parameter's country; null without either |
risk | device.score + network.score + location.score, capped at 10, one decimal |
triggeredRules | The device, IP, and location rules that added to risk, highest first |
penalty | The client's penalty, 0–10, including this request's increments |
securityRules | Every 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
hintsso 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
errorsfor failing providers, and see IP resolvers for provider order and caching. - Inspect as a client check. Without
security_rules,GET /v2/inspectis safe to call from your frontend, for example to show a stricter flow whenriskis high. Calls count like other requests: they add toheaderEntropy, a client overheaderEntropy.limitgets429 HEADER_ENTROPY, and the security group's rules apply.
Limitations
/v2/languagedetects only the 30 languages listed and reads only the first 400 characters./v2/time-zoneresolves location-based IANA names (Region/City) only. Offset and legacy zones such asCET,UTC, orEtc/GMT+1returnnullfields./v2/ipwith thecloudflareorheadersprovider returns data only for the caller's own IP.GET /v2/inspectevaluates the request it receives; it can't inspect another client's IP or headers.