Partner API

Quick start

Create a token and send it in the Authorization header. For POST requests, use JSON and Content-Type: application/json.

API URLhttps://proxycola.com/api/v1/

Rate limit300/min

First request · verify your token

curl "https://proxycola.com/api/v1/account/" \
  -H "Authorization: Bearer <TOKEN>"

Download OpenAPI Import all methods into Postman.

Account & catalog

GET /api/v1/account/ Account & limits

Verify your token and get the account ID, email and request limit per minute.

Request · curl

curl "https://proxycola.com/api/v1/account/" \
  -H "Authorization: Bearer <TOKEN>"

Response · JSON

{
    "success": true,
    "data": {
        "user": {
            "id": 42,
            "email": "you@example.com"
        },
        "api_key": {
            "id": 1,
            "name": "Partner API",
            "rate_limit_per_minute": 300
        }
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

GET /api/v1/balance/ Balance in USD

Check your USD balance before buying or renewing.

Request · curl

curl "https://proxycola.com/api/v1/balance/" \
  -H "Authorization: Bearer <TOKEN>"

Response · JSON

{
    "success": true,
    "data": {
        "balance": 100,
        "currency": "usd",
        "balance_text": "$100.00"
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

GET /api/v1/catalog/ Countries & plans

Get countries, operators and plans. Use their codes and amount values when buying.

Choose a country with is_available=true and an operator with is_sellable=true. plans contains prices by number of days, e.g. plans["30"].

Request · curl

curl "https://proxycola.com/api/v1/catalog/" \
  -H "Authorization: Bearer <TOKEN>"

Response · JSON

{
    "success": true,
    "data": {
        "countries": [
            {
                "id": 1,
                "code": "ua",
                "name": "Ukraine",
                "operators": [
                    {
                        "id": 1,
                        "code": "kyivstar",
                        "name": "Kyivstar",
                        "is_active": 1,
                        "availables": 10,
                        "is_sellable": true
                    }
                ],
                "plans": {
                    "30": {
                        "id": 1,
                        "amount": 30,
                        "price": "10.00",
                        "old_price": null,
                        "currency": "usd",
                        "is_active": 1,
                        "sort": 30
                    }
                },
                "is_available": true
            }
        ]
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

Buy & renew

POST /api/v1/proxies/quote/ Check the price

Calculate the purchase or renewal price before paying. No money is charged.

Parameters JSON

Parameter	Type	Required	What to send
`plan_type`	`"time"`	For purchase	Plan type from the catalog.
`amount`	`integer`	Yes	Number of days from the catalog.
`country_code`	`string`	For purchase	Country code from countries[].code.
`operator_code`	`string`	For purchase	Available operator code for the selected country from operators[].code.
`quantity`	`integer`	No	1–10. Defaults to 1.
`max_total`	`string`	No	Maximum total in USD, e.g. "20.00". A higher price is rejected without charging.
`proxy_id`	`integer`	For renewal	For a renewal quote, instead of purchase parameters.

For renewal, send only proxy_id, amount and optionally max_total. A quote does not reserve price or availability.

Request · curl

curl -X POST "https://proxycola.com/api/v1/proxies/quote/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_type": "time",
    "amount": 30,
    "country_code": "ua",
    "operator_code": "kyivstar",
    "max_total": "10.00"
}'

Response · JSON

{
    "success": true,
    "data": {
        "plan_type": "time",
        "plan_id": 1,
        "amount": 30,
        "unit": "days",
        "quantity": 1,
        "country_id": 1,
        "country_code": "ua",
        "operator_id": 1,
        "operator_code": "kyivstar",
        "unit_price": "10.00",
        "total": "10.00",
        "currency": "usd"
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

POST /api/v1/proxies/buy/ Buy proxies

Buy 1–10 proxies from your balance in one request. If the purchase fails, none are charged or created.

Parameters JSON

Parameter	Type	Required	What to send
`plan_type`	`"time"`	Yes	Plan type from the catalog.
`amount`	`integer`	Yes	Number of days from the catalog.
`country_code`	`string`	Yes	Country code from countries[].code.
`operator_code`	`string`	Yes	Available operator code for the selected country from operators[].code.
`quantity`	`integer`	No	1–10. Defaults to 1.
`max_total`	`string`	No	Maximum total in USD, e.g. "20.00". A higher price is rejected without charging.

Use the returned proxy_ids in GET /proxies/?ids=… for connection details. HTTP 201 means purchased; 200 with replayed=true returns an earlier result. Activation may take a short time.

Required header Idempotency-Key: 8–128 letters, digits or . _ : -. Use a new key for each new operation. After a timeout, retry the same request and key to avoid a second charge.

Request · curl

curl -X POST "https://proxycola.com/api/v1/proxies/buy/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Idempotency-Key: <UNIQUE_OPERATION_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_type": "time",
    "amount": 30,
    "country_code": "ua",
    "operator_code": "kyivstar",
    "max_total": "10.00"
}'

Response · JSON

{
    "success": true,
    "data": {
        "operation_id": 42,
        "proxy_ids": [
            1702
        ],
        "quote": {
            "plan_type": "time",
            "plan_id": 1,
            "amount": 30,
            "unit": "days",
            "quantity": 1,
            "country_id": 1,
            "country_code": "ua",
            "operator_id": 1,
            "operator_code": "kyivstar",
            "unit_price": "10.00",
            "total": "10.00",
            "currency": "usd"
        },
        "balance_after": "90.00",
        "replayed": false
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

POST /api/v1/proxies/renew/ Renew a proxy

Add days to your proxy. Unused time is kept; an expired term restarts at renewal.

Parameters JSON

Parameter	Type	Required	What to send
`proxy_id`	`integer`	Yes	Your proxy ID from GET /proxies/.
`amount`	`integer`	Yes	Number of days from the catalog.
`max_total`	`string`	No	Maximum total in USD, e.g. "20.00". A higher price is rejected without charging.

Login, password and port stay the same. Blocked or archived proxies cannot be renewed. Success: HTTP 200; replayed=true means no new charge.

Required header Idempotency-Key: 8–128 letters, digits or . _ : -. Use a new key for each new operation. After a timeout, retry the same request and key to avoid a second charge.

Request · curl

curl -X POST "https://proxycola.com/api/v1/proxies/renew/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Idempotency-Key: <UNIQUE_OPERATION_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702,
    "amount": 30,
    "max_total": "10.00"
}'

Response · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "quote": {
            "proxy_id": 1702,
            "plan_type": "time",
            "plan_id": 1,
            "amount": 30,
            "unit": "days",
            "quantity": 1,
            "unit_price": "10.00",
            "total": "10.00",
            "currency": "usd"
        },
        "expires_at": "2026-11-25 12:00:00",
        "traffic_left": 0,
        "operation_id": 43,
        "balance_after": "80.00",
        "replayed": false
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

Manage proxies

GET /api/v1/proxies/ Proxies & credentials

List proxies with credentials, connection URLs and settings. Find specific proxies by ID, port or status.

Parameters query

Parameter	Type	Required	What to send
`ids`	`string`	No	1–100 IDs separated by commas, e.g. 1702,1703.
`port`	`integer`	No	Proxy port: 1–65535.
`status`	`string`	No	all, active or expired (inactive). Defaults to all.
`limit`	`integer`	No	Page size: 1–500. Defaults to 100.
`offset`	`integer`	No	Number of results to skip. Defaults to 0.

Filters apply together. pagination.total counts matches before pagination. Archived proxies are excluded. traffic_left is in bytes; dates are UTC.

Request · curl

curl "https://proxycola.com/api/v1/proxies/?ids=1702,1703" \
  -H "Authorization: Bearer <TOKEN>"

Response · JSON

{
    "success": true,
    "data": {
        "items": [
            {
                "id": 1702,
                "host": "tproxy.pro",
                "port": 20000,
                "login": "example_user",
                "password": "<PROXY_PASSWORD>",
                "http_url": "http://example_user:<PROXY_PASSWORD>@tproxy.pro:20000",
                "socks5_url": "socks5://example_user:<PROXY_PASSWORD>@tproxy.pro:20000",
                "udp_supported": false,
                "plan_type": "time",
                "status": 1,
                "is_active": true,
                "expires_at": "2026-10-25 12:00:00",
                "traffic_left": 0,
                "country": {
                    "id": 1,
                    "code": "ua",
                    "name": "Ukraine"
                },
                "operator": {
                    "id": 1,
                    "code": "kyivstar",
                    "name": "Kyivstar"
                },
                "auto_renew": false,
                "ip_change_interval": 0,
                "ip_bindings": []
            }
        ],
        "pagination": {
            "limit": 100,
            "offset": 0,
            "total": 1
        }
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

POST /api/v1/proxies/settings/ Proxy settings

Change the IP rotation timer, auto-renewal, password or allowed IPs. Only supplied settings change.

Parameters JSON

Parameter	Type	Required	What to send
`proxy_id`	`integer`	Yes	Your proxy ID from GET /proxies/.
`auto_renew`	`boolean`	No	true to enable, false to disable. Only paid proxies can enable it.
`ip_change_interval`	`integer`	No	IP rotation interval in minutes: 0–1440. 0 disables the timer.
`password`	`string`	No	New password: 12–64 printable ASCII characters, no spaces.
`ip_bindings`	`string[]`	No	Up to 10 allowed IPv4 addresses. [] removes the IP restriction.

Active proxies only. Send at least one setting. Errors leave all settings unchanged; identical retries are safe. Changes may take a short time to apply.

Request · curl

curl -X POST "https://proxycola.com/api/v1/proxies/settings/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702,
    "auto_renew": true,
    "ip_change_interval": 10,
    "ip_bindings": [
        "192.0.2.10"
    ]
}'

Response · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "changed": true,
        "settings": {
            "auto_renew": true,
            "ip_change_interval": 10,
            "ip_bindings": [
                "192.0.2.10"
            ]
        }
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

POST /api/v1/proxies/set-location/ Change location

Switch an active proxy to another country and operator from the catalog.

Parameters JSON

Parameter	Type	Required	What to send
`proxy_id`	`integer`	Yes	Your proxy ID from GET /proxies/.
`country_code`	`string`	Yes	Country code from countries[].code.
`operator_code`	`string`	Yes	Available operator code for the selected country from operators[].code.

Country changes: once per 10 minutes; operator changes: once per 5 minutes. Changing country adjusts remaining paid time to the new country’s price.

Request · curl

curl -X POST "https://proxycola.com/api/v1/proxies/set-location/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702,
    "country_code": "ua",
    "operator_code": "kyivstar"
}'

Response · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "country_code": "ua",
        "operator_code": "kyivstar"
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

POST /api/v1/proxies/set-operator/ Change operator

Change the operator while keeping the proxy’s country. Get the operator code from the catalog.

Parameters JSON

Parameter	Type	Required	What to send
`proxy_id`	`integer`	Yes	Your proxy ID from GET /proxies/.
`operator_code`	`string`	Yes	Available operator code for the selected country from operators[].code.

Change operators once per 5 minutes. A cooldown response includes data.retry_after in seconds.

Request · curl

curl -X POST "https://proxycola.com/api/v1/proxies/set-operator/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702,
    "operator_code": "kyivstar"
}'

Response · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "country_code": "ua",
        "operator_code": "kyivstar"
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

POST /api/v1/proxies/change-ip/ Rotate IP

Request a new exit IP for an active proxy. After rotation, use check-ip to verify the address.

Parameters JSON

Parameter	Type	Required	What to send
`proxy_id`	`integer`	Yes	Your proxy ID from GET /proxies/.

Request · curl

curl -X POST "https://proxycola.com/api/v1/proxies/change-ip/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702
}'

Response · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "hub_response": {}
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

POST /api/v1/proxies/check-ip/ Check current IP

Get an active proxy’s current exit IP. This checks the connection without rotating the IP.

Parameters JSON

Parameter	Type	Required	What to send
`proxy_id`	`integer`	Yes	Your proxy ID from GET /proxies/.

Request · curl

curl -X POST "https://proxycola.com/api/v1/proxies/check-ip/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": 1702
}'

Response · JSON

{
    "success": true,
    "data": {
        "proxy_id": 1702,
        "current_ip": "203.0.113.10"
    },
    "request_id": "..."
}

Response example is shortened. IDs, prices and credentials are illustrative.

Errors & retries

On success, read data. On failure, read error and message. Keep request_id when contacting support.

401: Check your token and the Authorization: Bearer <TOKEN> header.
402: Insufficient balance. Add funds; data.needed shows the missing amount.
404: Proxy not found. Check proxy_id in your proxy list.
409: Check error: price exceeds max_total, the key was used with different parameters, or the action is unavailable for this proxy.
429: Too many requests. If Retry-After or data.retry_after is present, wait that many seconds; otherwise increase the delay between requests.
500: Temporary error. Retry later; use the same Idempotency-Key for purchase and renewal retries.

Error example

{
    "success": false,
    "error": "insufficient_balance",
    "message": "Insufficient balance",
    "data": {
        "needed": "5.00"
    },
    "request_id": "..."
}