Management API

Everything the dashboard does, the API does. One key, one header, the same endpoints the panel itself calls. Use it to create credentials from a deploy script, poll usage before a big job, or pull settlement records into your own billing.

This is the management API — it manages your account. It is not the proxy itself; traffic still goes through the gateway as described in Getting started.

Authentication

Create a key under API keys. The full value is shown once — store it like a password. Send it in the X-API-KEY header:

curl -H "X-API-KEY: $KEY" "https://oneforproxy.com/api/v1/usage/summary"

Never put the key in a URL or query string: URLs end up in browser history, proxy logs and error reports. A key has full account access (there are no scopes yet), so it can create credentials and spend your balance — revoke any key you no longer use, and use a separate key per machine so a single leak is cheap to contain.

Browser sessions and API keys are separate paths to the same endpoints: the panel authenticates with a cookie plus a CSRF token, an API key needs neither. Requests you make from the panel do not count against the API rate limit.

What you can call

Admin endpoints are never exposed to API keys, and they are not in the public schema.

Examples

Create a credential:

curl -X POST "https://oneforproxy.com/api/v1/proxies" \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{"label": "scraper-01"}'

{ "id": 12, "login": "ofp_0123abcd", "password": "…", "label": "scraper-01", "active": true }

The password is returned once, on creation — exactly like the API key itself. Rotate it from the panel if you lose it.

Check what is left before starting a job:

curl -H "X-API-KEY: $KEY" "https://oneforproxy.com/api/v1/usage/summary"

{ "quota_bytes_remaining": 5368709120,
  "plan_bytes_remaining": 45097156608,
  "plan_period_end": "2026-10-16T10:00:00Z",
  "price_per_gb": 3.0 }

Pull settlement records as CSV (UTF-8 with BOM, opens straight in Excel or Sheets):

curl -H "X-API-KEY: $KEY" -o usage.csv \
  "https://oneforproxy.com/api/v1/usage/records.csv?since=2026-09-01T00:00:00Z&until=2026-09-16T00:00:00Z"

CSV endpoints are limited to 5 downloads per minute and 50,000 rows; a truncated export sets the X-Truncated: 1 response header, so narrow the date range when you see it. since/until are ISO-8601 UTC, default to the last 30 days, and cannot span more than 366 days.

Python

import requests

API = "https://oneforproxy.com/api/v1"
session = requests.Session()
session.headers["X-API-KEY"] = KEY

# 1. how much traffic is left?
summary = session.get(f"{API}/usage/summary", timeout=30).json()
free_bytes = summary["plan_bytes_remaining"] + summary["quota_bytes_remaining"]
print(f"{free_bytes / 1024**3:.2f} GB before pay-as-you-go billing starts")

# 2. a credential for this run
cred = session.post(f"{API}/proxies", json={"label": "nightly-run"}, timeout=30).json()
proxy = f"http://{cred['login']}-country-de:{cred['password']}@proxy.oneforproxy.com:8080"

# 3. use it
ip = requests.get("https://api.ipify.org", proxies={"http": proxy, "https": proxy}, timeout=30).text
print("exit ip:", ip)

Handle 429 by honouring the Retry-After header (always 60 seconds) rather than retrying immediately — a tight retry loop just burns the next minute's budget too.

Error codes

A 5xx is ours, not yours — retry with backoff and, if it persists, open a ticket from Support.

Deprecated: GET /balance

The old root-level GET /balance still works for existing integrations, but new code should use GET /api/v1/wallet/balance, which returns the same balance plus the plan and package allowance in one call.