# Lookups & inspect

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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](/docs/sentinel/v2/concepts/api-keys/#credential-matrix).

The lookups use the same data as the classifier: `/v2/ip` the [`[ip_resolver]` providers](/docs/sentinel/v2/configure/ip-resolvers/) and [threat intelligence](/docs/sentinel/v2/features/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]`:

```toml
[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]`](/docs/sentinel/v2/configure/listeners/), `GET /v2/inspect` is also served on the public listener. See [`[inspect]`](/docs/sentinel/v2/reference/configuration/#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](/docs/sentinel/v2/configure/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](https://github.com/pemistahl/lingua-rs), 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](https://github.com/faisalman/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](/docs/sentinel/v2/reference/glossary/)), `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](/docs/sentinel/v2/concepts/scoring/).

## Using the API

Look up an IP with a backend key:

```bash
curl https://sentinel.example.com/v2/ip \
-u 'key_…:sec_…' \
-H 'Content-Type: application/json' \
-d '{ "ip": "8.8.8.8" }'
```

```json
{
"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:

```bash
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." }'
```

```json
{ "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:

```bash
curl 'https://sentinel.example.com/v2/inspect?apiKey=key_…'
```

```json
{
"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](/docs/sentinel/v2/policies/security-rules/#inspect-with-a-rule-trace).

Full schemas: [`POST /v2/ip`](/sentinel-api-docs-v2.html#tag/ip/POST/v2/ip), [`POST /v2/language`](/sentinel-api-docs-v2.html#tag/language/POST/v2/language), [`POST /v2/user-agent`](/sentinel-api-docs-v2.html#tag/user-agent/POST/v2/user-agent), [`POST /v2/time-zone`](/sentinel-api-docs-v2.html#tag/time-zone/POST/v2/time-zone), and [`GET /v2/inspect`](/sentinel-api-docs-v2.html#tag/inspect/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](/docs/sentinel/v2/configure/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.

## Related

- [Scores, risk & penalty](/docs/sentinel/v2/concepts/scoring/)
- [Writing security rules](/docs/sentinel/v2/policies/security-rules/)
- [IP resolvers](/docs/sentinel/v2/configure/ip-resolvers/)
- [Threat intelligence](/docs/sentinel/v2/features/threat-intelligence/)
- [Classifier](/docs/sentinel/v2/features/classifier/)
- [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/)
- [`[inspect]` configuration](/docs/sentinel/v2/reference/configuration/#inspect)
