Conventions

Read this page once and the rest of the reference will be predictable. Every endpoint shares the same envelope, the same error shape, and the same retry rules.

The response envelope

Every endpoint returns the same wrapper. The resource you asked for is always under data.

{
  "success": true,
  "data": { },
  "error": null,
  "context": {
    "affected_entities": ["organization:0e4c…"],
    "suggested_next_actions": ["list_proxies"],
    "warnings": []
  },
  "request_id": null,
  "timestamp": "2026-02-18T09:31:04.512Z"
}

Status codes

This is the one place the API will surprise you, so it is worth stating plainly: a request that was well-formed and authenticated returns HTTP 200 even when the action was refused. The refusal is in the body.

The two error shapes differ, which matters if you parse errors in one place. Business failures put the code in error.code; HTTP-level failures put it in detail.code.

HTTP/1.1 200 OK

{
  "success": false,
  "data": null,
  "error": {
    "code": "LAST_ACCOUNT_CANCEL_ONLY",
    "message": "The last live account cannot be removed.",
    "field": null,
    "details": null,
    "suggestion": "Cancel the organization plan in the billing portal."
  },
  "timestamp": "2026-02-18T09:31:04.512Z"
}

HTTP/1.1 401 Unauthorized

{
  "detail": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked.",
    "suggestion": "Generate a new key in the dashboard."
  }
}

Pagination

Only GET /invoices paginates, because only invoices can grow without bound. It uses cursors rather than page numbers, so a new invoice arriving mid-walk does not shift rows into a page you already read.

To walk the whole history, pass the last id of each page as the next starting_after and stop when has_more is false.

import os

import requests

API_KEY = os.environ["PROXYCHARM_API_KEY"]
BASE_URL = "https://api.proxycharm.com/api/v1/public"

cursor = None
invoices = []

while True:
    params = {"limit": 100}
    if cursor:
        params["starting_after"] = cursor

    payload = requests.get(
        f"{BASE_URL}/invoices",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=params,
        timeout=30,
    ).json()

    page = payload["data"]
    invoices.extend(page["items"])

    if not page["has_more"]:
        break
    cursor = page["items"][-1]["id"]

print(len(invoices))

The other list endpoints return every row in one response. GET /workspaces and GET /proxies are bounded by your plan size, so there is nothing to page through.

Filtering

Filtering is per-endpoint rather than a general query language.

Sorting

There is no sort parameter. Invoices come back newest-first; other lists come back in creation order. Sort client-side if you need a different order.

Idempotency

POST /workspaces is the only endpoint that creates a billable resource, so it is the only one that takes an idempotency key. Send one whenever a retry could otherwise double-charge you.

Put a unique value — a UUID works — in idempotency_key. If you retry with the same key, the original workspace is returned instead of a second one being created.

curl https://api.proxycharm.com/api/v1/public/workspaces \
  -X POST \
  -H "Authorization: Bearer $PROXYCHARM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "Scraper EU",
       "slots": [{ "country": "DE" }],
       "idempotency_key": "6f9619ff-8b86-d011-b42d-00c04fc964ff"
     }'

Timestamps, ids, and money

Versioning

The version lives in the path (/api/v1/public). We treat adding a response field or an optional parameter as backwards-compatible, so build your client to ignore fields it does not recognise. Removing a field or changing its meaning would ship as a new version path, and v1 would keep working.