Client API¶

The Client API checks a visitor IP (and optional user agent) and returns allow or block. It does not use a campaign ID. You decide what to do with the result in your own app.

• One credit is deducted per check call.
• action=credits returns your balance and does not deduct a credit.
• Call it from your server. Never put the token in public JavaScript or a mobile app binary.

Your token and live examples are also on API in the dashboard: https://ai.cloakerly.com/client-api.

Endpoint¶

POST or GET  https://api.cloakerly.com/client/v1/

JSON responses. CORS allows browser calls, but the token must stay private — use a backend.

Authentication¶

Send your client token in one of these ways (format api_user_id:api_key):

Copy the token from API in the dashboard. Do not share it.

Actions¶

If credits are 0, check returns HTTP 402 insufficient_credits. Top up on Plans.

Check request¶

You can send GET query parameters, POST form fields, or POST application/json.

Decision rules¶

These rules apply to check. Campaign filters (countries, OS, UTM, affiliate URLs) are not applied.

• Always block: proxy, Tor, scraper, compromised, anonymous, high risk score, and known bad networks
• Block VPN unless allow_vpn=1
• Block hosting / datacenter unless allow_datacenter=1

Success response (check)¶

{
  "ok": true,
  "decision": "block",
  "reasons": ["vpn_not_allowed"],
  "ip": "203.0.113.10",
  "ip_version": "4",
  "device": "mobile",
  "os": "IOS",
  "accept_language": "en-US,en;q=0.9",
  "location": {
    "country_code": "US",
    "country_name": null,
    "region_name": null,
    "city_name": "Los Angeles",
    "timezone": null
  },
  "network": {
    "asn": "AS13335",
    "provider": null,
    "organisation": null,
    "type": "Hosting",
    "hostname": null
  },
  "detections": {
    "proxy": false,
    "vpn": true,
    "hosting": true,
    "tor": false,
    "scraper": false,
    "compromised": false,
    "anonymous": false,
    "risk_score": 88,
    "confidence": null
  },
  "credits_remaining": 1499,
  "response_time_ms": 210
}

Common reasons¶

Credits response¶

{
  "ok": true,
  "subscription_type": "pay",
  "credits_remaining": 1499
}

Errors¶

All errors are JSON: { "ok": false, "error": "...", "message": "..." }.

Examples¶

Replace USER_ID:API_KEY with the token from API in the dashboard.

cURL — check¶

curl -X POST 'https://api.cloakerly.com/client/v1/' \
  -H 'Accept: application/json' \
  -d 'client_token=USER_ID:API_KEY' \
  -d 'ip=203.0.113.10' \
  -d 'user_agent=Mozilla/5.0'

cURL — credits (no deduction)¶

curl 'https://api.cloakerly.com/client/v1/?action=credits&client_token=USER_ID:API_KEY' \
  -H 'Accept: application/json'

PHP¶

<?php
$ch = curl_init('https://api.cloakerly.com/client/v1/');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => ['Accept: application/json'],
    CURLOPT_POSTFIELDS     => http_build_query([
        'client_token' => 'USER_ID:API_KEY',
        'ip'           => $_SERVER['REMOTE_ADDR'] ?? '',
        'user_agent'   => $_SERVER['HTTP_USER_AGENT'] ?? '',
    ]),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($result['ok']) && ($result['decision'] ?? '') === 'allow') {
    // Real visitor
} else {
    // Filtered traffic (VPN, proxy, hosting, etc.)
}

Using it with campaigns¶

The Client API is a standalone lookup. It does not redirect to Safe or affiliate URLs. For landing-page filtering with campaigns, use the SCRIPT integration instead — see Integration.