Logo

v-proxies

V-PROXIES / DOCS · BUILD 0.1.0

API reference.

Proxy gateway auth, geo targeting, REST management endpoints, error codes, and SDK examples.

Base URL: https://v-proxies.com/api/v1Status

01 // QUICK START

Start routing traffic through v-proxies in under a minute. Grab your proxy credentials from the Credentials page, and your API key from API keys.

bash
# Route any HTTP/HTTPS request through the gateway
curl -x proxy.v-proxies.com:9000 \
  -U "u_a91c2f:p_xk9m2r4n8q1vw3" \
  https://httpbin.org/ip

# Response
{ "origin": "82.15.67.33" }

~/01

Get credentials

Find your proxy username and password on the credentials page.

~/02

Get API key

Generate a secret key on the API keys page for REST access.

~/03

Start routing

Traffic proxies immediately. Usage updates in real time.

02 // AUTHENTICATION

There are two separate credential types — keep them distinct.

::rest api

Bearer token

Pass your API key as a Bearer token on every REST request. Generate it from the API keys page.

Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

::proxy gateway

HTTP Basic Auth

Proxy gateway traffic uses your proxy username + password — separate from the API key. Get them from Credentials.

u_a91c2f:p_xk9m2r4n8q1vw3
bash
# REST API — pass your API key as a Bearer token
curl https://v-proxies.com/api/v1/me \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

API key format

Keys are standard UUIDs — e.g. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Generate or rotate yours from the API keys page.

03 // PROXY GATEWAY

The proxy gateway speaks HTTP CONNECT and plain HTTP proxy protocols. Use it with any HTTP client that supports proxy settings. The port determines whether you get a rotating or sticky IP — see Session modes.

HOST

proxy.v-proxies.com

PORT (ROTATING)

9000

PORT (STICKY)

10000

PROTOCOL

HTTP / HTTPS

Proxy list format

proxy.v-proxies.com:9000:username:password
bash
# HTTPS via CONNECT tunnel
curl -x https://proxy.v-proxies.com:9000 \
  -U "u_a91c2f:p_xk9m2r4n8q1vw3" \
  https://target.example.com/api

# Plain HTTP
curl -x http://proxy.v-proxies.com:9000 \
  -U "u_a91c2f:p_xk9m2r4n8q1vw3" \
  http://target.example.com/page

04 // SESSION MODES

Choose between a new IP per request (rotating) or pinning the same IP for a set duration (sticky). Session mode is selected by port, and sticky sessions encode a lifetime + session id in the proxy username.

::rotating · port 9000

New IP per request

Default mode. Highest anonymity. No lifetime/session suffix.

u_a91c2f-type-residential:p_xk9m2r4n8q1vw3

::sticky · port 10000

Same IP for N minutes

Pin a session for 1–60 minutes or 1–24 hours. Lifetime is encoded in minutes.

u_a91c2f-type-residential-lifetime-30-session-abc12:p_…

Username format

The username is built by joining your base username and key/value pairs with hyphens. The first pair is always type-residential. Sticky mode appends lifetime-{minutes} and session-{id} at the end.

bash
# Rotating — port 9000, no lifetime/session
curl -x proxy.v-proxies.com:9000 \
  -U "u_a91c2f-type-residential:p_xk9m2r4n8q1vw3" \
  https://httpbin.org/ip

# Sticky 30-minute session — port 10000, lifetime in minutes
SESSION=$(openssl rand -hex 3 | cut -c1-5)
curl -x proxy.v-proxies.com:10000 \
  -U "u_a91c2f-type-residential-lifetime-30-session-${SESSION}:p_xk9m2r4n8q1vw3" \
  https://httpbin.org/ip

Sticky limits

  • · Minutes: 1–60 (e.g. lifetime-1 to lifetime-60)
  • · Hours: 1–24 (e.g. lifetime-60 to lifetime-1440)
  • · Use POST /v1/connection to have the API build the username for you.

05 // GEO TARGETING

Target by country, state, city, or ASN by appending key/value pairs to the proxy username (separated by hyphens). City requires state. Looking up valid codes? See GET /v1/getTargeting.

Targeting keys

country-{code}country-US

ISO 3166-1 alpha-2 country code (uppercase)

state-{code}state-CA

State/region code. Requires country.

city-{code}city-los_angeles

City slug (lowercase). Requires country + state.

asn-{code}asn-16509

Autonomous System Number. Requires country.

bash
# Country only
-U "u_a91c2f-type-residential-country-US:p_xk9m2r4n8q1vw3"

# Country + state + city
-U "u_a91c2f-type-residential-country-US-state-CA-city-los_angeles:p_xk9m2r4n8q1vw3"

# Country + ASN (AWS us-east-1)
-U "u_a91c2f-type-residential-country-US-asn-16509:p_xk9m2r4n8q1vw3"

# Country + city + sticky 15 min (port 10000)
-U "u_a91c2f-type-residential-country-GB-state-ENG-city-london-lifetime-15-session-xyz12:p_xk9m2r4n8q1vw3"

