Proxybonanza
Home / Articles

API V1 reference

Proxybonanza API v1

Base URL: https://proxybonanza.com/api/v1

The API lets you manage your proxy plans, authentication IPs, proxy IP lists and usage statistics. All requests are scoped to the authenticated account — you can only read and modify your own resources.

  • Format: JSON (application/json). Append .json to the URL, or send Accept: application/json.
  • Alternatives: .csv / .txt (CSV export, see Proxy IP list).
  • HTTP: GET, POST, PUT, PATCH, DELETE as noted per endpoint.

Authentication

Send your full API key in the Authorization header:

Authorization: <full_api_key>

The full API key is a 50-character key plus ! and your user id:

<api_key>!<user_id>

Example: 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN!42

All three of these work (first is recommended):

  • Authorization: <full_api_key>
  • X-Proxybonanza-ApiKey: <full_api_key>
  • HTTP Basic auth with username = full API key (-u '<full_api_key>:')

Browser (CORS) clients must use X-Proxybonanza-ApiKey — browsers only allow that header in cross-origin requests; the Authorization header will not pass through.

Get your API key: in the user panel → Account settings → API Key. The key is shown there; Generate new API key creates a new one.

Response envelope

Successful requests return {"success": true, "data": ...}. What data contains depends on the endpoint:

{
  "success": true,
  "data": []
}

Errors return:

{
  "success": false,
  "data": {
    "message": "Authentication is required to continue",
    "url": "/api/v1/userpackages.json",
    "code": 401
  }
}
  • 401 — missing/invalid API key
  • 403 — not allowed (e.g. action locked)
  • 404 — resource not found or not yours
  • 422 — validation failed; message is "field: reason" (e.g. "ip: The provided value is invalid")

Proxy plans (userpackages)

GET /api/v1/userpackages.json

Lists all active proxy plans (not expired) of your account. Not paginated.

Example

curl https://proxybonanza.com/api/v1/userpackages.json \
  -H "Authorization: $API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": 123456,
      "custom_name": null,
      "login": "login11",
      "password": "secretpass",
      "expires": "2027-09-17T09:59:00+02:00",
      "bandwidth": 4772417328398,
      "last_ip_change": "2026-05-29T14:03:00+02:00",
      "low_banwidth_notification_percent": 25,
      "ipstack": "mixed",
      "ipstackorder": "v4v6",
      "package": {
        "name": "Exclusive Plan",
        "bandwidth": 10737418240,
        "price": { "amount": "10", "currency": "USD" },
        "howmany_ips": 20,
        "price_per_gig": { "amount": "1", "currency": "USD" },
        "package_type": "exclusive",
        "howmany_authips": 10,
        "price_user_formatted": "$10.00"
      },
      "bandwidth_gb": 4772.42,
      "additional_bandwidth_gb": 1,
      "bandwidth_percent_left_human": "6734.04%",
      "expiration_date_human": "334 days",
      "name": "Exclusive Plan"
    }
  ]
}

Fields: id, custom_name, login, password, expires, bandwidth (bytes), last_ip_change, low_banwidth_notification_percent, ipstack, ipstackorder, package (name, bandwidth, price, howmany_ips, price_per_gig, package_type, howmany_authips, price_user_formatted), plus helpers bandwidth_gb, additional_bandwidth_gb, bandwidth_percent_left_human, expiration_date_human, name.

GET /api/v1/userpackages/{id}.json

Details of one plan, including its proxy IPs (ippacks) and auth IPs (authips). 404 if the plan doesn't exist or isn't yours.

Example

curl https://proxybonanza.com/api/v1/userpackages/123456.json \
  -H "Authorization: $API_KEY"

Response

{
  "success": true,
  "data": {
    "id": 123456,
    "login": "login11",
    "password": "secretpass",
    "expires": "2027-06-27T23:59:00+02:00",
    "ippacks": [
      {
        "ip": "203.0.113.10",
        "outgoing_ip": "203.0.113.10",
        "georegion_name": "Warsaw",
        "port_http": 8080,
        "port_socks": 1080,
        "countrycode": "PL",
        "country_name": "Poland"
      }
    ],
    "authips": [
      { "id": 123457, "ip": "198.51.100.20", "userpackage_id": 123456 }
    ],
    "package": { "name": "Exclusive Plan", "bandwidth": 10737418240, "price": { "amount": "10", "currency": "USD" }, "howmany_ips": 20, "price_per_gig": { "amount": "1", "currency": "USD" }, "package_type": "exclusive", "howmany_authips": 10, "price_user_formatted": "$10.00" }
  }
}

