CloakMe API Reference

Programmatic access to intelligent traffic routing

The CloakMe API allows developers to create, manage, and analyze redirect links with advanced bot detection and traffic filtering built in. Your links automatically block bots, email scanners, VPNs, and ad reviewers — routing real humans to your offer URL while sending filtered traffic to your white URL.

Base URL https://api.cloakme.ru/api/developer

Auth header X-API-Key: your_api_key_here

Content-Type application/json

Authentication

All API requests must include your API key in the X-API-Key header. You can find your API key in the dashboard under Settings → API Key.

# Using X-API-Key header (recommended)
curl https://api.cloakme.ru/api/developer/me \
  -H "X-API-Key: YOUR_API_KEY"

# Using Authorization Bearer
curl https://api.cloakme.ru/api/developer/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Security notice: Your API key grants full access to your account. Never expose it in client-side code or public repositories. Rotate it immediately if compromised.

Base URL

The API is available at:

https://api.cloakme.ru/api/developer

All responses are JSON. Timestamps are ISO 8601 UTC.

Rate Limits

Requests are rate-limited per API key. If you exceed a limit you will receive a 429 Too Many Requests response.

Endpoint	Limit
All API endpoints	60 requests / minute per API key
`POST /links`	10 requests / minute
`GET /links/{id}/stats`	30 requests / minute

Rate limit response headers

Every API response includes the following headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1705312800

429 response body

{
  "detail": "Rate limit exceeded. Retry after 12 seconds."
}

Errors

CloakMe uses standard HTTP status codes. All error responses include a human-readable detail field.

{
  "detail": "Human-readable error message"
}

Status	Meaning
200 OK	Request succeeded
201 Created	Resource created successfully
400 Bad Request	Invalid parameters or malformed request body
401 Unauthorized	Missing or invalid API key
403 Forbidden	Insufficient permissions for this resource
404 Not Found	Resource does not exist
422 Unprocessable Entity	Request body failed validation
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	An unexpected error occurred on our end

GET

List Links

GET /api/developer/links

Returns all redirect links for your account.

200 Response

{
  "links": [
    {
      "id": 1,
      "name": "Summer Campaign",
      "token": "E0DcgZAboh5K0cUz_o3a7",
      "redirect_url": "https://cloakme.ru/go/E0DcgZAboh5K0cUz_o3a7",
      "offer_url": "https://offer.example.com/landing",
      "white_url": "https://safe.example.com",
      "is_active": true,
      "filters": {
        "block_bots": true,
        "block_vpn": false,
        "block_datacenter": false,
        "block_email_scanners": true,
        "allowed_countries": ["US", "GB", "CA"],
        "blocked_countries": []
      },
      "total_clicks": 1482,
      "offer_clicks": 1091,
      "white_clicks": 391,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Code examples

curl https://api.cloakme.ru/api/developer/links \
  -H "X-API-Key: YOUR_API_KEY"

import requests

links = requests.get(
    "https://api.cloakme.ru/api/developer/links",
    headers={"X-API-Key": "YOUR_API_KEY"}
).json()

for link in links["links"]:
    print(f"{link['name']}: {link['redirect_url']}")

$ch = curl_init("https://api.cloakme.ru/api/developer/links");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);

const res = await fetch("https://api.cloakme.ru/api/developer/links", {
  headers: { "X-API-Key": "YOUR_API_KEY" }
});
const { links } = await res.json();

POST

Create Link

POST /api/developer/links

Creates a new redirect link. The returned redirect_url is the URL you share in emails, ads, or embed in your app. All bot detection and filtering is applied automatically when a visitor hits that URL.

Request body

Field	Type	Description
`name` required	string	Human-readable label for this link
`offer_url` required	string	Destination URL for real human traffic
`white_url` required	string	Destination URL for filtered/bot traffic
`filters`	object	Filter configuration — see filters object below. All fields are optional.
`is_active`	boolean	Whether the link is active. Default: `true`

Filters object

All filter fields are optional. The values below are defaults.

{
  "block_bots": true,
  "block_vpn": false,
  "block_datacenter": false,
  "block_proxy": false,
  "block_tor": false,
  "block_ad_platforms": true,
  "block_email_scanners": true,
  "allowed_countries": [],     // empty = all countries allowed
  "blocked_countries": [],
  "allowed_devices": [],
  "allowed_browsers": [],
  "blocked_ip_ranges": []
}

Note: block_email_scanners is always enforced regardless of this setting.

201 Response — full link object

Code examples

curl -X POST https://api.cloakme.ru/api/developer/links \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Email Campaign",
    "offer_url": "https://offer.example.com/summer",
    "white_url": "https://safe.example.com",
    "filters": {
      "block_bots": true,
      "block_vpn": true,
      "allowed_countries": ["US", "CA", "GB"]
    }
  }'

import requests

link = requests.post(
    "https://api.cloakme.ru/api/developer/links",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "name": "Summer Email Campaign",
        "offer_url": "https://offer.example.com/summer",
        "white_url": "https://safe.example.com",
        "filters": {
            "block_bots": True,
            "block_vpn": True,
            "allowed_countries": ["US", "CA", "GB"]
        }
    }
).json()

