Sentinel API Reference

Authentication

Authenticated API endpoints live under /api/v1 and are authenticated with an API key sent in the X-Api-Key request header. Every request is scoped to the key's owner, plan and quota.

Header

X-Api-Key: rk_xxxxxxxx_your_secret

Identity & quota

Returns the calling API key's identity, plan, remaining credits and quota. Useful for confirming a key works and checking limits before a batch of calls.

Example request

curl https://redeyed.com/api/v1/me \
  -H "X-Api-Key: rk_xxxxxxxx_your_secret"

Example response

{
  "key": {
    "name": "Production",
    "prefix": "xxxxxxxx",
    "scopes": ["ip:read", "verify"],
    "last_used_at": "2026-06-22T01:14:09Z"
  },
  "plan": "team",
  "credit_balance": 9820,
  "quota": 48000
}

IP reputation

Scores an IP address. Omit {ip} to score the caller's own IP. Returns a 0–100 score, a risk band, flags (proxy / VPN / Tor / datacenter / bot / abuser), geolocation and ASN. Each lookup is recorded as a behavioral signal for the reputation engine.

Path parameters

Example request

curl https://redeyed.com/api/v1/ip/8.8.8.8 \
  -H "X-Api-Key: rk_xxxxxxxx_your_secret"

Example response

{
  "ip": "8.8.8.8",
  "score": 72,
  "risk": "medium",
  "flags": {
    "is_proxy": false,
    "is_vpn": false,
    "is_tor": false,
    "is_datacenter": true,
    "is_residential_proxy": false,
    "is_bot": false,
    "is_abuser": false
  },
  "connection_type": "hosting",
  "network_kind": "hosting",
  "country_code": "US",
  "asn": 15169,
  "asn_org": "Google LLC",
  "signals": { /* score breakdown */ },
  "evidence": { "datacenter": "confirmed" },
  "confidence": 61,
  "last_seen_at": "2026-06-22T01:10:00Z",
  "usage": { /* request quota usage */ }
}

Verify a captcha

Server-to-server human verification — reCAPTCHA/Turnstile style. From your backend, post your site's Secret Key together with the response token your form collected from the widget. The secret alone identifies and authorizes the site, so no developer API key is required. Returns the outcome band, score and reason.

Body parameters

Example request

curl -X POST https://redeyed.com/captcha/siteverify \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "st_sec_xxxxxxxxxxxxxxxxxxxx",
    "response": "captcha-token-from-widget",
    "remoteip": "203.0.113.42"
  }'

Example response

{
  "success": true,
  "outcome": "passed",   // passed | challenged | blocked
  "score": 18,
  "reason": "Acceptable risk (score 18)",
  "hostname": "yoursite.com",
  "error-codes": []
}

Outcomes: passed — allow the request; challenged — re-prompt or step up; blocked — deny (high-risk IP or detected automation).

Alternative: the developer API

Already using the /api/v1 key-based API? You can also verify with POST /api/v1/verify (X-Api-Key + site_key + token). It returns the same outcome. For a plain captcha integration, prefer /captcha/siteverify above.

Widget embed

The Sentinel widget is a self-contained, vanilla-JS captcha — no build step. Load the script once, then drop a .redeyed-captcha element with your site key inside any form. The widget auto-mounts, runs the challenge, and injects a hidden captcha-token input on success.

Embed

<!-- Load once, anywhere on the page -->
<script src="https://redeyed.com/captcha.js" async></script>

<!-- Place inside the form you want to protect -->
<form method="POST" action="/signup">
  <!-- ...your fields... -->
  <div class="redeyed-captcha" data-sitekey="site_xxxxxxxxxxxx" data-width="full"></div>
  <button type="submit">Create account</button>
</form>

On success the widget appends <input type="hidden" name="captcha-token"> to the enclosing form and fires a captcha:solved event. Submit the token to your backend and confirm it with POST /captcha/siteverify (your Secret Key + the token). You can also drive the widget programmatically with window.Captcha.render() and window.Captcha.reset().

Customize per form

The same site key works everywhere — add optional data-* attributes to each .redeyed-captcha element to tune the widget per form. All are optional.

Procedural visual challenges include a keyboard-accessible verification switch. Visitors who prefer reduced motion are moved automatically to the non-animated press-and-hold proof.