06 // GENERATE ENDPOINTS

POST /v1/connection

Generate a batch of ready-to-use proxy endpoints with session, geo targeting, and output format already applied. Useful for bulk imports into bots, scrapers, or proxy managers.

Request body

amount
integer

Number of endpoints to generate. 1–10000. Defaults to 1.

format
string

One of: "host:port:user:pass" (default), "user:pass@host:port", "host:port".

session.type
string

"rotating" (default) or "sticky".

session.duration
integer

Sticky only. Pin duration. 1–60 with unit=min, 1–24 with unit=hr.

session.unit
string

Sticky only. "min" (default) or "hr".

targeting.country
object

Optional. { "code": "US" }.

targeting.state
object

Optional. { "code": "CA" } or { "name": "California" }. Requires country.

targeting.city
object

Optional. { "code": "los_angeles" } or { "name": "Los Angeles" }. Requires country + state.

targeting.isp
object

Optional. { "asn": "16509" } or { "code": "16509" }. Requires country.

bash
curl -X POST https://v-proxies.com/api/v1/connection \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5,
    "format": "host:port:user:pass",
    "session": { "type": "sticky", "duration": 30, "unit": "min" },
    "targeting": {
      "country": { "code": "US" },
      "state":   { "code": "CA" },
      "city":    { "code": "los_angeles" }
    }
  }'

# 200 OK
{
  "host": "proxy.v-proxies.com",
  "port": 10000,
  "format": "host:port:user:pass",
  "session": { "type": "sticky", "duration": 30, "unit": "min" },
  "targeting": { "country": "US", "state": "CA", "city": "los_angeles" },
  "amount": 5,
  "endpoints": [
    "proxy.v-proxies.com:10000:u_a91c2f-type-residential-country-US-state-CA-city-los_angeles-lifetime-30-session-abc12:p_xk9m2r4n8q1vw3",
    "proxy.v-proxies.com:10000:u_a91c2f-type-residential-country-US-state-CA-city-los_angeles-lifetime-30-session-d3f4k:p_xk9m2r4n8q1vw3",
    "..."
  ]
}

Rotating example

Omit session (or send { "type": "rotating" }) to receive rotating endpoints on port 9000. Each request through them gets a new IP.

07 // REST API

All endpoints live under https://v-proxies.com/api/v1. Responses are JSON. Authenticate every request with your API key — see Authentication.

POST/v1/connection

Generate ready-to-use proxy endpoints with session + geo targeting

GET/v1/me

Account info — id, email, plan, credits, created_at

GET/v1/credentials

Proxy host, port, username, and password

PATCH/v1/credentials/rotate

Rotate the proxy password (username is never changed)

GET/v1/getTargeting

List supported countries, states, cities, and ISPs

GET/v1/usage

Bandwidth usage — ?range=7d|30d|90d

GET/v1/sub-accounts

List sub-accounts, your cap, and main balance free

POST/v1/sub-accounts

Create a sub-account with a GB allocation from your balance

PATCH/v1/sub-accounts/{id}

Re-allocate a sub-account to a new GB total

DELETE/v1/sub-accounts/{id}

Delete a sub-account; unused GB returns to your balance

GET /v1/me

Returns the authenticated account's info.

bash
curl https://v-proxies.com/api/v1/me \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 200 OK
{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "email": "ops@example.com",
  "plan": "residential",
  "credits": 184.20,
  "created_at": "2024-09-01T00:00:00Z"
}

GET /v1/credentials

Returns your proxy host, port, username, and password.

bash
curl https://v-proxies.com/api/v1/credentials \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 200 OK
{
  "host": "proxy.v-proxies.com",
  "port": 9000,
  "username": "u_a91c2f",
  "password": "p_xk9m2r4n8q1vw3"
}

PATCH /v1/credentials/rotate

Rotates the proxy password. The username is never changed. The new password takes effect immediately — your next /v1/credentials call will return it.

bash
curl -X PATCH https://v-proxies.com/api/v1/credentials/rotate \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 200 OK
{
  "host": "proxy.v-proxies.com",
  "port": 9000,
  "username": "u_a91c2f",
  "password": "p_newpasswordhere",
  "rotated_at": "2025-05-19T12:00:00.000Z"
}

GET /v1/getTargeting

Lists supported countries, or drills into a country to fetch its states, cities, or ASNs. Use this to populate dropdowns or validate user input before calling /v1/connection.

Query parameters

level
string

One of: "country" (default), "state", "city", "isp".

country
string

ISO country code. Required when level is "state", "city", or "isp".

state
string

State code. Required when level is "city".

bash
# List all countries
curl "https://v-proxies.com/api/v1/getTargeting?level=country" \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 200 OK
{
  "level": "country",
  "data": [
    { "code": "US", "name": "United States", "flag": "🇺🇸" },
    { "code": "GB", "name": "United Kingdom", "flag": "🇬🇧" }
  ]
}

