Overview

The Rotating Proxy API gives you programmatic access to rotating residential proxies: discover geo targets, create proxy accesses (sub-users), read your current tariff and traffic balance, pull usage statistics and manage IP authorization.

All business logic, billing and traffic accounting are identical to the platform dashboard — the API is simply another way to drive the same product.

Base URL

All Rotating Proxy API endpoints live under the v2 prefix:

https://app.cyberyozh.com/api/v2/rotating-proxies/

Authentication

The API authenticates with an API key passed in the X-Api-Key header. This is the same key system used across the whole CyberYozh API — no separate credentials are required.

-H 'X-Api-Key: your_api_key_here'

How to get an API key

1. Sign in at https://app.cyberyozh.com.
2. Open the profile menu and go to the API Keys section.
3. Click Generate and copy the key (it is shown once).
4. Send it in the X-Api-Key header on every request.

A request without a valid key returns 403 Forbidden:

{
  "detail": "Invalid API key provided."
}

How rotating proxies work

A rotating proxy connection is made of three parts:

1. Gateway host and ports — fixed entry point of the proxy network. Read them from GET /subscription/ (proxy_host, proxy_port for HTTP, proxy_port_socks5 for SOCKS5).
2. Credentials — the real_login and password of a proxy access (sub-user). Create and read them via /sub-users/.
3. Targeting suffixes — geo, rotation/session and IP-filter parameters are encoded into the username by appending suffixes to real_login. There is no separate "generate proxy string" call; you compose the username yourself, exactly like the dashboard does.

Username grammar

<real_login>[-<country>][-<region>][-<city>][-<zip>][-<isp>][-<session>][-<ttl>][-<filter>]

• Parts are joined with - and prefixed with a leading -.
• Geo suffixes (country, region, city, zip, isp) come from the suffix field of the geo endpoints.
• Session (sticky IP): omit for full rotation; for a sticky IP append s-<id> where <id> is a random 8-character [A-Za-z0-9] string, plus a TTL suffix ttl-5m / ttl-10m / ttl-15m / ttl-30m (or ttl-<minutes>m for a custom duration).
• Filter suffixes (filter-speed, filter-iqs, filter-speed+iqs) come from GET /session-options/.

Example username targeting the country suffix us, a 5-minute sticky session and the quality filter:

u12ab-us-s-Ab3xK9pQ-ttl-5m-filter-iqs

The final connection string is then username:password@proxy_host:proxy_port. See Connecting for complete examples.

Endpoints at a glance

Resource	Method & path	Purpose
Countries	GET /geo/countries/	List available countries
Regions	GET /geo/regions/	List regions of a country
Cities	GET /geo/cities/	List cities of a country
ZIP codes	GET /geo/zips/	List ZIP codes
ISPs	GET /geo/isps/	List ISP providers
Session options	GET /session-options/	Rotation types, session durations, IP filters
Subscription	GET /subscription/	Tariff, traffic balance, connection data
Accesses	GET/POST /sub-users/	List / create proxy accesses
Access	GET/PATCH/DELETE /sub-users/{id}/	Read / update / revoke an access
Statistics	GET /stats/	Traffic usage statistics
Whitelist	GET/PUT /whitelist/	List / replace authorized IPs
Whitelist entry	PATCH/DELETE /whitelist/{id}/	Update / delete an authorized IP

Interactive documentation (Swagger)

Every endpoint is also available in the interactive Swagger UI, where you can authorize with your API key and run requests directly:

https://app.cyberyozh.com/docs/

Open Authorize, paste your key into ApiKeyAuth (X-Api-Key), and use Try it out on any rotating-proxy operation.

Common errors

HTTP	Meaning
400	Invalid request parameters or body
403	Missing or invalid API key
404	No active rotating proxy subscription, or resource not found
409	Login already exists (on access creation)
429	Rate limit exceeded — retry after the indicated delay
502	Upstream proxy gateway temporarily unavailable