print(f"Share this URL: {link['redirect_url']}")

$payload = json_encode([
    "name"      => "Summer Email Campaign",
    "offer_url" => "https://offer.example.com/summer",
    "white_url" => "https://safe.example.com",
    "filters"   => [
        "block_bots"         => true,
        "block_vpn"          => true,
        "allowed_countries" => ["US", "CA", "GB"]
    ]
]);

$ch = curl_init("https://api.cloakme.ru/api/developer/links");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: YOUR_API_KEY",
        "Content-Type: application/json"
    ]
]);
$link = json_decode(curl_exec($ch), true);

const link = await fetch("https://api.cloakme.ru/api/developer/links", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Summer Email Campaign",
    offer_url: "https://offer.example.com/summer",
    white_url: "https://safe.example.com",
    filters: {
      block_bots: true,
      block_vpn: true,
      allowed_countries: ["US", "CA", "GB"]
    }
  })
}).then(r => r.json());

console.log(`Share this URL: ${link.redirect_url}`);

GET

Get Link

GET /api/developer/links/{id}

Returns a single link by its ID. The response is the full link object, identical in structure to items returned by List Links.

200 Response — full link object

curl https://api.cloakme.ru/api/developer/links/1 \
  -H "X-API-Key: YOUR_API_KEY"

import requests

link = requests.get(
    "https://api.cloakme.ru/api/developer/links/1",
    headers={"X-API-Key": "YOUR_API_KEY"}
).json()

const link = await fetch("https://api.cloakme.ru/api/developer/links/1", {
  headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json());

PATCH

Update Link

PATCH /api/developer/links/{id}

Partially updates a link. Send only the fields you want to change — omitted fields remain unchanged. To update filters, send the entire filters object with the values you want; individual filter fields are merged.

Request body

Field	Type	Description
`name`	string	New label for the link
`offer_url`	string	New offer destination URL
`white_url`	string	New white destination URL
`is_active`	boolean	Enable or disable the link
`filters`	object	Updated filter settings (partial updates supported)

{
  "name": "Updated Campaign Name",
  "offer_url": "https://new-offer.example.com",
  "white_url": "https://safe.example.com",
  "is_active": false,
  "filters": { "block_vpn": true }
}

200 Response — updated link object

curl -X PATCH https://api.cloakme.ru/api/developer/links/1 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

import requests

updated = requests.patch(
    "https://api.cloakme.ru/api/developer/links/1",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_active": False}
).json()

const updated = await fetch("https://api.cloakme.ru/api/developer/links/1", {
  method: "PATCH",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ is_active: false })
}).then(r => r.json());

DELETE

Delete Link

DELETE /api/developer/links/{id}

Permanently deletes a link and all associated click data. This action cannot be undone. The link's redirect_url will immediately stop functioning.

200 Response

{
  "deleted": true,
  "id": 1
}

curl -X DELETE https://api.cloakme.ru/api/developer/links/1 \
  -H "X-API-Key: YOUR_API_KEY"

