man cloaking-x.api-referenceReference

API Reference

The public v1 REST API — list/create/update/delete streams, pull click stats, and manage your blacklist/whitelist from your own code.

Note

Base URL: https://cloakingx.com/api/v1. Every endpoint below also responds to OPTIONS with CORS headers (Access-Control-Allow-Origin: *). Calling GET https://cloakingx.com/api/v1 itself (no API key required) returns a self-describing index of this same surface.

Authentication#

Pass your API key (from your dashboard's Integration page) in the X-API-Key header on every request. Missing or invalid keys get a 401.

bash

curl https://cloakingx.com/api/v1/streams \
  -H "X-API-Key: YOUR_API_KEY"

Access is scoped to your account — an object ID belonging to another account returns 404, never 403, so a caller can't even infer whether a given ID exists on someone else's account.

Rate Limiting#

120 requests per minute, keyed by the API key's owner (not by IP — one customer automating from a single server shares one budget regardless of source IP). Exceeding it returns 429 with a JSON error message.

Error Shape & Status Codes#

Every error response is a JSON object of the shape { "error": "string" }.

401

Missing or invalid X-API-Key.

404

Object not found, OR it exists but belongs to a different account (never 403).

400

Malformed JSON body, an unknown/non-editable field in the body, or a required field missing.

403

A plan limit would be exceeded (stream count or money page count).

409

A blacklist/whitelist entry with the same type + value + listType already exists for your account.

429

Rate limit exceeded.

GETPOST /streams#

List or create streams for your account.

GET query params

limit — default 50, max 200
offset — default 0

POST body

name is the only required field. Unknown fields are rejected with 400, not silently dropped.

trafficSource
moneyPages
safePage
mode
threshold
allowedCountries
allowedOS
allowedDevices
appleMoneyPage
windowsMoneyPage
androidMoneyPage
rotationMode
rotationInterval
moneyAction
requireClickId
isActive

Returns 403 if creating this stream would exceed your plan's stream count, or if the number of money pages exceeds your plan's money-page limit. See Stream Settings Reference for what each field means.

GETPATCHDELETE /streams/:id#

Read, partially update, or delete a single stream you own.

userId, clickCount, blockCount, and createdAt can never be changed via PATCH. Setting moneyPages beyond your plan's limit returns 403.

Mutable fields: name, moneyPages, safePage, mode, threshold, allowedCountries, allowedOS, allowedDevices, rotationMode, rotationInterval, moneyAction, requireClickId, isActive, appleMoneyPage, windowsMoneyPage, androidMoneyPage.

GET /stats#

Click totals (total / passed / blocked) and a breakdown by blockReason — see the Block Reason Reference for what each value means.

streamId — optional, omit for account-wide stats
from — optional ISO date, clamped to your plan's click-history window
to — optional ISO date, treated as inclusive end-of-day

History window by plan: Free 7 days, Starter 30, Pro 90, Agency 180, Enterprise 365 — a wider from is silently clamped to this window rather than erroring.

GETPOST /blacklist#

List or add blacklist/whitelist entries for your account.

GET filters: type (ip / asn / useragent / cidr) and listType (blacklist / whitelist) — both optional. The list also includes global/system entries (read-only parity with your dashboard).

POST body: type (required) and value (required), plus optional listType (default blacklist) and reason. Returns 409 if an identical entry already exists.

DELETE /blacklist/:id#

Removes an entry your account owns. Global/system entries and other accounts' entries both fall through to the same 404 — never mutated by this endpoint even though GET can list them.

Field definitions

For what every stream field actually controls (destination pages, rotation, per-OS overrides, mode, threshold, allow-lists, and Money Page Delivery), see the Stream Settings Reference.