Server API

The ShieldLabs Server API is the server-side surface for your domain — the visitor identification and device fingerprinting API your backend calls to read scored results. ShieldLabs scores each visit asynchronously: the JS snippet collects signals, ShieldLabs scores them in about a second, and the result arrives by webhook and is stored for this API to read. Two backend APIs, both server-side only — never call them from the browser:

History API (recommended) on account.shieldlabs.ai — served by Shield.Portal.Admin. Read scored snapshots by identifier. Free: reads do not consume requests. Response envelope { data, total } (snake_case).
Management API on api.shieldlabs.ai — served by Shield.Core. Read your domain profile and balance, plus an alternate history path that bills per returned row (PascalCase JSON array).

Both History surfaces accept the same lookup types: ip, user_hid, visitor_id, request_id, device_id, session_id, cookie_id. Register webhook endpoints in the dashboard Webhooks tab (up to 10 per domain).

Base URLs

Use these hosts for the History API and Management API. The development hosts mirror production for local and staging work.

Environment	History API	Management API
Production	`https://account.shieldlabs.ai/api`	`https://api.shieldlabs.ai`
Development	`https://dev.account.shieldlabs.ai/api`	`https://api.shieldlabs.ai` (use dev-domain keys)

Authentication

Each API uses a different backend credential. Both are server-side only; an unauthenticated request returns 401.

API	Header(s)	Credential
History API	`Authorization: Bearer sec_…`	Private API Key — the domain is inferred from the key
Management API	`Authorization: Bearer <secret>` + `X-Shield-Domain: <domain>`	Secret Key (hex)

Authorization: Bearer sec_xxxxxxxx-xxxxxxxx-xxxxxxxx

All server credentials must stay on your backend. Never put a Private API Key or Secret Key in the browser, the JS snippet, client logs, or a public repository. Webhook endpoints use separate whsec_… signing secrets. The browser-safe credential is the Public Key, which goes in the snippet, not here.

Trying it out

The fastest check: read one scored identification back by its request_id with your Private API Key.

curl "https://account.shieldlabs.ai/api/v1/history/request_id/550e8400-e29b-41d4-a716-446655440000?limit=1" \
  -H "Authorization: Bearer sec_your_private_api_key"

A 200 with a data array (empty is valid) means your key and host are correct. Full endpoint detail follows.

History API (recommended)

Read stored snapshots from your backend with the Private API Key (authentication above). Wrong or missing credentials return 401 with a JSON body like {"error":"invalid api key"}.

Endpoints at a glance

Method	Path	Purpose
`GET`	`/api/v1/history/{search_type}/{value}`	Search snapshots by identifier (the standard read path)

For a single identification, query history/request_id/{value} with limit=1 (shown below). Two extended routes — /api/v1/request/{request_id} and /api/v1/debug/… — return one snapshot or a search in an extended PascalCase shape with extra network and attribution fields, for investigations. They are not the standard integration path, and their response shape differs from the snake_case history envelope below.

GET `/api/v1/history/{search_type}/{value}`

Searches the snapshots ShieldLabs has stored for your domain. Returns a paginated envelope, newest first. This is the guaranteed read path when a webhook may have been missed.

curl "https://account.shieldlabs.ai/api/v1/history/request_id/550e8400-e29b-41d4-a716-446655440000?limit=1" \
  -H "Authorization: Bearer sec_your_private_api_key"

Path parameters

string

required

The field to search on. One of:

ip: client IP address (IPv4)
user_hid: the hashed user id you passed via the snippet (free-form string)
visitor_id: a VisitorID (UUID)
request_id: a single identification’s RequestID (UUID)
device_id: a DeviceID (UUID)
session_id: a SessionID (UUID) — browsing session within a visit window
cookie_id: a CookieID (UUID)

Always send one of the supported values above. An unsupported {search_type} is not validated and will not return the result you expect.

string

required

The value to match for the chosen search_type.

Query parameters

integer

default:"20"

Maximum number of rows to return. Must be between 1 and 100; values outside that range fall back to 20. Rows are ordered newest first.