<div class="redeyed-captcha"
     data-sitekey="site_xxxxxxxxxxxx"
     data-widget="press_hold"
     data-theme="dark"
     data-difficulty="hard"></div>

Attack mode

Raise the challenge floor for every visitor to your site, immediately. Sentinel already arms this on its own when it sees a flood, but detection is reactive — it can only trip once traffic has been arriving for a counter window. Your WAF, CDN or on-call alerting usually notices first, so this endpoint lets that system raise the floor without a human opening a browser.

Authenticated with your site's Secret Key, like /captcha/siteverify — no X-Api-Key. The change is scoped to the site that key belongs to.

Request

Example request

curl -X POST https://redeyed.com/captcha/attack-mode \
  -H "Content-Type: application/json" \
  -d '{"secret":"st_sec_xxxxxxxx","state":"under_attack","minutes":30}'

Example response

{
  "success":    true,
  "state":      "under_attack",
  "held":       true,
  "expires_in": 1800,
  "hostname":   "example.com",
  "applies": {
    "risk_band":        "medium",
    "difficulty_floor": 5,
    "rounds_floor":     3
  }
}

Clearing it

curl -X POST https://redeyed.com/captcha/attack-mode \
  -H "Content-Type: application/json" \
  -d '{"secret":"st_sec_xxxxxxxx","state":"normal"}'

A hold expires on its own, so a forgotten one cannot punish your site indefinitely.

Attack alerts

Sentinel raises your challenge floor by itself when it detects a flood — on every plan, including free. Alerts tell you the moment it happens, so you can look at your own logs while it is going on rather than reading about it in a support ticket the next morning.

Configure a webhook URL and/or an email under Sentinel → Sites → your site. Alerts need an active Sentinel Pro add-on; the protection they report on does not.

Payload

{
  "event":       "attack_mode.changed",
  "site":        "example.com",
  "from":        "normal",
  "to":          "under_attack",
  "direction":   "raised",
  "occurred_at": "2026-08-25T14:03:11+00:00",
  "applies": {
    "risk_band": "medium", "difficulty_floor": 5, "rounds_floor": 3
  }
}

applies is null when direction is cleared.

Verifying the signature

Every call carries X-Sentinel-Timestamp and X-Sentinel-Signature. The signature is an HMAC-SHA256 of timestamp + "." + rawBody, keyed with the signing secret shown once when you saved the webhook.

PHP

$raw  = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_SENTINEL_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_SENTINEL_SIGNATURE'] ?? '';

$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);

// Constant-time compare, and reject anything older than five minutes so a
// captured call cannot be replayed at you later.
if (!hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(400);
    exit;
}

Network operators

If you run the address space we score — a VPN, a host, an ISP — you see the consequences of our verdicts without any view of the cause: one abuser on a shared exit degrades that address for every legitimate user behind it, and the first you hear of it is a support ticket saying "your service is broken".

These endpoints give you that view for your own networks, so the responsible account can be terminated and the address can recover. They require Sentinel Pro and an X-Api-Key.

Your claims and their status. verified_networks: 0 means nothing else here will return data yet.

Reputation for up to 500 addresses in one call, for operators holding thousands of exits. Billed per address resolved, the same as asking for each one individually — batching saves round trips, not money. Addresses you have not claimed are allowed here: it returns only what the per-IP endpoint already would.

curl -X POST https://redeyed.com/api/v1/network/bulk \
  -H "X-Api-Key: rk_xxxxxxxx_your_secret" \
  -H "Content-Type: application/json" \
  -d '{"ips":["203.0.113.4","198.51.100.7"]}'

An address we have never seen comes back "known": false with a null score, rather than being reported as clean. Absence of evidence is not evidence.

Per-ASN summary: how many addresses we know, the split by risk band, and the worst offenders first. The question you actually have when tickets start arriving.

Abuse observed on your verified networks. Takes since (ISO 8601, default 7 days) and limit (max 1000).

{
  "since": "2026-08-18T00:00:00+00:00",
  "count": 2,
  "events": [
    { "ip": "203.0.113.4", "observed_at": "…", "category": "automation", "severity": "high" }
  ]
}

Capabilities