PUT|PATCH /api/v1/userpackages/{id}.json

Updates a plan. Returns {"success": true, "data": []}.

Parameters

  • login (string) — plan login
  • password (string) — plan password
  • custom_name (string) — letters/numbers/spaces only, e.g. "My Plan", not "my-plan"
  • authips (array) — replaces the plan's auth IPs: [{"ip": "203.0.113.50", "userpackage_id": 123456, "label": "office"}]

Example

curl -X PUT https://proxybonanza.com/api/v1/userpackages/123456.json \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"custom_name": "My Plan", "login": "newlogin", "password": "newpass"}'

Response

{ "success": true, "data": [] }

Auth IPs (authips)

GET /api/v1/authips.json

Lists all your auth IPs.

Parameters

  • ip (exact) — filter by IP
  • userpackage_id (exact) — filter by plan
  • label (partial match) — filter by label

Example

curl "https://proxybonanza.com/api/v1/authips.json?userpackage_id=123456" \
  -H "Authorization: $API_KEY"

Response

{
  "success": true,
  "data": [
    { "id": 123458, "userpackage_id": 123456, "ip": "198.51.100.20", "label": null }
  ]
}

GET /api/v1/authips/{id}.json

One auth IP. 404 if not yours.

POST /api/v1/authips.json

Adds an auth IP. Returns 201 with the new id.

Parameters

  • ip (required, IPv4) — the auth IP address
  • userpackage_id (required) — must be your plan, not expired, and below the plan's howmany_authips limit
  • label (optional, max 20 chars) — stored slugified (letters, digits and spaces only)

Example

curl -X POST https://proxybonanza.com/api/v1/authips.json \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.50", "userpackage_id": 123456, "label": "Office"}'

Response

{ "success": true, "data": { "id": 123459 } }

PUT|PATCH /api/v1/authips/{id}.json

Updates ip or label. Returns {"success": true, "data": []}.

DELETE /api/v1/authips/{id}.json

Removes one auth IP. Returns {"success": true, "data": []}.

Example

curl -X DELETE https://proxybonanza.com/api/v1/authips/123459.json \
  -H "Authorization: $API_KEY"

POST /api/v1/authips/import-many.json

Bulk-imports auth IPs. Body is a JSON array of objects (ip, userpackage_id, label). Returns one entry per row with _success/_errors.

Example

curl -X POST https://proxybonanza.com/api/v1/authips/import-many.json \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"ip":"203.0.113.60","userpackage_id":123456},{"ip":"203.0.113.61","userpackage_id":123456,"label":"two"}]'

Response

{
  "success": true,
  "data": [
    { "_success": true, "_errors": [], "id": 123460, "ip": "203.0.113.60", "userpackage_id": 123456, "label": null },
    { "_success": true, "_errors": [], "id": 123461, "ip": "203.0.113.61", "userpackage_id": 123456, "label": "two" }
  ]
}

POST /api/v1/authips/delete-all.json

Deletes auth IPs. {"id": {"_all": true}} deletes all of your auth IPs; {"id": [1, 2, 3]} deletes specific ones. 404 if there is nothing to delete.

Example

curl -X POST https://proxybonanza.com/api/v1/authips/delete-all.json \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": {"_all": true}}'

POST /api/v1/userpackages/{userpackage_id}/authips/applyToOtherUserpackages.json

Copies all auth IPs from one plan to all your other active plans. 403 if userpackage_id isn't yours. Response is a per-row result array like import-many.

Example

curl -X POST https://proxybonanza.com/api/v1/userpackages/123456/authips/applyToOtherUserpackages.json \
  -H "Authorization: $API_KEY"

Proxy IP list (userpackages-ippacks)

GET /api/v1/userpackages-ippacks.json

Returns all proxy IPs of all your active plans (not paginated; can be large).

Parameters

  • userpackage_id — only one plan

Example