integer

default:"0"

Number of rows to skip for pagination.

Response

{
  "data": [
    {
      "request_id":  "550e8400-e29b-41d4-a716-446655440000",
      "session_id":  "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
      "cookie_id":   "3f2e1d0c-9b8a-7654-3210-fedcba987654",
      "device_id":   "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "visitor_id":  "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ip":          "203.0.113.10",
      "os":          "Windows",
      "browser":     "Chrome",
      "device_type": "desktop",
      "country":     "US",
      "user_hid":    "e3b0c44298fc1c149afbf4c8996fb924",
      "connection_type": "vpn",
      "score":            15,
      "score_details": "[{\"Value\":15,\"Description\":\"VPN\"}]",
      "created_at":  "2026-06-16 10:00:00"
    }
  ],
  "total": 1
}

The data array holds snapshot objects in snake_case. The score_details field is a JSON string; parse it to get the signal list. Each entry carries a numeric Value (the weight) and a free-form Description; branch on Value and the row score, not on the Description text, which is human-readable and not a stable contract. Field names map to the webhook body (request_id ↔ request_id, score ↔ risk_score, parsed score_details ↔ signals). The example shows the core fields; a full snapshot also carries the connection, network, traffic-attribution, and per-signal flag columns. History reads through this API do not consume request balance and do not return 402.

Common search patterns

# Guaranteed-read fallback when a webhook may have been dropped.
curl "https://account.shieldlabs.ai/api/v1/history/request_id/550e8400-e29b-41d4-a716-446655440000?limit=1" \
  -H "Authorization: Bearer sec_your_private_api_key"

curl "https://account.shieldlabs.ai/api/v1/history/device_id/d290f1ee-6c54-4b01-90e6-d701748f0851?limit=20" \
  -H "Authorization: Bearer sec_your_private_api_key"

curl "https://account.shieldlabs.ai/api/v1/history/user_hid/e3b0c44298fc1c149afbf4c8996fb924?limit=50" \
  -H "Authorization: Bearer sec_your_private_api_key"

curl "https://account.shieldlabs.ai/api/v1/history/ip/203.0.113.10?limit=20" \
  -H "Authorization: Bearer sec_your_private_api_key"

Query by request_id with limit=1 when you only need one scored result. Reserve wider device_id / user_hid / ip searches for investigations.

Management API (`api.shieldlabs.ai`)

The Management API runs on api.shieldlabs.ai. It serves profile and balance, and an alternate History path that bills against your domain balance.

Authentication

Credentials in headers, not in the URL:

-H "X-Shield-Domain: myshop.com" \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Wrong credentials, an unknown domain, or a disabled domain return 401 with an empty body.

Endpoints at a glance

Method	Path	Auth	Purpose	Cost
`GET`	`/v1/history/{type}/{value}?limit=N`	Headers	Search snapshots (alternate History path)	1 request per returned row (minimum 1)
`GET`	`/v1/profile`	Headers	Domain config, balance, masked keys	Free (0 requests)

GET `/v1/profile`

Returns your domain’s configuration and current balance. Keys are masked to their last four characters. This call is free.

curl "https://api.shieldlabs.ai/v1/profile" \
  -H "X-Shield-Domain: myshop.com" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response

{
  "Domain":     "myshop.com",
  "Weight":     148230,
  "PublicKey":  "•••• a3f8",
  "Secret":     "•••• 9c2d",
  "CreatedAt":  "2026-01-15T09:00:00Z"
}

string

The registered domain this profile belongs to.

integer

Your remaining balance, measured in requests. One identification consumes 1 request, and the Management History API consumes 1 request per returned row. When this reaches 0, scoring and Management History calls return 402, as the Billing page details.

string

Your Public Key, masked to the last four characters. The browser-safe credential that goes in the snippet URL. Read the full value from the dashboard.

string

Your Secret Key, masked to the last four characters. Used for this API only. The full value is shown only at creation in the dashboard.

string

ISO 8601 UTC timestamp of when the domain was created.

GET `/v1/history/{type}/{value}`

