HTTP API

Base URL: https://your-shieldgate-host/api/public

POST /decide

The core cloaking decision.

POST /api/public/decide
Content-Type: application/json

{
  "site_key": "sk_live_...",
  "visitor": {
    "ua":       "Mozilla/5.0 ...",
    "referrer": "https://facebook.com/...",
    "url":      "https://your-site.com/landing?utm_source=fb"
  }
}

Network identity, country, ASN, rate-limit keys, and challenge evidence are derived and verified by the server. Client-submitted network fields are telemetry-only and must not be used as authorization or decision evidence.

Response:

{
  "verdict": "allow" | "challenge" | "block",
  "action":  "money" | "white" | "block",
  "url":     "https://offer.com/?utm_source=fb",
  "mode":    "redirect",
  "ttl":     30
}

POST /track

Record events (pageviews, clicks, conversions).

POST /api/public/track
{
  "site_key": "sk_live_...",
  "session":  "sess_abc",
  "kind":     "pageview" | "click" | "conversion" | "custom",
  "name":     "purchase",
  "path":     "/checkout",
  "meta":     { "revenue": 129.00 }
}

GET /postback/{siteKey}

Voluum / Binom / Bemob-compatible conversion postback.

GET /api/public/postback/YOUR_SITE_KEY
     ?cid=CLICK_ID&payout=1.20&status=approved&sig=HMAC

sig = HMAC-SHA256(query_string, site.hmac_secret). Requests without a valid signature are rejected.

GET /check

Tenant-aware site check. It resolves the site key to an active organization and returns a no-store decision/status response; unknown, suspended, deleting, or unavailable tenants fail closed and never expose site configuration.

GET /cloak.js

Serves the client SDK. See SDK docs.

GET /wp-plugin/{siteKey}

Downloads a pre-configured WordPress plugin ZIP for the given site.

GET /stream/site/{siteKey}

Server-Sent Events feed of events for the site (anonymized kind, occurred_at, path). Sends a heartbeat every few seconds. Ideal for partner dashboards and live displays.

const es = new EventSource('/api/public/stream/site/YOUR_SITE_KEY');
es.onmessage = (e) => console.log(JSON.parse(e.data));

Short links: /s/{code}

Public short link — 302s to the destination after running the full cloak pipeline. Supports HMAC signing (?sig=...&ts=...) to prevent link scraping — see the security page.

Rate limits

Each site + IP is rate-limited (default: 60 requests / minute). Blocked requests return HTTP 429 with a Retry-After header.

Errors