Loading…
Developers
Read your endpoints, orders and balance programmatically. Authentication is a single scoped key, responses are stable JSON, and error codes are documented rather than discovered.
Quick start
Keys are created in the dashboard and shown exactly once. Store them in your secret manager, never in client-side code.
Dashboard → API keys → Create. Choose read, write and billing scopes independently, name the key after the integration that will use it, and revoke it the moment it is no longer needed.
Send the key in the X-API-Key request header. Keys are stored only as SHA-256 hashes on our side, so a database leak cannot be replayed against the API.
Limits are 120 requests per minute per key. On 429, read the Retry-After header and back off — do not retry in a tight loop.
Base URL
/api/v1
Auth header
X-API-Key
curl -s "https://your-domain/api/v1/proxies?country=DE&status=ACTIVE" \
-H "X-API-Key: pn_live_4f9a2c_8d1e4b7a3c5f6e92"const res = await fetch(
"https://your-domain/api/v1/proxies?country=DE&status=ACTIVE",
{ headers: { "X-API-Key": process.env.PROXYNOVA_KEY } }
);
if (!res.ok) throw new Error(`API error ${res.status}`);
const { data, pagination } = await res.json();
for (const proxy of data) {
console.log(proxy.host, proxy.port, proxy.expiresAt);
}{
"data": [
{
"id": "clx8f2k4m0001abcd",
"host": "203.0.113.14",
"port": 8443,
"username": "pn4f9a2c",
"password": "8d1e4b7a",
"protocol": "HTTPS",
"ipVersion": "IPv4",
"country": "DE",
"city": "Frankfurt",
"status": "ACTIVE",
"autoRenew": true,
"expiresAt": "2026-02-14T09:12:00.000Z"
}
],
"pagination": { "page": 1, "pageSize": 50, "total": 3, "totalPages": 1 }
}Reference
Every endpoint returns JSON. Field names are stable; new optional fields may be added without a version bump.
/api/v1/proxiesreadList your endpoints. Supports filtering by status, country and protocol, plus pagination.
| Parameter | Values |
|---|---|
| status | ACTIVE · EXPIRING · EXPIRED · SUSPENDED · RELEASED |
| country | Two-letter country code, e.g. DE |
| protocol | HTTP · HTTPS · SOCKS5 |
| page | Page number, 1-based (default 1) |
| pageSize | 1–100 (default 50) |
/api/v1/proxies/{id}readRetrieve a single endpoint, including credentials and expiry.
/api/v1/proxies/{id}/checkwriteRun a live reachability probe against the endpoint and return latency. Rate-limited to 60 calls per hour per key.
/api/v1/ordersreadbillingList your orders with status, totals and line items.
| Parameter | Values |
|---|---|
| status | Order status filter |
| page | Page number, 1-based |
| pageSize | 1–100 (default 20) |
/api/v1/accountreadReturn account summary: balance, endpoint counts, open tickets.
Consistent across every endpoint.
| Status | Meaning | What to do |
|---|---|---|
| 200 | Success | Response body contains the requested resource. |
| 400 | Bad request | A parameter is missing or malformed. The `error` field explains which. |
| 401 | Unauthorized | API key missing, malformed or revoked. |
| 403 | Forbidden | The key does not carry the scope required by the endpoint. |
| 404 | Not found | The resource does not exist, or belongs to another account. |
| 429 | Rate limited | Too many requests. Honour the `Retry-After` header. |
| 500 | Server error | Unexpected fault on our side. Safe to retry with backoff. |
Using a proxy
Credentials are ordinary authenticated proxy endpoints, so anything that speaks HTTP or SOCKS5 works.
curl -x "http://pn4f9a2c:8d1e4b7a@203.0.113.14:8443" \
https://api.ipify.orgimport requests
proxies = {
"http": "http://pn4f9a2c:8d1e4b7a@203.0.113.14:8443",
"https": "http://pn4f9a2c:8d1e4b7a@203.0.113.14:8443",
}
print(requests.get("https://api.ipify.org", proxies=proxies, timeout=15).text)const browser = await chromium.launch({
proxy: {
server: "http://203.0.113.14:8443",
username: "pn4f9a2c",
password: "8d1e4b7a",
},
});Good practice
The proxy is only half the problem — how you drive it decides your success rate.
Keep a session on one IP for as long as the target tolerates it, then move on. Constant rotation looks more suspicious than persistence.
Start with datacenter. Escalate to ISP, then residential, then mobile, only for targets that reject the cheaper class.
Retrying a rate-limited request immediately from the same IP is the fastest way to get the whole subnet flagged.
Read expiresAt from the API and rotate before it lapses. Auto-renew removes the problem for long-lived jobs.
One key per integration means you can revoke a single compromised credential without breaking everything else.
Create an account in under a minute and pay only for the endpoints you actually need. Volume discounts apply automatically as your order grows.