PapaProxy.net API

Authentication

Pass an API key as a bearer token:

Authorization: Bearer <api_key>

Create and revoke keys in the Dashboard under Settings → API keys (papaproxy.net/account_new/settings#api-keys). The /api/v1/customers/me/api-keys endpoints work only in a signed-in Dashboard session: an API key can't list, create, or revoke keys, so a leaked key can't be used to issue new ones. Each key has an explicit set of scopes. A request made with a key that lacks the scope an endpoint requires fails with 403; a missing, malformed, revoked, or expired key fails with 401.

A few endpoints work without a key: GET /api/v1/billing/countries, GET /api/v1/billing/composite/pricing-info, POST /api/v1/billing/composite/auto-plan, POST /api/v1/billing/composite/quote, GET /api/v1/billing/dedicated/countries, and POST /api/v1/billing/dedicated/quote.

Scopes

Each API key has an explicit set of scopes, chosen when you create the key. Every endpoint in this reference and every MCP tool lists the scope it requires, and a request with a key that lacks it fails with 403. Scopes work the same way for the REST API and the MCP server.

Typical key setups for monitoring and provisioning: papaproxy.net/developers.php#scopes

Conventions

• Money is always an integer number of cents (USD). Fields ending in _millicents are thousandths of a cent: 220000 millicents is $2.20.
• Countries in requests are ISO 3166-1 alpha-2 codes (DE, GB, US). Proxy-package endpoints also accept the numeric country ID from GET /api/v1/billing/countries; dedicated-proxy endpoints accept ISO codes only.
• In proxy-package responses, country is the numeric country ID and country_code is the ISO code.
• Timestamps are ISO 8601 in UTC.
• Requests that charge your wallet need the wallet:spend scope in addition to services:write. A key without wallet:spend can read, quote, and configure, but its paid requests fail with 403.
• Requests that charge your wallet confirm the price you showed the user (expected_price_cents or expected_total_cents). If the price is missing or has changed, the request fails and nothing is charged.
• Endpoints that charge your wallet take an idempotency key; see Idempotency below.

Order minimums

• Proxy packages (datacenter and ISP proxies, /api/v1/billing/composite/*): at least 100 IPs per order and at least 10 IPs per country. Adding IPs to a package follows the same rule: at least 100 IPs per request, at least 10 per country. GET /api/v1/billing/composite/pricing-info returns these values as min_ips_per_order and min_ips_per_segment.
• Dedicated proxies (/api/v1/billing/dedicated/*): from 1 IP per order, and from 1 IP when you add IPs to a dedicated service.
• An order, auto-plan, or quote with fewer than 100 IPs in total fails with 422. A quote with a country below 10 IPs still returns 200: that country is listed in errors and left out of segments and the total. Always check errors before you place the order.

Errors

Every error response is JSON with a detail field. Check the HTTP status first, then read detail, which is either a string or an object:

{"detail": "Invalid or revoked API key."}
{"detail": {"error": "PRICE_CHANGED", "expected_price_cents": 1, "actual_price_cents": 3}}

When detail is an object, the machine-readable code is in detail.error (proxy-package orders, add-ons, service cancellation) or in detail.code (dedicated proxies, IP refresh). Schema validation errors return 422 with {"detail": "Validation error"} and don't name the field, so compare the request with the field table of the endpoint.

• 400 — the request can't be completed in the current state: an unknown add-on type or a missing add-on parameter, a reply to a closed ticket, or insufficient balance for a renewal.
• 401 — the API key is missing, malformed, revoked, or expired, or the account is inactive. The response includes WWW-Authenticate: Bearer.
• 402 — insufficient wallet balance when adding IPs or buying an add-on. Nothing is charged.
• 403 — the API key lacks the required scope, or a top-up needs identity verification.
• 404 — the resource doesn't exist or doesn't belong to your account.
• 409 — the price wasn't confirmed or has changed, stock ran out, or a cancellation cooldown is active. Nothing is charged.
• 422 — a validation error or a business rule: order minimums, a required whitelisted IP, an invalid promo code.
• 429 — rate limit exceeded; see Rate limits.
• 501 — the operation isn't supported for this service.
• 5xx — a temporary server error (500 returns {"detail": "Internal server error"}; 503 means the service is briefly unavailable). Retry after a few seconds with backoff, using the same idempotency key.

The MCP server doesn't return HTTP status codes to your agent: a failed tool call comes back as error text with a short code and an explanation, for example insufficient_pool: … Nothing was charged.

Rate limits

• Each account can make up to 60 requests per minute (a rolling window). All API keys of the account and the MCP server share this limit.
• Requests are also limited per source IP address, including requests without a key, and short bursts are limited separately. Spread requests evenly rather than sending them in bursts.
• A limited request returns 429 with {"detail": "Too Many Requests"}. Wait and retry with exponential backoff (for example, 2, 4, 8 seconds); nothing is charged for a rejected request.
• Each response includes an X-Request-Id header. Include it when you contact support about a specific request.

Testing

There's no sandbox or test mode: every order, top-up, renewal, and add-on charges your real wallet balance. To build and test an integration without spending money:

• Use quotes (POST /api/v1/billing/composite/quote, POST /api/v1/billing/dedicated/quote), which never charge and work without an API key.
• Test webhook handling with POST /api/v1/customer/webhooks/{endpoint_id}/test, which sends a ping event.
• Give a key only the scopes it needs, and keep keys that can spend money out of test environments.

Webhooks

Webhook deliveries are POST requests with a compact JSON body:

{"id": "3f1c2a9e-8b7d-4e6f-9a01-2c5d7e8f9b10", "type": "service.renewed", "created_at": "2026-11-09T13:16:07.181118Z", "data": {…}}

id is the event ID, type is the event type, created_at is in UTC, and data depends on the event type. Each delivery carries these headers:

• X-FB-Signature — v1= followed by the hex-encoded HMAC-SHA256 signature.
• X-FB-Timestamp — the Unix time (seconds) when the delivery was signed.
• X-FB-Event-Id — the event ID. It stays the same when a delivery is retried or redelivered.
• X-FB-Event-Type — the event type.

To verify a delivery, compute HMAC-SHA256 over {X-FB-Timestamp}.{raw body} with the endpoint's full signing secret, including the whsec_ prefix, as the key, and compare the hex digest with the value after v1=. Use the raw request bytes, not re-serialized JSON:

import hashlib, hmac, time

def verify(secret: str, body: bytes, timestamp: str, signature: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    digest = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest("v1=" + digest, signature)

• Reject deliveries whose timestamp is more than 5 minutes from your server's time, and skip event IDs you've already processed. Retries are signed again with a new timestamp.
• Respond with any 2xx status within 10 seconds. Other statuses, timeouts, and redirects (3xx isn't followed) count as failures.
• A failed delivery is retried 5 more times: after 1 minute, 5 minutes, 30 minutes, 2 hours, and 6 hours. After that it's marked as failed; you can send it again with the redeliver endpoint.
• After 20 consecutive failed deliveries, the endpoint is disabled automatically and disabled_reason explains why. A successful delivery resets the counter.
• The URL must be a public https address; private and internal addresses are rejected.
• Deliveries don't come from a fixed set of IP addresses, so verify the signature instead of whitelisting sender IPs.
• Event types: payment.succeeded, payment.failed, deposit.completed, service.provisioned, service.renewed, service.expiring, service.suspended, service.terminated, and wallet.balance_low. GET /api/v1/customer/webhooks/events returns the current list. ping is sent only by the test endpoint and can't be subscribed to.

Pagination

List endpoints return results in pages. Pass offset (how many items to skip) and limit (page size: 50 by default) as query parameters, and keep increasing offset by limit until a page comes back with fewer items than limit.

• GET /api/v1/customer/wallet/ledger — List wallet transactions (limit up to 200)
• GET /api/v1/customer/catalog — List products (limit up to 100)
• GET /api/v1/customer/services — List your services (limit up to 100)
• GET /api/v1/customer/tickets — List support tickets

Idempotency

The endpoints below take an idempotency key — idempotency_key in the request body unless noted otherwise. If a request times out or the connection drops, retry it with the same key and the same body: you get the result of the original request, and you aren't charged twice. Use a new key for each new purchase. Without a key, a repeated request is processed again.

• POST /api/v1/billing/composite/order — Place an order
• POST /api/v1/billing/services/{service_id}/add-ips — Add IPs to a service (required)
• POST /api/v1/billing/services/{service_id}/addons — Buy an add-on (required)
• POST /api/v1/customer/wallet/deposit/init — Top up your wallet
• POST /api/v1/customer/services/{service_id}/renew — Renew a service
• POST /api/v1/customer/services/{service_id}/proxy/refresh — Refresh proxy IPs (required)
• POST /api/v1/billing/dedicated/order — Order dedicated proxies (in the Idempotency-Key header, required)

MCP tools

The MCP server at https://papaproxy.net/account_new/api/v1/mcp gives AI agents 56 tools for your account. They use the same API keys, scopes, and rate limit as the REST API. Most tools call one of the endpoints in this reference; tools marked MCP only have no REST endpoint. To connect Cursor, Claude Code, VS Code, or another client, see papaproxy.net/developers.php#mcp.

• Charges your balance: the tool requires wallet:spend and takes the price you confirmed (expected_total_cents, expected_price_cents, or a similar field). If the price has changed, nothing is charged.
• Needs confirmation: the tool cancels something immediately and runs only with confirm: true. An agent should ask you before it sets this.

Catalog and pricing

Orders

Dedicated proxies

Services

Proxy access

Rotating sessions

Add-ons

Analytics

Wallet

Account

Support tickets

REST only

These endpoints have no MCP tool and work only over REST:

• API keys: List API keys · Create an API key · Revoke an API key
• Orders: Quote additional IPs
• Account: Update your profile
• Catalog and pricing: Get a product
• Wallet: Download an invoice (PDF)
• Rotating sessions: List sticky sessions · Rotate a sticky session · End a sticky session · End all sticky sessions · Get session mode · Set session mode · Get sticky session duration · Set sticky session duration · Reset sticky session duration
• Webhooks: List webhook event types · List webhook endpoints · Create a webhook endpoint · Get a webhook endpoint · Update a webhook endpoint · Delete a webhook endpoint · List webhook deliveries · Send a test event · Redeliver an event
• Dedicated proxies: List dedicated-proxy countries

Endpoints

62 operations in 12 groups.