Alternate History path on the Management API. Returns a JSON array of snapshot objects in PascalCase, newest first. Prefer the History API for new work.

curl "https://api.shieldlabs.ai/v1/history/request_id/550e8400-e29b-41d4-a716-446655440000?limit=1" \
  -H "X-Shield-Domain: myshop.com" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Path parameters

string

required

The field to search on. One of (same set as the History API):

ip: client IP address (IPv4 validated)
user_hid: the hashed user id you passed via the snippet (free-form string)
visitor_id: a VisitorID (UUID validated)
request_id: a single identification’s RequestID (UUID validated)
device_id: a DeviceID (UUID validated)
session_id: a SessionID (UUID validated)
cookie_id: a CookieID (UUID validated)

Any other value returns 404. A value in the wrong format (for example a non-UUID for device_id) returns 400.

string

required

The value to match for the chosen type. UUID types are UUID validated, ip is IPv4 validated, user_hid is a free string.

Query parameters

integer

default:"100"

Maximum number of rows to return. Capped at 100: a higher value is clamped to 100. Rows are ordered newest first.

Billing

The Management History API bills 1 request per returned row. An empty result still bills 1 request (the lookup itself). If your balance is insufficient for the result, the call returns 402.

The 1-request lookup charge is taken before the lookup is validated, so a 400 (malformed value) or 404 (unsupported {type}) still bills 1 request. Only 401 (bad credentials) and 402 (out of requests) cost 0.

The Snapshot object (Management API)

On api.shieldlabs.ai, History returns a superset of the webhook body: identity and score fields in PascalCase, plus connection and network detail captured during scoring.

{
  "RequestID":            "550e8400-e29b-41d4-a716-446655440000",
  "SessionID":            "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "CookieID":             "3f2e1d0c-9b8a-7654-3210-fedcba987654",
  "DeviceID":             "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "VisitorID":            "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "IP":                   "203.0.113.10",
  "OS":                   "Windows",
  "Browser":              "Chrome",
  "DeviceType":           "desktop",
  "Country":              "US",
  "UserHID":              "e3b0c44298fc1c149afbf4c8996fb924",
  "ConnectionType":       "vpn",
  "TcpMss":               1460,
  "MtuValue":             1500,
  "MtuHint":              "ethernet",
  "WebRtcHIP":            "203.0.113.10",
  "WebRtcCountry":        "US",
  "WebRtcConnectionType": "direct",
  "Score":                15,
  "Details": [
    { "Value": 15, "Description": "VPN" }
  ],
  "LastRequestTime":      "2026-06-16T10:00:00Z"
}

The identity and score fields map to the webhook body (request_id, risk_score, signals[{ name, weight }], …). Note the field name differs by surface: this PascalCase Management snapshot uses Score, the recommended account.shieldlabs.ai History rows use score, and the webhook data uses risk_score. See Snapshot.

string

Detected browser name, e.g. Chrome, Safari.

string

Form factor: desktop, mobile, or tablet.

string

The classified connection type, one of direct, mobile, vpn, proxy, tor, privacy_relay, browser_vpn_proxy, or unknown (when the type could not be resolved).

A snapshot also carries the Network Intelligence fields below. They describe the connection itself, are captured during scoring, and are useful for your own forensics and correlation.

integer

The TCP maximum segment size observed for the connection, a low-level network attribute captured during the network check.

integer

The network MTU (maximum transmission unit) derived from the connection.

string

A short label for the link type inferred from the MTU, for example ethernet.

string

The visitor’s local (host) IP observed during the network check. This is a server-side correlation field for the local-IP entity: keep it server-side and do not display it to end users.

string

Country derived from the network-check IP, used to cross-check against the public-IP Country.

string

Connection type classified from the network check, for example direct.

A snapshot is a point-in-time record of one identification. When a follow-up network check completes after the first score, the stored snapshot reflects the recomputed value (the webhook itself is sent once, after that follow-up window).

Reading the score

