Skip to main content
ShieldLabs has a small, focused API surface. You install a snippet, you receive scored results, and you read history when you need a guaranteed pull. ShieldLabs scores every visit; your own code decides whether to allow, challenge, review, or block.

​
The three surfaces

JS snippet

Collects browser, device, and network signals and posts them to rest.shieldlabs.ai automatically. You install it once; you do not call this endpoint yourself.

Webhooks

Push delivery. ShieldLabs POSTs the Risk Score and signals to each endpoint you register in the dashboard, about a second after a visit.

Server API

Pull. Call from your backend to read scored snapshots (History API) and, when needed, your domain profile and balance (Management API).
A typical integration uses all three: the snippet runs on your pages, webhooks deliver scores in real time, and the History API is your guaranteed fallback for anything a webhook might miss.

​
Hosts

The development hosts mirror these for local and staging work (dev.account.shieldlabs.ai/api, dev.cdn.shieldlabs.ai, …).

​
Authentication

Each domain has three server credentials plus per-webhook signing secrets. They are not interchangeable. History API (recommended for snapshot reads):
Management API (profile and balance):
Private API Keys and Secret Keys must never appear in the browser, the snippet, client logs, or a public repository. If one leaks, rotate it from the dashboard. The Keys page covers where each credential belongs.

​
No synchronous score endpoint (today)

There is no request that returns a Risk Score in its response. Scoring is asynchronous: it combines IP reputation, network analysis, and a follow-up network check that take about a second to resolve. So the snippet posts signals, ShieldLabs scores them, and the result reaches you by webhook and through the History API.
A cleaner synchronous server endpoint (POST /v1/verify) is planned but not yet available. Integrate today via webhooks plus the History API, both documented here. The RequestID is the join key that ties a snapshot, its webhooks, and its history rows together.

​
Billing and limits

  • One identification consumes 1 request from your domain balance.
  • The Management API History path on api.shieldlabs.ai consumes 1 request per returned row (an empty result still costs 1). The History API on account.shieldlabs.ai does not bill per row.
  • Reading your profile, receiving webhooks, viewing the dashboard, and History reads through account.shieldlabs.ai are free.
  • The Management API history path returns at most 100 rows per call. The History API defaults to 20 rows and accepts a limit up to 100.
  • When the balance reaches 0, new identifications and Management API history calls return 402, as the Billing page details.
  • Infrastructure rate limits protect the gateways and never feed the Risk Score.

​
Conventions

  • Responses are JSON. Error bodies are not uniform, so branch on the HTTP status code rather than parsing a body field. The Errors page enumerates each case.
  • Timestamps are ISO 8601 UTC on the Management API; the History API may return ClickHouse datetime strings in created_at.
  • Identifiers (RequestID, DeviceID, VisitorID, SessionID, CookieID) are UUIDs. UserHID is your own hashed user id, a free-form string.

​
Next steps

Identification Flow

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

Webhooks

The flat webhook payload, X-Shield-Signature verification, and delivery guarantees.

Server API

History API, Management API profile, and full request and response detail.

Data Models

WebhookEvent, Snapshot, WebhookSignal, ScoreDetail, and Profile schemas in one place.