JesusProxy Build API reference
Manage your Android proxy connection from code: read live status, create HTTP and SOCKS5 access points, rotate the carrier IP, pull traffic and uptime stats, and download VPN profiles. Plain HTTPS and JSON, authenticated with an API key.
$ curl -x http://USERNAME:PASSWORD@HOST:PORT https://example.com$ curl "YOUR_PRIVATE_ROTATION_URL"Base URL and conventions
https://build.jesusproxy.com/api- Every request uses HTTPS and returns JSON (VPN profiles and the CSV export return files).
- Send JSON bodies with
Content-Type: application/json. Response fields are camelCase; request bodies accept camelCase or snake_case. - Timestamps are ISO 8601 with a UTC offset. IDs are UUIDs.
- Some paths end in a slash and some do not. Copy them exactly as listed below.
You don’t need the API to use your proxy. Normal traffic goes through the host, port, username and password of an access point. The API is for automating what the dashboard does: rotation, access points, monitoring and VPN profiles.
Authentication: two kinds of key
| Key | Starts with | Where to create it | What it can reach |
|---|---|---|---|
| Connection key | jp_ | Dashboard → your connection → Advanced → API Key | Built for one connection. Use the short /connection/… paths; the server fills in the connection for you. |
| Account key | jpa_ | Dashboard → Profile → API key | Every connection on your account. Use /connections/{id}/… paths. |
Send the key in either header. Both work on every endpoint:
Authorization: Bearer jp_YOUR_CONNECTION_KEY
X-API-Key: jp_YOUR_CONNECTION_KEYcurl -s https://build.jesusproxy.com/api/connection/status \
-H "Authorization: Bearer jp_YOUR_CONNECTION_KEY"import os, requests
API = "https://build.jesusproxy.com/api"
headers = {"Authorization": f"Bearer {os.environ['JP_API_KEY']}"}
r = requests.get(f"{API}/connection/status", headers=headers, timeout=20)
r.raise_for_status()
print(r.json())// Node 18+ (built-in fetch)
const API = "https://build.jesusproxy.com/api";
const headers = { Authorization: `Bearer ${process.env.JP_API_KEY}` };
const res = await fetch(`${API}/connection/status`, { headers });
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());- The full key is shown once, when you create it. Store it in a secret manager or an environment variable.
- A connection has one active key at a time. Creating a new key revokes the old one immediately, which is also how you replace a leaked key.
- Only the account owner can create or revoke keys. Team members cannot.
- Keys can’t manage other keys, team members, your profile or password. Handle those, and wallet top-ups and plan purchases, in the dashboard.
If a script only touches one phone, give it that connection’s jp_ key. Keep the account-wide jpa_ key for your own back office, never in a client app, browser extension or shared server.
Endpoint reference
Paths are relative to https://build.jesusproxy.com/api. With a connection key use them as written. With an account key, replace /connection with /connections/{connectionId}.
Account
| Method | Path | What it does | Key |
|---|---|---|---|
| GET | /connections | List the connections on your account: id, name, plan, status, online flag and expiry. | jpa_ |
| GET | /account/ | Your highest active plan and a summary of each connection. | jpa_ |
Connection
| Method | Path | What it does | Key |
|---|---|---|---|
| GET | /connectionAccount key: /connections/ | Connection details: name, plan, status, online, expiry, host and port. | jp_jpa_ |
| PATCH | /connectionAccount key: /connections/ | Update name, description, group or autoRenew. | jp_jpa_ |
| GET | /connection/Account key: /connections/ | Live snapshot: online, exit IP, tunnel protocol, last heartbeat, battery, network type and rotation status. | jp_jpa_ |
Example response: GET /connection/status
{
"online": true,
"status": "active",
"tunnelProtocol": "wireguard",
"exitIp": "203.0.113.24",
"lastHeartbeat": "2026-11-22T08:15:04+00:00",
"batteryLevel": 84,
"networkType": "5G",
"rotationStatus": "idle",
"plan": "bigdaddy_pro",
"planLabel": "JesusProxy Max"
}Access points (proxies)
| Method | Path | What it does | Key |
|---|---|---|---|
| GET POST | /connection/Account key: /connections/ | List access points or create one. Body: protocol (http or socks5), authMode (credentials or open), login/password or generateLogin/generatePassword, optional description and expiresAt. | jp_jpa_ |
| GET PATCH DELETE | /proxies/ | Read, edit (same fields as create) or delete one access point. | jp_jpa_ |
| POST | /proxies/ | Issue a new password for one access point. | jp_jpa_ |
| POST | /connection/Account key: /connections/ | Pause an access point without deleting it. …/start resumes it. | jp_jpa_ |
| POST | /connection/Account key: /connections/ | New passwords for every access point on the connection. | jp_jpa_ |
| POST | /connection/Account key: /connections/ | Set one expiresAt on every access point (null clears it). | jp_jpa_ |
# list access points
curl -s https://build.jesusproxy.com/api/connection/proxies -H "Authorization: Bearer jp_YOUR_CONNECTION_KEY"
# create a SOCKS5 access point with generated credentials
curl -s -X POST https://build.jesusproxy.com/api/connection/proxies \
-H "Authorization: Bearer jp_YOUR_CONNECTION_KEY" \
-H "Content-Type: application/json" \
-d '{"protocol":"socks5","authMode":"credentials","generateLogin":true,"generatePassword":true,"description":"scraper-1"}'import os, requests
API = "https://build.jesusproxy.com/api"
H = {"Authorization": f"Bearer {os.environ['JP_API_KEY']}"}
new = requests.post(f"{API}/connection/proxies", headers=H, timeout=20, json={
"protocol": "socks5", # or "http"
"authMode": "credentials", # or "open"
"generateLogin": True,
"generatePassword": True,
"description": "scraper-1",
}).json()
print(new["host"], new["port"], new["login"])
# rename it, then issue a new password
requests.patch(f"{API}/proxies/{new['id']}", headers=H, json={"description": "scraper-main"}, timeout=20)
requests.post(f"{API}/proxies/{new['id']}/regenerate-password", headers=H, timeout=20)const API = "https://build.jesusproxy.com/api";
const H = { Authorization: `Bearer ${process.env.JP_API_KEY}`, "Content-Type": "application/json" };
const res = await fetch(`${API}/connection/proxies`, {
method: "POST",
headers: H,
body: JSON.stringify({ protocol: "http", authMode: "credentials", generateLogin: true, generatePassword: true }),
});
const proxy = await res.json();
console.log(`${proxy.host}:${proxy.port}`, proxy.login);IP rotation
| Method | Path | What it does | Key |
|---|---|---|---|
| POST | /connection/Account key: /connections/ | Ask the phone for a new carrier IP. 200 when the phone is online; 503 when it is offline (the request stays queued). | jp_jpa_ |
| GET | /connection/Account key: /connections/ | Rotation progress: status, lastRotationAt, requestedAt, currentExitIp, online. | jp_jpa_ |
| GET | /connection/Account key: /connections/ | Your primary private rotation link (created on first call). | jp_jpa_ |
| GET POST | /connection/Account key: /connections/ | List rotation links with hit counts, or create another one. | jp_jpa_ |
| DELETE | /rotation-urls/ | Delete a rotation link so it stops working. | jpa_ |
| GET PATCH | /connection/Account key: /connections/ | Automatic rotation: autoRotationEnabled, rotationIntervalMinutes (5–1440) and airplaneDurationSeconds (5–60). | jp_jpa_ |
Phone pairing PIN
| Method | Path | What it does | Key |
|---|---|---|---|
| POST | /connection/Account key: /connections/ | Create a fresh pairing PIN for the Android app, with a QR image as a data URL. Needs an active plan. | jp_jpa_ |
| GET | /connection/Account key: /connections/ | The current active PIN. Returns an empty response when there is none. | jp_jpa_ |
Statistics and history
| Method | Path | What it does | Key |
|---|---|---|---|
| GET | /connection/Account key: /connections/ | Phone uptime history. Optional timezone (IANA name, e.g. Europe/London). | jp_jpa_ |
| GET | /connection/Account key: /connections/ | Hourly traffic for one day. Optional date=YYYY-MM-DD, timezone, port. | jp_jpa_ |
| GET | /connection/Account key: /connections/ | Daily traffic for a month. Optional date and timezone. | jp_jpa_ |
| GET | /connection/Account key: /connections/ | Exit IPs the phone has used. Paginated with page and page_size. | jp_jpa_ |
| GET | /connection/Account key: /connections/ | The same history as a CSV file. | jp_jpa_ |
| GET | /connection/Account key: /connections/ | IPs that came back more than once. Optional hours window. | jp_jpa_ |
Proxy test
| Method | Path | What it does | Key |
|---|---|---|---|
| POST | /connection/Account key: /connections/ | Test connectivity and speed through an access point. Body: proxy_type (http or socks5), host, port, username, password, optional target_url. Returns 202 with a taskId. | jp_jpa_ |
| GET | /proxy-test-result/ | Poll for the result: pending, then success (exit IP, location, download and upload Mbps, latency) or failed with an error. | jp_jpa_ |
VPN profiles and bandwidth limits (JesusProxy Max)
| Method | Path | What it does | Key |
|---|---|---|---|
| GET | /connection/Account key: /connections/ | Download the connection’s WireGuard profile (.conf). | jp_jpa_ |
| GET | /connection/Account key: /connections/ | Download the connection’s OpenVPN profile (.ovpn). | jp_jpa_ |
| GET POST | /connection/Account key: /connections/ | List or create named WireGuard profiles. Body: name, optional setExpiration and expiresAt. | jp_jpa_ |
| GET PATCH DELETE | /connection/ | Read, rename, change the expiry of or delete one profile. Add download/ for the file. | jp_jpa_ |
| GET POST | /connection/Account key: /connections/ | The same for named OpenVPN profiles. | jp_jpa_ |
| GET PATCH | /connection/ | Read or set the DNS servers written into WireGuard profiles (wgCommonDns). | jp_jpa_ |
| GET POST | /connection/Account key: /connections/ | Monthly bandwidth limits. Body: name, limitGb, action (notify, deactivate or deactivate_notify), scope (connection or proxy) and proxyId for a proxy scope. | jp_jpa_ |
| GET PATCH DELETE | /connection/ | Manage one limit. reset/ (POST) clears it; usage/ (GET) shows usage. | jp_jpa_ |
On Lite and Pro these endpoints return 403 with "code": "pro_required". Profile downloads are rate limited (see below).
Rotation links and rotation timing
A rotation link is a private URL that changes the IP when it is opened. It needs no API key, which makes it handy for tools that can only call a URL. Copy yours from the dashboard (Change IP → URL) or GET /connection/rotation-url. It looks like https://rt.jpxdx.net/rotate/YOUR_SECRET; older links on rotate.jesusproxy.com keep working.
curl -s "https://rt.jpxdx.net/rotate/YOUR_SECRET"| Response | Meaning |
|---|---|
200 | Rotation started, or one is already running ("status": "already_in_progress"). |
503 | The phone is offline. The rotation is queued and runs when the phone reconnects. |
403 | Rotation is blocked for this connection right now, for example because the plan is off. |
404 | Unknown or deleted link. |
429 | Too many calls. Wait and try again. |
- Link previews and prefetches (chat apps, crawlers, HEAD requests) never rotate. Only a real GET does.
- A rotation usually completes within about a minute while the phone switches mobile data off and on. Poll
/connection/rotation-status/or/connection/statusinstead of sleeping a fixed time. - Your host, port, username and password stay the same after a rotation. Only the exit IP changes.
- Rotate between jobs, not in the middle of a logged-in session.
curl -s -X POST https://build.jesusproxy.com/api/connection/rotate-ip \
-H "Authorization: Bearer jp_YOUR_CONNECTION_KEY"
# then poll until the new IP is in place
curl -s https://build.jesusproxy.com/api/connection/rotation-status/ \
-H "Authorization: Bearer jp_YOUR_CONNECTION_KEY"import os, time, requests
API = "https://build.jesusproxy.com/api"
H = {"Authorization": f"Bearer {os.environ['JP_API_KEY']}"}
before = requests.get(f"{API}/connection/status", headers=H, timeout=20).json().get("exitIp")
r = requests.post(f"{API}/connection/rotate-ip", headers=H, timeout=20)
if r.status_code == 503:
raise SystemExit("Phone is offline: " + r.json()["message"])
r.raise_for_status()
for _ in range(30): # up to ~2.5 minutes
time.sleep(5)
s = requests.get(f"{API}/connection/rotation-status/", headers=H, timeout=20).json()
if s.get("currentExitIp") and s["currentExitIp"] != before:
print("new exit IP:", s["currentExitIp"])
breakconst API = "https://build.jesusproxy.com/api";
const H = { Authorization: `Bearer ${process.env.JP_API_KEY}` };
const sleep = ms => new Promise(r => setTimeout(r, ms));
const before = (await (await fetch(`${API}/connection/status`, { headers: H })).json()).exitIp;
const start = await fetch(`${API}/connection/rotate-ip`, { method: "POST", headers: H });
if (start.status === 503) throw new Error((await start.json()).message);
for (let i = 0; i < 30; i++) {
await sleep(5000);
const s = await (await fetch(`${API}/connection/rotation-status/`, { headers: H })).json();
if (s.currentExitIp && s.currentExitIp !== before) {
console.log("new exit IP:", s.currentExitIp);
break;
}
}Sending traffic through the proxy
Use the host, port, username and password of an access point (Dashboard → connection → Proxy, or GET /connection/proxies). Use socks5h:// when you want DNS resolved on the phone side too.
curl -x http://USERNAME:PASSWORD@HOST:PORT https://api.ipify.org
curl -x socks5h://USERNAME:PASSWORD@HOST:PORT https://api.ipify.orgimport requests
proxy = "http://USERNAME:PASSWORD@HOST:PORT" # socks5h://… needs: pip install "requests[socks]"
r = requests.get("https://api.ipify.org?format=json",
proxies={"http": proxy, "https": proxy}, timeout=30)
print(r.json())// npm i undici
import { fetch, ProxyAgent } from "undici";
const dispatcher = new ProxyAgent("http://USERNAME:PASSWORD@HOST:PORT");
const res = await fetch("https://api.ipify.org?format=json", { dispatcher });
console.log(await res.json());More clients, browsers and operating systems are covered in the HTTP and SOCKS5 setup guide
Rate limits
| What | Limit |
|---|---|
| Write requests (POST, PATCH, DELETE) per user | 300 per minute and 10,000 per hour |
| Read requests (GET) | Not counted against the write limit. Poll sensibly: every 3–5 seconds during a rotation is plenty. |
| Pairing PIN | 30 per minute |
| Proxy tests | 60 per minute |
| VPN profile downloads and key regeneration | 30 per hour per user and 10 per hour per connection |
| Public rotation links | 20 per minute per client, plus abuse protection |
Going over a limit returns 429. Back off and retry; don’t hammer the endpoint in a loop.
Status codes and error format
Errors are JSON. Most have a detail message, and many add a machine-readable code:
{
"detail": "API key revoked or invalid.",
"code": "api_key_revoked"
}Validation errors list the fields that failed, for example {"protocol": ["\"ftp\" is not a valid choice."]}. The proxy test endpoint answers with {"error": "…"}.
| Status | When it happens |
|---|---|
200, 201, 202, 204 | Success. 201 for creates, 202 for queued proxy tests, 204 for deletes and for “nothing here yet”. |
400 | The body or a query parameter is invalid. |
401 | No key (api_key_required) or a revoked or wrong key (api_key_revoked). |
403 | The key may not do this: another connection, key or team management, profile or password; a Max-only feature (pro_required); or an inactive plan. |
404 | The resource doesn’t exist or doesn’t belong to this key. |
429 | Rate limit reached. |
503 | Rotation requested while the phone is offline. |
Keep keys and links private
- Call the API from a server, script or back office, never from browser JavaScript or an app you give to other people.
- Keep keys in environment variables or a secret manager, not in Git, screenshots or support chats.
- Treat rotation links and proxy passwords like keys: anyone who has them can use them.
- If something leaks, create a new connection key (the old one stops at once), regenerate proxy passwords and delete the exposed rotation link.
- Support will never ask for your full API key or password.
Renting proxies instead? That’s a different API
The Share and Private proxies sold on jesusproxy.com have their own API at https://jesusproxy.com/api/v1, with separate jp_live_ keys. It covers rental pricing, wallet balance, purchases, rotation and renewal of rented proxies. It doesn’t manage Build phones.
Next: guides
Automate your own mobile proxies
Create an account, pair an Android phone and generate a connection key from the dashboard.