Code samples

Every request authenticates the same way: HTTP Basic auth over a plain HTTP proxy — username selects routing, password is your token. Sign in to fill these in with your real token instead of a placeholder.

Try it

Pick a profile, country, and session below — every snippet updates live.

Profile

Country

Sticky session

A different healthy proxy on every request. No stickiness.

Example URL

http://random:[email protected]:8080

curl -x "http://random:[email protected]:8080" https://ifconfig.me

Username random encodes the profile, country filter, and session — the password is always your token below.

Profiles

What each routing profile does.

Random: A different healthy proxy on every request. No stickiness.
Stable: Rotates among the best-known proxies. Add a session ID to pin one exit IP consistently.
Fastest: Rotates among the lowest-latency healthy proxies. Add a session ID to pin one exit IP.
Fresh: Prefers proxies that haven't been used recently, to spread load evenly.

Country targeting & sticky sessions

Add a country to the username to only route through proxies in that country, e.g. random-DE. Leave it out (or use ANY) for no filter.

Add a session ID (1–5) to keep reusing the same exit IP across multiple requests — useful for anything that needs a consistent identity, like a multi-step checkout or a logged-in session, e.g. stable-DE-3. Different session IDs get independent sticky proxies; without one, every request rotates.

HTTP API

Same credential, different door: Authorization: Bearer <your token> — the proxy password is the API token.

`GET /api/token`	Checks the token and returns what it can do: profiles, session bounds, sticky TTL, and the proxy endpoint. The cheapest way to validate a token.
`GET /api/sessions`	Each session slot: whether it is pinned, to which exit IP and country, and how long before it expires unused.
`POST /api/sessions/drop`	Expires one sticky session so the next request through it picks a new exit. Body: {"session": 1}. Reports the IP it let go.
`GET /api/countries`	Country codes with live exit counts. The only honest answer to what you can route through right now.
`GET /api/usage`	Bytes used this period, the cap being enforced, period end, and daily history. Add ?days=30 for a longer window.
`GET /api/whoami`	Echoes the IP this request came from — your own address, not your exit. Unauthenticated.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://rcloak.com/api/sessions

Which exit am I on?

Ask the proxy, through the proxy — it answers from its own records, so there is no third-party echo service in the loop and no bandwidth spent finding out. pinned: true means a sticky session is holding that exit; false means it is what selection would hand you right now.

curl -x "http://stable-DE-1:[email protected]:8080" \
  http://exit.rcloak.internal/
# {"ip":"203.0.113.42","country":"DE","profile":"stable","session":1,"pinned":true}

For a sticky session you can also read every slot at once, with no proxy traffic at all, from GET /api/sessions.

Errors answer JSON with a stable code next to the human-readable error, so branch on the code. Reads are limited per token per minute and answer 429 with Retry-After when you go over.

When a request fails

The proxy tags every error it generates itself with X-Rcloak-Error. Read it instead of guessing from the status code.

`invalid_token`	407	The password is not a live token.
`invalid_profile / invalid_country / invalid_session`	407	The username cannot be routed. Fix the username, not the retry logic.
`quota_exceeded`	402	This billing period's bandwidth is spent.
`no_exits_in_country`	503	Valid country, nothing available right now — pick another, or drop the filter.
`no_exits`	503	No exits available at all. Retry shortly.
`upstream_failed`	502	Every exit tried failed. Retry.
`port_not_allowed`	403	Only ports 80 and 443 are relayed.