Proxy access

8 endpoints · base URL https://papaproxy.net/account_new · authentication

GETList proxy IPs
GETGet proxy credentials
PUTChange proxy credentials
GETList whitelisted IPs
POSTAdd a whitelisted IP
DELETERemove a whitelisted IP
GETCheck IP refresh cost
POSTRefresh proxy IPs

List proxy IPs

GET/api/v1/customer/services/{service_id}/proxy/ips

API key required scope services:read

List the proxy IP endpoints of one of your services.

Parameters

Field	Type	Description
`service_id (path)` required	string (uuid)	ID of the service.

Request example Try it in the Dashboard

cURL

curl -X GET "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/ips" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY"

Python

import os

import requests

resp = requests.get(
    "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/ips",
    headers={"Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Node.js

const resp = await fetch("https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/ips", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
  },
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

PHP

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/ips');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
    ],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/ips", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

200 List of proxy IPs for a service. · 10 fields

Example response · JSON

{
  "service_id": "cb532178-5b03-506a-84ea-0230ff28576b",
  "ips": [
    {
      "ip": "192.0.2.10",
      "country": "US",
      "type": "socks5"
    },
    {
      "ip": "192.0.2.11",
      "country": "US",
      "type": "socks5"
    }
  ],
  "format_hints": {},
  "geo_source": "maxmind"
}

Field	Type	Description
`service_id` required	string (uuid)	ID of the service.
`ips` required	array of object
`ips[].ip` required	string	IPv4 or IPv6 address
`ips[].port`	integer, nullable	Minimum: 1Maximum: 65535
`ips[].country`	string, nullable	ISO 3166-1 alpha-2 country code of the IP.
`ips[].type`	string, nullable
`format_hints`	object, nullable	Display hints for proxy IP list rendering.
`format_hints.host_port`	string, nullable
`format_hints.auth_url`	string, nullable
`geo_source`	string, nullable

401 The API key is missing, malformed, revoked, or expired, or the account is inactive.
Example · JSON
```
{
  "detail": "Invalid or revoked API key."
}
```
Error format
403 The API key lacks scope services:read.
Example · JSON
```
{
  "detail": "API key is missing required scope: services:read"
}
```
Error format
404 Service not found, or it doesn't belong to your account.
Example · JSON
```
{
  "detail": "Service 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found."
}
```
Error format
422 Validation error: a field is missing or has the wrong type or value.
Example · JSON
```
{
  "detail": "Validation error"
}
```
Error format
429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.
Example · JSON
```
{
  "detail": "Too Many Requests"
}
```
Error format

Get proxy credentials

GET/api/v1/customer/services/{service_id}/proxy/auth

API key required scope services:read

Get the proxy connection credentials for one of your services.

The password is masked by default; pass reveal=true to receive it in plain text.

Parameters

Field	Type	Description
`service_id (path)` required	string (uuid)	ID of the service.
`reveal (query)`	boolean	Default: `false`

Request example Try it in the Dashboard

cURL

curl -X GET "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/auth" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY"

Python

import os

import requests

resp = requests.get(
    "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/auth",
    headers={"Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Node.js

const resp = await fetch("https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/auth", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
  },
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

PHP

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/auth');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
    ],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/auth", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

200 Current proxy auth status. · 29 fields

Example response · JSON

{
  "username": "pp_user_3fa85f64",
  "protocols": [
    "socks5",
    "http",
    "https"
  ],
  "endpoints": [
    {
      "protocol": "socks5",
      "label": "SOCKS5",
      "scheme": "socks5",
      "port": 1080,
      "port_whitelist": 1085,
      "http2": false,
      "udp": true,
      "noauth_only": false
    },
    {
      "protocol": "http",
      "label": "HTTP",
      "scheme": "http",
      "port": 8080,
      "port_whitelist": 8085,
      "http2": false,
      "udp": false,
      "noauth_only": false
    }
  ],
  "whitelist_ips": [
    "203.0.113.11"
  ],
  "password_set": true,
  "udp_enabled": false
}

Field	Type	Description
`username` required	string	Proxy username.
`password`	string, nullable
`protocols`	array of string
`endpoints`	array of object
`endpoints[].protocol` required	string
`endpoints[].label` required	string
`endpoints[].scheme` required	string
`endpoints[].port`	integer, nullable
`endpoints[].port_whitelist`	integer, nullable
`endpoints[].http2`	boolean	Default: `false`
`endpoints[].udp`	boolean	Default: `false`
`endpoints[].noauth_only`	boolean	Default: `false`
`endpoints[].hostname_template`	string, nullable
`whitelist_ips`	array of string	Whitelisted IPv4 addresses.
`password_set`	boolean	Default: `false`
`udp_enabled`	boolean	Whether UDP is enabled.Default: `false`
`conn_cap`	integer, nullable	Concurrent connection limit of the service.
`whitelist_conn_limits`	object, nullable
`rotating_gateway`	object, nullable	Rotating gateway hostnames and ports for this service. The list fields are authoritative; `entry_host` and `https_host` are the first entries. Lists are empty when a gateway type isn't available for the service.
`rotating_gateway.entry_hosts`	array of string
`rotating_gateway.https_hosts`	array of string
`rotating_gateway.sticky_hosts`	array of string
`rotating_gateway.entry_host`	string, nullable
`rotating_gateway.https_host`	string, nullable
`rotating_gateway.http_ports`	array of integer	HTTP ports.
`rotating_gateway.socks_ports`	array of integer	SOCKS5 ports.
`rotating_gateway.sticky_http`	integer	Default: `5080`
`rotating_gateway.sticky_socks5`	integer	Default: `4080`
`rotating_gateway.sticky_https`	integer	Default: `4443`

401 The API key is missing, malformed, revoked, or expired, or the account is inactive.
Example · JSON
```
{
  "detail": "Invalid or revoked API key."
}
```
Error format
403 The API key lacks scope services:read.
Example · JSON
```
{
  "detail": "API key is missing required scope: services:read"
}
```
Error format
404 Service not found, or it doesn't belong to your account.
Example · JSON
```
{
  "detail": "Service 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found."
}
```
Error format
422 Validation error: a field is missing or has the wrong type or value.
Example · JSON
```
{
  "detail": "Validation error"
}
```
Error format
429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.
Example · JSON
```
{
  "detail": "Too Many Requests"
}
```
Error format

Change proxy credentials

PUT/api/v1/customer/services/{service_id}/proxy/auth

API key required scope services:write

Update proxy credentials — rotate the password or change the login.

Idempotent: a repeated identical payload produces the same state. When rotating, the new password is returned exactly once in the response body.

Parameters

Field	Type	Description
`service_id (path)` required	string (uuid)	ID of the service.

Request body

Field	Type	Description
`rotate_password`	boolean	Default: `false`
`udp_enabled`	boolean, nullable	Whether UDP is enabled.
`new_username`	string, nullable	New proxy login. Must not be taken by another account.Min length: 3Max length: 32
`whitelist_ips`	array of string, nullable	Whitelisted IPv4 addresses.

Request example Try it in the Dashboard

cURL

curl -X PUT "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/auth" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whitelist_ips": ["203.0.113.10"]}'

Python

import os

import requests

resp = requests.put(
    "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/auth",
    headers={"Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}"},
    json={
        "whitelist_ips": [
            "203.0.113.10"
        ]
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Node.js

const resp = await fetch("https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/auth", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "whitelist_ips": [
      "203.0.113.10"
    ]
  }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

PHP

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/auth');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'whitelist_ips' => ['203.0.113.10']
    ]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	req, err := http.NewRequest("PUT", "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/auth", strings.NewReader(`{"whitelist_ips": ["203.0.113.10"]}`))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

200 Current proxy auth status. · 29 fields

Example response · JSON

{
  "username": "pp_user_3fa85f64",
  "protocols": [
    "socks5",
    "http",
    "https"
  ],
  "endpoints": [
    {
      "protocol": "socks5",
      "label": "SOCKS5",
      "scheme": "socks5",
      "port": 1080,
      "port_whitelist": 1085,
      "http2": false,
      "udp": true,
      "noauth_only": false
    },
    {
      "protocol": "http",
      "label": "HTTP",
      "scheme": "http",
      "port": 8080,
      "port_whitelist": 8085,
      "http2": false,
      "udp": false,
      "noauth_only": false
    }
  ],
  "whitelist_ips": [
    "203.0.113.11"
  ],
  "password_set": true,
  "udp_enabled": false
}

Field	Type	Description
`username` required	string	Proxy username.
`password`	string, nullable
`protocols`	array of string
`endpoints`	array of object
`endpoints[].protocol` required	string
`endpoints[].label` required	string
`endpoints[].scheme` required	string
`endpoints[].port`	integer, nullable
`endpoints[].port_whitelist`	integer, nullable
`endpoints[].http2`	boolean	Default: `false`
`endpoints[].udp`	boolean	Default: `false`
`endpoints[].noauth_only`	boolean	Default: `false`
`endpoints[].hostname_template`	string, nullable
`whitelist_ips`	array of string	Whitelisted IPv4 addresses.
`password_set`	boolean	Default: `false`
`udp_enabled`	boolean	Whether UDP is enabled.Default: `false`
`conn_cap`	integer, nullable	Concurrent connection limit of the service.
`whitelist_conn_limits`	object, nullable
`rotating_gateway`	object, nullable	Rotating gateway hostnames and ports for this service. The list fields are authoritative; `entry_host` and `https_host` are the first entries. Lists are empty when a gateway type isn't available for the service.
`rotating_gateway.entry_hosts`	array of string
`rotating_gateway.https_hosts`	array of string
`rotating_gateway.sticky_hosts`	array of string
`rotating_gateway.entry_host`	string, nullable
`rotating_gateway.https_host`	string, nullable
`rotating_gateway.http_ports`	array of integer	HTTP ports.
`rotating_gateway.socks_ports`	array of integer	SOCKS5 ports.
`rotating_gateway.sticky_http`	integer	Default: `5080`
`rotating_gateway.sticky_socks5`	integer	Default: `4080`
`rotating_gateway.sticky_https`	integer	Default: `4443`

401 The API key is missing, malformed, revoked, or expired, or the account is inactive.
Example · JSON
```
{
  "detail": "Invalid or revoked API key."
}
```
Error format
403 The API key lacks scope services:write.
Example · JSON
```
{
  "detail": "API key is missing required scope: services:write"
}
```
Error format
404 Service not found, or it doesn't belong to your account.
Example · JSON
```
{
  "detail": "Service 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found."
}
```
Error format
422 Validation error: a field is missing or has the wrong type or value.
Example · JSON
```
{
  "detail": "Validation error"
}
```
Error format
429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.
Example · JSON
```
{
  "detail": "Too Many Requests"
}
```
Error format

List whitelisted IPs

GET/api/v1/customer/services/{service_id}/proxy/whitelist

API key required scope services:read

List the IP whitelist entries of one of your proxy services.

Parameters

Field	Type	Description
`service_id (path)` required	string (uuid)	ID of the service.

Request example Try it in the Dashboard

cURL

curl -X GET "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY"

Python

import os

import requests

resp = requests.get(
    "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist",
    headers={"Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Node.js

const resp = await fetch("https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
  },
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

PHP

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
    ],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

200 Whitelisted IPs and the service's concurrent connection limit. · 11 fields

Example response · JSON

{
  "service_id": "cb532178-5b03-506a-84ea-0230ff28576b",
  "entries": [
    {
      "ip_or_cidr": "203.0.113.11",
      "conn_limit": 1500,
      "is_paid": false
    }
  ],
  "conn_cap": 1500,
  "capacity": 5,
  "free_quota": 5,
  "used": 1,
  "paid_slots": 0
}

Field	Type	Description
`service_id` required	string (uuid)	ID of the service.
`entries` required	array of object
`entries[].ip_or_cidr` required	string
`entries[].label`	string, nullable
`entries[].conn_limit`	integer, nullable	Concurrent connections allowed from this IP.
`entries[].is_paid`	boolean	Default: `false`
`conn_cap` required	integer	Concurrent connection limit of the service.
`capacity`	integer	Default: `0`
`free_quota`	integer	Default: `0`
`used`	integer	Default: `0`
`paid_slots`	integer	Default: `0`

401 The API key is missing, malformed, revoked, or expired, or the account is inactive.
Example · JSON
```
{
  "detail": "Invalid or revoked API key."
}
```
Error format
403 The API key lacks scope services:read.
Example · JSON
```
{
  "detail": "API key is missing required scope: services:read"
}
```
Error format
404 Service not found, or it doesn't belong to your account.
Example · JSON
```
{
  "detail": "Service 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found."
}
```
Error format
422 Validation error: a field is missing or has the wrong type or value.
Example · JSON
```
{
  "detail": "Validation error"
}
```
Error format
429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.
Example · JSON
```
{
  "detail": "Too Many Requests"
}
```
Error format

Add a whitelisted IP

POST/api/v1/customer/services/{service_id}/proxy/whitelist

API key required scope services:write

Add a single IPv4 address to the service's IP whitelist.

Only single addresses are accepted (no CIDR subnets).

Parameters

Field	Type	Description
`service_id (path)` required	string (uuid)	ID of the service.

Request body

Field	Type	Description
`ip_or_cidr` required	string	Single IPv4 address (CIDR subnets are not supported)
`label`	string, nullable
`conn_limit`	integer, nullable	Concurrent connections allowed from this IP.Minimum: 0

Request example Try it in the Dashboard

cURL

curl -X POST "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip_or_cidr": "203.0.113.10"}'

Python

import os

import requests

resp = requests.post(
    "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist",
    headers={"Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}"},
    json={
        "ip_or_cidr": "203.0.113.10"
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Node.js

const resp = await fetch("https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ip_or_cidr": "203.0.113.10"
  }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

PHP

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'ip_or_cidr' => '203.0.113.10'
    ]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	req, err := http.NewRequest("POST", "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist", strings.NewReader(`{"ip_or_cidr": "203.0.113.10"}`))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

200 Whitelisted IPs and the service's concurrent connection limit. · 11 fields

Example response · JSON

{
  "service_id": "cb532178-5b03-506a-84ea-0230ff28576b",
  "entries": [
    {
      "ip_or_cidr": "203.0.113.11",
      "conn_limit": 750,
      "is_paid": false
    },
    {
      "ip_or_cidr": "203.0.113.77",
      "conn_limit": 750,
      "is_paid": false
    }
  ],
  "conn_cap": 1500,
  "capacity": 5,
  "free_quota": 5,
  "used": 2,
  "paid_slots": 0
}

Field	Type	Description
`service_id` required	string (uuid)	ID of the service.
`entries` required	array of object
`entries[].ip_or_cidr` required	string
`entries[].label`	string, nullable
`entries[].conn_limit`	integer, nullable	Concurrent connections allowed from this IP.
`entries[].is_paid`	boolean	Default: `false`
`conn_cap` required	integer	Concurrent connection limit of the service.
`capacity`	integer	Default: `0`
`free_quota`	integer	Default: `0`
`used`	integer	Default: `0`
`paid_slots`	integer	Default: `0`

401 The API key is missing, malformed, revoked, or expired, or the account is inactive.
Example · JSON
```
{
  "detail": "Invalid or revoked API key."
}
```
Error format
403 The API key lacks scope services:write.
Example · JSON
```
{
  "detail": "API key is missing required scope: services:write"
}
```
Error format
404 Service not found, or it doesn't belong to your account.
Example · JSON
```
{
  "detail": "Service 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found."
}
```
Error format
422 Validation error: a field is missing or has the wrong type or value.
Example · JSON
```
{
  "detail": "Validation error"
}
```
Error format
429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.
Example · JSON
```
{
  "detail": "Too Many Requests"
}
```
Error format

Remove a whitelisted IP

DELETE/api/v1/customer/services/{service_id}/proxy/whitelist

API key required scope services:write

Remove an IP address from the service's IP whitelist.

Parameters

Field	Type	Description
`service_id (path)` required	string (uuid)	ID of the service.
`ip_or_cidr (query)` required	string	IP address to remove from the whitelist

Request example Try it in the Dashboard

cURL

curl -X DELETE "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist?ip_or_cidr=203.0.113.10" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY"

Python

import os

import requests

resp = requests.delete(
    "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist?ip_or_cidr=203.0.113.10",
    headers={"Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Node.js

const resp = await fetch("https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist?ip_or_cidr=203.0.113.10", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
  },
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

PHP

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist?ip_or_cidr=203.0.113.10');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
    ],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("DELETE", "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/whitelist?ip_or_cidr=203.0.113.10", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

200 Whitelisted IPs and the service's concurrent connection limit. · 11 fields

Example response · JSON

{
  "service_id": "cb532178-5b03-506a-84ea-0230ff28576b",
  "entries": [
    {
      "ip_or_cidr": "203.0.113.11",
      "conn_limit": 1500,
      "is_paid": false
    }
  ],
  "conn_cap": 1500,
  "capacity": 5,
  "free_quota": 5,
  "used": 1,
  "paid_slots": 0
}

Field	Type	Description
`service_id` required	string (uuid)	ID of the service.
`entries` required	array of object
`entries[].ip_or_cidr` required	string
`entries[].label`	string, nullable
`entries[].conn_limit`	integer, nullable	Concurrent connections allowed from this IP.
`entries[].is_paid`	boolean	Default: `false`
`conn_cap` required	integer	Concurrent connection limit of the service.
`capacity`	integer	Default: `0`
`free_quota`	integer	Default: `0`
`used`	integer	Default: `0`
`paid_slots`	integer	Default: `0`

401 The API key is missing, malformed, revoked, or expired, or the account is inactive.
Example · JSON
```
{
  "detail": "Invalid or revoked API key."
}
```
Error format
403 The API key lacks scope services:write.
Example · JSON
```
{
  "detail": "API key is missing required scope: services:write"
}
```
Error format
404 Service not found, or it doesn't belong to your account.
Example · JSON
```
{
  "detail": "Service 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found."
}
```
Error format
422 Validation error: a field is missing or has the wrong type or value.
Example · JSON
```
{
  "detail": "Validation error"
}
```
Error format
429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.
Example · JSON
```
{
  "detail": "Too Many Requests"
}
```
Error format

Check IP refresh cost

GET/api/v1/customer/services/{service_id}/proxy/refresh-status

API key required scope services:read

Check whether the next IP refresh for this service is free or paid.

Read-only.

Parameters

Field	Type	Description
`service_id (path)` required	string (uuid)	ID of the service.

Request example Try it in the Dashboard

cURL

curl -X GET "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/refresh-status" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY"

Python

import os

import requests

resp = requests.get(
    "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/refresh-status",
    headers={"Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Node.js

const resp = await fetch("https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/refresh-status", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
  },
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

PHP

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/refresh-status');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
    ],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/refresh-status", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

200 Status of the next IP reallocation for a service. · 7 fields

Example response · JSON

{
  "service_id": "cb532178-5b03-506a-84ea-0230ff28576b",
  "is_free": false,
  "free_window_days": 8,
  "days_since_start": 0,
  "next_free_refresh_at": "2026-11-15T14:26:50.787259Z",
  "price_cents": 1000,
  "is_pool_service": true
}

Field	Type	Description
`service_id` required	string (uuid)	ID of the service.
`is_free` required	boolean
`free_window_days` required	integer
`days_since_start` required	integer, nullable
`next_free_refresh_at`	string (date-time), nullable
`price_cents` required	integer	Price in cents.
`is_pool_service` required	boolean	Whether the service uses a shared IP pool.

401 The API key is missing, malformed, revoked, or expired, or the account is inactive.
Example · JSON
```
{
  "detail": "Invalid or revoked API key."
}
```
Error format
403 The API key lacks scope services:read.
Example · JSON
```
{
  "detail": "API key is missing required scope: services:read"
}
```
Error format
404 Service not found, or it doesn't belong to your account.
Example · JSON
```
{
  "detail": "Service 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found."
}
```
Error format
422 Validation error: a field is missing or has the wrong type or value.
Example · JSON
```
{
  "detail": "Validation error"
}
```
Error format
429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.
Example · JSON
```
{
  "detail": "Too Many Requests"
}
```
Error format

Refresh proxy IPs

POST/api/v1/customer/services/{service_id}/proxy/refresh

API key required scope services:write

Replace the IPs of a proxy service. Pass target_ips to replace only specific addresses, or omit it to refresh the whole list. For dedicated proxies, target_ips is required; without it the response is 422 with detail.code = "dedicated_refresh_target_required". Scheduled refreshes are free; an off-cycle refresh is charged to your wallet — check GET …/proxy/refresh-status first. Pass idempotency_key so a retried call can't charge twice.

Parameters

Field	Type	Description
`service_id (path)` required	string (uuid)	ID of the service.

Request body

Field	Type	Description
`idempotency_key` required	string	Unique key for this refresh intent; retries with the same key return the original result and never charge twice.
`target_ips`	array of string, nullable	Specific currently-allocated IPs to replace. Omit to refresh the entire allocation.

Request example Try it in the Dashboard

cURL

curl -X POST "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/refresh" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key": "refresh-2026-001"}'

Python

import os

import requests

resp = requests.post(
    "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/refresh",
    headers={"Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}"},
    json={
        "idempotency_key": "refresh-2026-001"
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Node.js

const resp = await fetch("https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/refresh", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "idempotency_key": "refresh-2026-001"
  }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

PHP

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/refresh');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'idempotency_key' => 'refresh-2026-001'
    ]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	req, err := http.NewRequest("POST", "https://papaproxy.net/account_new/api/v1/customer/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/proxy/refresh", strings.NewReader(`{"idempotency_key": "refresh-2026-001"}`))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

200 Result of a successful IP reallocation. · 5 fields

Field	Type	Description
`service_id` required	string (uuid)	ID of the service.
`ip_count` required	integer	Number of IPs.
`charged_cents` required	integer	Amount charged to your wallet, in cents.
`ledger_entry_id` required	string (uuid), nullable
`new_ips`	array of string

401 The API key is missing, malformed, revoked, or expired, or the account is inactive.
Example · JSON
```
{
  "detail": "Invalid or revoked API key."
}
```
Error format
403 The API key lacks scope services:write.
Example · JSON
```
{
  "detail": "API key is missing required scope: services:write"
}
```
Error format
404 Service not found, or it doesn't belong to your account.
Example · JSON
```
{
  "detail": "Service 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found."
}
```
Error format
422 Validation error, or target_ips is missing for a dedicated service.
Example · JSON
```
{
  "detail": {
    "code": "dedicated_refresh_target_required",
    "message": "…"
  }
}
```
Error format
429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.
Example · JSON
```
{
  "detail": "Too Many Requests"
}
```
Error format

Last updated: November 9, 2026. Generated from the OpenAPI 3.1 specification (API version 0.1.0). Markdown version for AI agents.