import requests

result = requests.delete(
    "https://api.cloakme.ru/api/developer/links/1",
    headers={"X-API-Key": "YOUR_API_KEY"}
).json()

print(result["deleted"])  # True

const result = await fetch("https://api.cloakme.ru/api/developer/links/1", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json());

GET

Link Stats

GET /api/developer/links/{id}/stats

Returns click statistics and recent click history for a link. offer_rate is the percentage of visitors who passed all filters and were sent to your offer URL.

200 Response

{
  "link_id": 1,
  "total_clicks": 1482,
  "offer_clicks": 1091,
  "white_clicks": 391,
  "offer_rate": 73.6,
  "recent_clicks": [
    {
      "ip": "98.45.21.100",
      "country": "US",
      "city": "New York",
      "device": "desktop",
      "browser": "chrome",
      "os": "windows",
      "action": "offer",
      "filter_reason": null,
      "at": "2024-01-15T14:22:10Z"
    }
  ]
}

Click action values

Field	Values	Description
`action`	`"offer"` `"white"`	`offer` — real human, sent to offer URL. `white` — filtered, sent to white URL.
`filter_reason`	string or null	Why traffic was filtered. Examples: `"bot_ua"`, `"email_scanner_org:microsoft"`, `"vpn"`, `"country_blocked"`. `null` when action is `"offer"`.

curl https://api.cloakme.ru/api/developer/links/1/stats \
  -H "X-API-Key: YOUR_API_KEY"

import requests

stats = requests.get(
    "https://api.cloakme.ru/api/developer/links/1/stats",
    headers={"X-API-Key": "YOUR_API_KEY"}
).json()

print(f"Offer rate: {stats['offer_rate']}%")

const stats = await fetch("https://api.cloakme.ru/api/developer/links/1/stats", {
  headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json());

console.log(`Offer rate: ${stats.offer_rate}%`);

GET

Get Account

GET /api/developer/me

Returns your account information, API key, and current plan usage. Use this endpoint to check remaining click quota and campaign limits.

200 Response

{
  "id": 42,
  "email": "you@example.com",
  "username": "yourname",
  "api_key": "9026dadd46d019...",
  "is_active": true,
  "created_at": "2024-01-01T00:00:00Z",
  "usage": {
    "plan": "starter",
    "plan_display": "Starter",
    "clicks_used": 8432,
    "clicks_limit": 25000,
    "clicks_remaining": 16568,
    "usage_pct": 33.7,
    "campaign_limit": 5
  }
}

curl https://api.cloakme.ru/api/developer/me \
  -H "X-API-Key: YOUR_API_KEY"

import requests

account = requests.get(
    "https://api.cloakme.ru/api/developer/me",
    headers={"X-API-Key": "YOUR_API_KEY"}
).json()

usage = account["usage"]
print(f"{usage['clicks_used']:,} / {usage['clicks_limit']:,} clicks used")

const account = await fetch("https://api.cloakme.ru/api/developer/me", {
  headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json());

const { clicks_used, clicks_limit } = account.usage;
console.log(`${clicks_used.toLocaleString()} / ${clicks_limit.toLocaleString()} clicks used`);

GET

Direct Redirect

GET /go/{token}

Browser redirect endpoint. Use the redirect_url returned by the API as the link you share with end users — it points to this endpoint. No authentication is required.

How it works

The visitor's IP, user-agent, and referrer are evaluated against your link's filters
If they pass all checks (real human): 302 redirect to your offer_url via the JS challenge gate
If they are filtered (bot, scanner, VPN, bad country, etc.): 302 redirect to your white_url

Example

https://cloakme.ru/go/E0DcgZAboh5K0cUz_o3a7

This URL is safe to embed in email campaigns, paid ads, SMS, or any channel where bots and ad reviewers may follow your links before real users do.

No authentication needed. This is the public-facing redirect URL. The token uniquely identifies which link to use — keep your offer_url private; only share the redirect_url.

Ready to start?

Get your API key and start building in minutes.

Get your API key →