ShieldLabs scores. Your application decides. The Risk Score is a 0 to 100 number that falls into four Risk Score bands, and your code is the actor for allow, challenge, review, or block. Decide on Score + Details + action context, never the number alone: a legitimate user can score high behind a corporate proxy, a VPN, or a privacy browser. Tune your thresholds gradually, working from the per-band playbook and its worked examples.

Errors

Error bodies are not uniform across surfaces — branch on the HTTP status code first.

History API (`account.shieldlabs.ai`)

Status	Meaning	What to do
`200`	Success	Parse `data` and `total`. An empty `data` array is a valid result.
`401`	Bad or missing Private API Key	Check `Authorization: Bearer sec_…` and that the domain is enabled.
`500`	Internal error	Transient. Retry with backoff.

Management API (`api.shieldlabs.ai`)

Status	Meaning	What to do
`200`	Success	Parse the response. A History search with a valid `{type}` that matches nothing returns `200` with `[]` and still bills 1 request.
`400`	Bad parameters	A malformed value, e.g. a non-UUID where a UUID is required. Fix the request.
`401`	Bad credentials or disabled domain	Check `X-Shield-Domain`, `Authorization: Bearer`, and that the domain is enabled.
`402`	Out of requests	Balance exhausted (Management History needs 1 request per returned row). Top up from the Billing page.
`404`	Unsupported history type	`{type}` must be one of `ip`, `user_hid`, `visitor_id`, `request_id`, `device_id`.
`429`	Rate limit exceeded	Per-IP limit (20 req/min, 1-hour ban). Back off; see Rate limits. Body: `{"error":"too many requests"}`.
`503`	Gateway busy	Transient back-pressure. Retry with a short backoff. Body: `{"error":"server is busy"}`.
`500`	Internal error	Transient. Retry with backoff.

On the Management API, 401 and 402 return an empty body. 400 and 404 return a bare JSON string. The Errors page is the full reference across every surface.

Next steps

Data Models

The full Snapshot, webhook body, and Score Detail schemas in one place.

Webhooks

The push delivery path: payload, X-Shield-Signature verification, and delivery guarantees.

Identification Flow

How signals become a score and how the webhook and History API fit together.

Keys

Public Key, Private API Key, Secret Key — where each one belongs, and how to rotate.

Overview

Reference

See also

Base URLs

Authentication

Trying it out

History API (recommended)

Endpoints at a glance

GET `/api/v1/history/{search_type}/{value}`

Path parameters

Query parameters

Response

Common search patterns

Management API (`api.shieldlabs.ai`)

Authentication

Endpoints at a glance

GET `/v1/profile`

Response

GET `/v1/history/{type}/{value}`

Path parameters

Query parameters

Billing

The Snapshot object (Management API)

Reading the score

Errors

History API (`account.shieldlabs.ai`)

Management API (`api.shieldlabs.ai`)

Next steps

Data Models

Webhooks

Identification Flow

Keys

​See also

​Base URLs

​Authentication

​Trying it out

​History API (recommended)

​Endpoints at a glance

​GET /api/v1/history/{search_type}/{value}

​Path parameters

​Query parameters

​Response

​Common search patterns

​Management API (api.shieldlabs.ai)

​Authentication

​Endpoints at a glance

​GET /v1/profile

​Response

​GET /v1/history/{type}/{value}

​Path parameters

​Query parameters

​Billing

​The Snapshot object (Management API)

​Reading the score

​Errors

​History API (account.shieldlabs.ai)

​Management API (api.shieldlabs.ai)

​Next steps

Data Models

Webhooks

Identification Flow

Keys

See also

Base URLs

Authentication

Trying it out

History API (recommended)

Endpoints at a glance

GET `/api/v1/history/{search_type}/{value}`

Path parameters

Query parameters

Response

Common search patterns

Management API (`api.shieldlabs.ai`)

Authentication

Endpoints at a glance

GET `/v1/profile`

Response

GET `/v1/history/{type}/{value}`

Path parameters

Query parameters

Billing

The Snapshot object (Management API)

Reading the score

Errors

History API (`account.shieldlabs.ai`)

Management API (`api.shieldlabs.ai`)

Next steps