curl "https://proxybonanza.com/api/v1/userpackages-ippacks.json?userpackage_id=123456" \
  -H "Authorization: $API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "ip": "203.0.113.10",
      "outgoing_ip": "203.0.113.10",
      "port_http": 8080,
      "port_socks": 1080,
      "login": "login11",
      "password": "secretpass",
      "countrycode": "PL",
      "georegion_name": "Warsaw",
      "userpackage_id": 123456,
      "country_name": "Poland"
    }
  ]
}

GET /api/v1/userpackages-ippacks.txt (or .csv)

Same data as CSV. First row is the header.

Parameters

  • _delimiter — comma (default), tab, ., :, ;
  • _csvFields[] — limit columns, e.g. _csvFields[]=ip&_csvFields[]=port_http

Example

curl "https://proxybonanza.com/api/v1/userpackages-ippacks.txt?userpackage_id=123456&_delimiter=tab&_csvFields[]=ip&_csvFields[]=port_http" \
  -H "Authorization: $API_KEY"

Response

ip	port_http
203.0.113.10	8080
203.0.113.11	8080

Usage statistics

All stats endpoints take the plan id as the URL segment and only work on your plans (404 otherwise). Bandwidth values are in bytes; *_human fields are pre-formatted strings.

Shared parameters:

  • days — look back N days (default 30), on stats/daily endpoints
  • date — one day YYYY-MM-DD, on hourly endpoints
  • ip — filter by source IP (on bysourceip variants)
  • georegion_id — filter by proxy location (on byproxylocation variants)

GET /api/v1/userpackagestats/{id}.json

Totals over the period (default 30 days), summed.

Example

curl "https://proxybonanza.com/api/v1/userpackagestats/123456.json?days=30" \
  -H "Authorization: $API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "userpackage_id": 123456,
      "bnd_http": 1048576,
      "conn_http": 1175,
      "bnd_socks": 0,
      "conn_socks": 0,
      "bnd_total": 1048576,
      "conn_total": 1175,
      "bnd_http_human": "1.00 MB",
      "bnd_socks_human": "0 B",
      "bnd_total_human": "1.00 MB",
      "date": null,
      "used_on_day": null
    }
  ]
}

GET /api/v1/userpackagestats/bysourceip/{id}.json

Same totals grouped by source IP (ip field; filter with ?ip=).

GET /api/v1/userpackagestats/byproxylocation/{id}.json

Same totals grouped by proxy location. proxyserver contains georegion_id and georegion.name.

GET /api/v1/userpackagedailystats/{id}.json

Per-day rows (last 30 days by default, ?days=N), newest first.

Example

curl "https://proxybonanza.com/api/v1/userpackagedailystats/123456.json?days=7" \
  -H "Authorization: $API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "userpackage_id": 123456,
      "date": "2026-10-14",
      "bnd_http": 1048576,
      "conn_http": 1175,
      "bnd_socks": 0,
      "conn_socks": 0,
      "bnd_total": 1048576,
      "conn_total": 1175,
      "bnd_http_human": "1.00 MB",
      "bnd_socks_human": "0 B",
      "bnd_total_human": "1.00 MB",
      "used_on_day": null
    }
  ]
}

Variants: bysourceip (adds ip, ?ip= filter), byproxylocation (adds proxyserver, ?georegion_id= filter).

GET /api/v1/userpackagehourlystats/{id}.json

Per-hour rows. Without parameters: last 24 hours. With ?date=YYYY-MM-DD: that day (ascending hours).

Example

curl "https://proxybonanza.com/api/v1/userpackagehourlystats/123456.json?date=2026-10-14" \
  -H "Authorization: $API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "userpackage_id": 123456,
      "date": "2026-10-14",
      "hour": 8,
      "bnd_http": 1048576,
      "conn_http": 1175,
      "bnd_socks": 0,
      "conn_socks": 0,
      "bnd_total": 1048576,
      "conn_total": 1175,
      "bnd_http_human": "1.00 MB",
      "bnd_socks_human": "0 B",
      "bnd_total_human": "1.00 MB",
      "used_on_day": null,
      "used_on_time": null
    }
  ]
}

Variants: bysourceip (adds ip, ?ip=), byproxylocation (adds proxyserver, ?georegion_id=).

© 2026 ProxyBonanza.com. All rights reserved. 30 days money back guarantee.