API Documentation

Everything you need to integrate the Cloackit cloaking engine — no login required.

API Docs

REST reference for the Cloackit decision engine and dashboard resources. All endpoints are served under https://cloackit.com.

Getting started

Base URL. Every path below is relative to https://cloackit.com. Requests and responses are JSON unless noted otherwise.

Two auth schemes. Dashboard endpoints (keys, flows, stats) authenticate with a Bearer JWT — the same token the dashboard stores after login. The core decision endpoint POST /api/v1/check instead uses your API key via the X-Api-Key header (or a ?key= query param), so it can be called server-side from the cloaked landing page without exposing a login session.

Bearer auth (dashboard endpoints)

Authorization: Bearer <jwt>

API-key auth (the check endpoint)

X-Api-Key: <your-api-key>

Each /api/v1/checkcall charges one credit from the key owner's monthly quota. When the quota is exhausted the endpoint returns 402 with verdict: "block" so the cloaker safe-defaults the visitor to the white page.

POST/api/v1/check

The core cloaking decision. Scores a visitor (IP / UA / headers / fingerprint / behavior) against your rules and intel feeds and returns a verdict. Called server-side by the generated PHP file. Authenticated with X-Api-Key.

Request — headers

X-Api-Key: <your-api-key>
Content-Type: application/json

Request — body

{
  "ip": "203.0.113.7",
  "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) ...",
  "url": "https://offer.example.com/lp?utm_source=fb",
  "headers": { "accept-language": "en-US,en;q=0.9" },
  "fingerprint": null,
  "behavior": null,
  "flow_id": 12,
  "allow_known_bots": false,
  "allow_blocklist_hits": false,
  "allow_datacenter": false
}

All body fields are optional. If ip / uaare omitted the engine falls back to the request's own connection IP and User-Agent header. Pass flow_idto attribute the event to a flow and apply that flow's gates (country blocks, warmup, per-IP daily cap).

Response — 200

{
  "verdict": "allow",
  "score": 12,
  "reasons": ["rep_trusted"],
  "rule_matched": null,
  "country": "US",
  "asn": 7922,
  "org": "Comcast Cable",
  "ip": "203.0.113.7",
  "flow_clicks_today": 1,
  "credits_remaining": 9842
}

verdict is one of allow, flag, challenge, block. The PHP cloaker shows the money page only on allow.

Response — 402 (quota exhausted)

{
  "verdict": "block",
  "reasons": ["quota_exhausted"],
  "score": 100,
  "error": "monthly_quota_exhausted",
  "action": "upgrade_or_wait_for_reset"
}

GET/api/v1/flows

List every flow on your account, newest first. A flow bundles a white URL, a money URL, the API key it calls with, and all filter knobs. Authenticated with a Bearer JWT.

Request — headers

Authorization: Bearer <jwt>

Response — 200

{
  "flows": [
    {
      "id": 12,
      "name": "FB — iOS offer",
      "key_id": 3,
      "white_url": "https://safe.example.com/",
      "white_mode": "redirect",
      "money_url": "https://offer.example.com/lp",
      "money_mode": "redirect",
      "cloaking_enabled": true,
      "block_vpn_proxy": true,
      "block_ipv6": false,
      "allow_known_bots": false,
      "allow_datacenter": false,
      "max_clicks_per_ip_per_day": 1,
      "warmup_clicks": 0,
      "blocked_countries": "IN,PK",
      "allowed_devices": "mobile",
      "status": "active",
      "created_at": "2026-04-28 10:11:02"
    }
  ]
}

GET/api/v1/flows/:id/php

Download the self-contained PHP cloaker for a flow. The generated file embeds the flow's API key and flow_id, calls POST /api/v1/check on each visitor, and routes to the white or money page. Authenticated with a Bearer JWT.

Request — headers

Authorization: Bearer <jwt>

Response — 200

Returns the raw PHP file (not JSON) with Content-Type: application/x-httpd-php and a download disposition:

Content-Type: application/x-httpd-php
Content-Disposition: attachment; filename="cloak-flow-12.php"

<?php /* generated cloaker — calls /api/v1/check ... */

Upload the file to your cloaked domain. No manual key wiring needed — it already carries the flow's key. Returns 409 if the flow has no API key.

GET/api/v1/keys

List your API keys. Authenticated with a Bearer JWT.

Response — 200

{
  "keys": [
    {
      "id": 3,
      "label": "production",
      "key": "ck_live_8f2a...c91",
      "is_active": 1,
      "created_at": "2026-04-28 10:00:00",
      "last_used_at": "2026-05-31 08:14:55"
    }
  ]
}

POST/api/v1/keys

Create a new API key. A fresh key string is generated server-side and returned once. Authenticated with a Bearer JWT.

Request — body

{ "label": "tiktok-flow" }

Response — 200

{
  "id": 7,
  "label": "tiktok-flow",
  "key": "ck_live_3b91...7de"
}

DELETE/api/v1/keys/:id

Revoke a key. Any flow or PHP file still using it stops working. Authenticated with a Bearer JWT.

Response — 200

{ "ok": true }

Returns 404 if the key does not exist or is not yours.

GET/api/v1/stats/summary

Aggregate decision stats across all your keys: lifetime + today totals, a 7-day verdict breakdown, top countries, and a daily timeline. Authenticated with a Bearer JWT.

Request — headers

Authorization: Bearer <jwt>

Response — 200

{
  "total": 18422,
  "today": 312,
  "verdicts": { "allow": 240, "block": 58, "flag": 14 },
  "countries": [
    { "country": "US", "c": 121 },
    { "country": "GB", "c": 44 }
  ],
  "timeline": [
    { "d": "2026-05-31", "allows": 240, "flags": 14, "chals": 0, "blocks": 58 }
  ]
}

Related endpoints not detailed here: GET /api/v1/stats/events (recent raw decisions), GET /api/v1/flows/:id/stats (per-flow window stats), and the flow POST/PATCH/DELETE CRUD on /api/v1/flows/:id. All use the same Bearer JWT auth.