# List states for a country
curl "https://v-proxies.com/api/v1/getTargeting?level=state&country=us" \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# List cities for a state
curl "https://v-proxies.com/api/v1/getTargeting?level=city&country=us&state=ca" \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# List ASNs for a country
curl "https://v-proxies.com/api/v1/getTargeting?level=isp&country=us" \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

GET /v1/usage

Returns daily bandwidth usage for the authenticated account over the requested window.

Query parameters

range
string

Time window. One of: 7d · 30d · 90d. Defaults to 30d.

bash
curl "https://v-proxies.com/api/v1/usage?range=7d" \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 200 OK
{
  "range": "7d",
  "data": [ … ]
}

Sub-accounts

Create sub-accounts with their own proxy credentials and a fixed GB budget. The GB assigned to a sub-account is moved out of your main balance — increasing an allocation pulls from your balance, decreasing or deleting returns the unused GB. Each account is capped (default 10 sub-accounts); contact support to raise it.

GET /v1/sub-accounts

bash
curl "https://v-proxies.com/api/v1/sub-accounts" \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 200 OK
{
  "limit": 10,
  "count": 1,
  "mainAvailableGb": 42.5,
  "subAccounts": [
    {
      "id": "8f3c…",
      "label": "scraper-eu",
      "username": "ab12cd34ef56",
      "password": "9z8y7x6w",
      "allocatedGb": 5,
      "limitGb": 5,
      "usedGb": 1.27,
      "createdAt": "2026-06-17T18:00:00.000Z"
    }
  ]
}

POST /v1/sub-accounts

Body parameters

gb
integer

Whole GB to allocate from your main balance. Minimum 1.

label
string

Optional name to identify the sub-account. Up to 60 characters.

bash
curl -X POST "https://v-proxies.com/api/v1/sub-accounts" \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "label": "scraper-eu", "gb": 5 }'

# 201 Created
{
  "id": "8f3c…",
  "label": "scraper-eu",
  "username": "ab12cd34ef56",
  "password": "9z8y7x6w",
  "allocatedGb": 5,
  "limitGb": 5,
  "usedGb": 0,
  "createdAt": "2026-06-17T18:00:00.000Z"
}

PATCH /v1/sub-accounts/{id}

Body parameters

gb
integer

New total GB for the sub-account. Cannot be lower than the GB already used.

bash
curl -X PATCH "https://v-proxies.com/api/v1/sub-accounts/8f3c…" \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "gb": 10 }'

# 200 OK
{ "id": "8f3c…", "allocatedGb": 10, "limitGb": 10, "usedGb": 1.27 }

DELETE /v1/sub-accounts/{id}

Deletes the sub-account and returns its unused GB to your main balance. GB already consumed is not refunded.

bash
curl -X DELETE "https://v-proxies.com/api/v1/sub-accounts/8f3c…" \
  -H "Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 200 OK
{ "ok": true }

08 // ERROR CODES

Every error response uses the same JSON envelope. Parse error.code for programmatic handling and error.message for the human-readable reason.

json
// Error envelope — every non-2xx response
{
  "error": {
    "code": "unauthorized",                   // machine-readable slug
    "message": "Invalid or revoked API key",  // human-readable
    "status": 401                             // mirrors the HTTP status
  }
}
400Bad request

A request parameter is missing or invalid (e.g. malformed JSON body, unknown level on /v1/getTargeting, sticky duration out of range).

Example response

{ "error": { "code": "invalid_param", "message": "…", "status": 400 } }
401Unauthorized

Authorization header is missing, malformed, or the API key is not recognized.

Example response

{ "error": { "code": "unauthorized", "message": "Invalid or revoked API key", "status": 401 } }
404Not found

The authenticated user has no record in userInfo, or the targeted country / state / city / ASN does not exist.

Example response

{ "error": { "code": "not_found", "message": "…", "status": 404 } }
500Server error

An unexpected internal error occurred while processing your request.

Example response

{ "error": { "code": "fetch_failed", "message": "…", "status": 500 } }
502Bad gateway

The upstream proxy API returned an error or was unreachable.

Example response

{ "error": { "code": "upstream_error", "message": "Upstream 502", "status": 502 } }

Proxy gateway errors

These are returned by the proxy gateway itself, not the REST API — they appear as HTTP status codes on the proxied connection.

407Proxy auth required

Proxy credentials rejected at the gateway. Check username and password.

403Forbidden

Account balance is $0, or the target is blocked.

503Unavailable

Gateway under maintenance. Check the status page.

09 // SDKS

Use any HTTP client that supports proxy authentication. Copy-paste examples for the most common environments.

bash
curl -x proxy.v-proxies.com:9000 \
  -U "u_a91c2f:p_xk9m2r4n8q1vw3" \
  https://httpbin.org/ip

::ready

Start routing traffic

Top-up from $10. Credentials provisioned in under 2 seconds.

Top upGet credentials