Returns every challenge type, colour scheme, theme and difficulty level this deployment accepts. No API key and no Site Key — the widget script already ships the same tables to the browser. Cached for 5 minutes.

Use it instead of hardcoding a list. An unrecognised data-widget is not an error — it falls back to the site default — so a stale hardcoded list keeps working while silently ignoring the setting. Plugin settings screens should build their dropdown from this endpoint.

Example request

curl https://redeyed.com/captcha/capabilities

Example response

{
  "widget_version": "20260824c",
  "types": {
    "meta":     ["adaptive", "all"],
    "concrete": ["behavioral", "pow", "press_hold", …, "shape_match", "count_match"],
    "default":  "press_hold"
  },
  "themes":  ["light", "dark", "auto"],
  "schemes": [
    { "name": "default",  "premium": false },
    { "name": "midnight", "premium": true  }
  ],
  "difficulty": { "named": ["easy","medium","hard","max"], "min": 1, "max": 6, "raises_only": true }
}

Challenge types

Set with data-widget. Two values are resolved server-side rather than naming a concrete challenge:

Concrete types

Colour schemes

Set with data-scheme. Themed schemes tint the surface and compose with data-theme (light / dark / auto). Fixed schemes carry their own surface and ignore the theme. Animated schemes paint a moving backdrop and require a paid plan.

<div class="redeyed-captcha"
     data-sitekey="site_xxxxxxxxxxxx"
     data-scheme="cyber"
     data-theme="dark"></div>

JavaScript API

Loading captcha.js defines window.Captcha. Any .redeyed-captcha[data-sitekey] element on the page mounts automatically on load — you only need these for widgets you add or reset dynamically.

Events

On success the widget dispatches a bubbling captcha:solved CustomEvent whose detail.token is the single-use token, and writes that token into a hidden captcha-token input in the enclosing form.

document.addEventListener('captcha:solved', function (e) {
  // Send e.detail.token to your server and verify it there.
  console.log(e.detail.token);
});

// Re-arm after a rejected submit
window.Captcha.reset('#signup .redeyed-captcha');

Drop-in replacement

Migrating from reCAPTCHA, hCaptcha or Turnstile needs no markup changes. Swap the provider's script for captcha.js and keep your existing container — Sentinel adopts it and writes the response field your server already reads.

The explicit JS APIs keep working too: grecaptcha, hcaptcha and turnstile shims are defined only when the real provider script is absent, so a live install is never clobbered. render(), reset(), ready() and getResponse() all behave as expected.

Server-side, these paths accept your existing verify payload and return the same response shape, so only the hostname changes:

POST https://redeyed.com/recaptcha/api/siteverify
POST https://redeyed.com/hcaptcha/siteverify
POST https://redeyed.com/turnstile/v0/siteverify

Challenge / solve flow

The widget uses two same-origin endpoints under the hood. You normally never call these directly, but they're documented for custom integrations.

1. Issue a challenge

Issues an adaptive proof-of-work challenge for a site key. Difficulty scales with the IP's live risk band; high-risk IPs are blocked rather than challenged.

Request & response

curl -X POST https://redeyed.com/captcha/challenge \
  -H "Content-Type: application/json" \
  -d '{ "site_key": "site_xxxxxxxxxxxx" }'

// 200 OK
{
  "challenge_id": "aZ8...40-char-token",
  "nonce": "16-char-nonce",
  "difficulty": 3
}
// 403 { "error": "Access denied.", "blocked": true } for high-risk IPs

2. Solve the challenge

Find an integer solution so that sha256(nonce + solution) starts with difficulty leading hex zeros, then post it back. The server recomputes the hash, checks it's unsolved / unexpired / IP-matched, and mints a short-lived HMAC token.

Request & response

curl -X POST https://redeyed.com/captcha/solve \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_id": "aZ8...40-char-token",
    "solution": "104729",
    "telemetry": { "solve_ms": 380, "pointer_entropy": 0.42 }
  }'

// 200 OK
{
  "token": "signed-captcha-token",
  "bot_likelihood": 7
}

Submit the returned token with your form, then confirm it server-side via POST /captcha/siteverify (your Secret Key + the token).

Reputation response fields

Fields returned by GET /api/v1/ip/{ip}.