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.

Bearer or X-API-Key authcurl, Python and Node.jsConnection and account keys
Developer connection
HTTPSOCKS5ROTATE
proxy-client.sh
$ curl -x http://USERNAME:PASSWORD@HOST:PORT https://example.com$ curl "YOUR_PRIVATE_ROTATION_URL"
Host · Port · Username · PasswordSame login after rotation

Base URL and conventions

BUILD API BASE URLhttps://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

KeyStarts withWhere to create itWhat it can reach
Connection keyjp_Dashboard → your connection → Advanced → API KeyBuilt for one connection. Use the short /connection/… paths; the server fills in the connection for you.
Account keyjpa_Dashboard → Profile → API keyEvery 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_KEY
curl -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.
Use the smallest key that does the job

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

MethodPathWhat it doesKey
GET/connectionsList the connections on your account: id, name, plan, status, online flag and expiry.jpa_
GET/account/planYour highest active plan and a summary of each connection.jpa_

Connection

MethodPathWhat it doesKey
GET/connectionAccount key: /connections/{id}Connection details: name, plan, status, online, expiry, host and port.jp_jpa_
PATCH/connectionAccount key: /connections/{id}Update name, description, group or autoRenew.jp_jpa_
GET/connection/statusAccount key: /connections/{id}/statusLive 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)

MethodPathWhat it doesKey
GET POST/connection/proxiesAccount key: /connections/{id}/proxiesList 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/{proxyId}Read, edit (same fields as create) or delete one access point.jp_jpa_
POST/proxies/{proxyId}/regenerate-passwordIssue a new password for one access point.jp_jpa_
POST/connection/proxies/{proxyId}/stopAccount key: /connections/{id}/proxies/{proxyId}/stopPause an access point without deleting it. …/start resumes it.jp_jpa_
POST/connection/proxies/reset-all-passwordsAccount key: /connections/{id}/proxies/reset-all-passwordsNew passwords for every access point on the connection.jp_jpa_
POST/connection/proxies/set-common-expirationAccount key: /connections/{id}/proxies/set-common-expirationSet 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

MethodPathWhat it doesKey
POST/connection/rotate-ipAccount key: /connections/{id}/rotate-ipAsk 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/rotation-status/Account key: /connections/{id}/rotation-status/Rotation progress: status, lastRotationAt, requestedAt, currentExitIp, online.jp_jpa_
GET/connection/rotation-urlAccount key: /connections/{id}/rotation-urlYour primary private rotation link (created on first call).jp_jpa_
GET POST/connection/rotation-urlsAccount key: /connections/{id}/rotation-urlsList rotation links with hit counts, or create another one.jp_jpa_
DELETE/rotation-urls/{urlId}Delete a rotation link so it stops working.jpa_
GET PATCH/connection/rotation-settingsAccount key: /connections/{id}/rotation-settingsAutomatic rotation: autoRotationEnabled, rotationIntervalMinutes (5–1440) and airplaneDurationSeconds (5–60).jp_jpa_

Phone pairing PIN

MethodPathWhat it doesKey
POST/connection/pinAccount key: /connections/{id}/pinCreate a fresh pairing PIN for the Android app, with a QR image as a data URL. Needs an active plan.jp_jpa_
GET/connection/pinAccount key: /connections/{id}/pinThe current active PIN. Returns an empty response when there is none.jp_jpa_

Statistics and history

MethodPathWhat it doesKey
GET/connection/stats/uptime/Account key: /connections/{id}/stats/uptime/Phone uptime history. Optional timezone (IANA name, e.g. Europe/London).jp_jpa_
GET/connection/stats/traffic/daily/Account key: /connections/{id}/stats/traffic/daily/Hourly traffic for one day. Optional date=YYYY-MM-DD, timezone, port.jp_jpa_
GET/connection/stats/traffic/monthly/Account key: /connections/{id}/stats/traffic/monthly/Daily traffic for a month. Optional date and timezone.jp_jpa_
GET/connection/ip-history/Account key: /connections/{id}/ip-history/Exit IPs the phone has used. Paginated with page and page_size.jp_jpa_
GET/connection/ip-history/export/Account key: /connections/{id}/ip-history/export/The same history as a CSV file.jp_jpa_
GET/connection/repeating-ip/Account key: /connections/{id}/repeating-ip/IPs that came back more than once. Optional hours window.jp_jpa_

Proxy test

MethodPathWhat it doesKey
POST/connection/proxy-test/Account key: /connections/{id}/proxy-test/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/{taskId}/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)

MethodPathWhat it doesKey
GET/connection/download/wireguard/Account key: /connections/{id}/download/wireguard/Download the connection’s WireGuard profile (.conf).jp_jpa_
GET/connection/download/openvpn/Account key: /connections/{id}/download/openvpn/Download the connection’s OpenVPN profile (.ovpn).jp_jpa_
GET POST/connection/wireguard-configs/Account key: /connections/{id}/wireguard-configs/List or create named WireGuard profiles. Body: name, optional setExpiration and expiresAt.jp_jpa_
GET PATCH DELETE/connection/wireguard-configs/{configId}/Read, rename, change the expiry of or delete one profile. Add download/ for the file.jp_jpa_
GET POST/connection/openvpn-configs/Account key: /connections/{id}/openvpn-configs/The same for named OpenVPN profiles.jp_jpa_
GET PATCH/connection/wireguard-dns/Read or set the DNS servers written into WireGuard profiles (wgCommonDns).jp_jpa_
GET POST/connection/traffic-triggers/Account key: /connections/{id}/traffic-triggers/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/traffic-triggers/{triggerId}/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"
ResponseMeaning
200Rotation started, or one is already running ("status": "already_in_progress").
503The phone is offline. The rotation is queued and runs when the phone reconnects.
403Rotation is blocked for this connection right now, for example because the plan is off.
404Unknown or deleted link.
429Too 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/status instead 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"]) break
const 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.org
import 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

WhatLimit
Write requests (POST, PATCH, DELETE) per user300 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 PIN30 per minute
Proxy tests60 per minute
VPN profile downloads and key regeneration30 per hour per user and 10 per hour per connection
Public rotation links20 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": "…"}.

StatusWhen it happens
200, 201, 202, 204Success. 201 for creates, 202 for queued proxy tests, 204 for deletes and for “nothing here yet”.
400The body or a query parameter is invalid.
401No key (api_key_required) or a revoked or wrong key (api_key_revoked).
403The key may not do this: another connection, key or team management, profile or password; a Max-only feature (pro_required); or an inactive plan.
404The resource doesn’t exist or doesn’t belong to this key.
429Rate limit reached.
503Rotation 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.

Open the rental API reference

Automate your own mobile proxies

Create an account, pair an Android phone and generate a connection key from the dashboard.