Referência da API

Autenticação e URL base

Todos os endpoints estão sob https://mobileproxy.app/api/v1 e exigem um bearer token. Crie um no dashboard em Para programadores → Tokens de API, ou com POST /tokens depois de iniciar sessão. O segredo é mostrado uma única vez — guarde-o. Envie-o em todos os pedidos:

Authorization: Bearer mpx_live_…

Os tokens que começam por mpx_live_ são os tokens da sua conta. Os endpoints /device/* são chamados pela própria app Android e autenticam com um token de dispositivo por telefone (mpxdev_…) emitido no emparelhamento — normalmente nunca os chama.

Os erros são JSON com uma mensagem legível e um código de máquina:

{ "error": "No such device.", "code": "not_found" }

Conta

GET /me — quem sou eu? Devolve a conta mais as contagens em direto de subscrições e tokens de API.

curl https://mobileproxy.app/api/v1/me \
     -H "Authorization: Bearer mpx_live_…"

# → { "id": "u_8c31f0", "email": "[email protected]",
#     "created_at": "2026-06-28T14:02:11.000Z",
#     "subscriptions": 3, "api_tokens": 2,
#     "plan": "beta", "balance": "0.00" }

Subscrições

Uma subscrição (id sub_…) é o slot duradouro que possui: o seu name amigável, as definições e os proxies persistem mesmo quando o telefone por baixo muda. O seu device é o telefone que a alimenta neste momento (ou null quando não emparelhado) e é trocável — uma troca mantém todos os endpoints de proxy.

Liste as subscrições — cada uma com o seu dispositivo emparelhado combinado com o estado em direto do gateway (online = o túnel de proxy está ativo):

curl https://mobileproxy.app/api/v1/subscriptions \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscriptions": [ {
#     "id": "sub_760c1fc8ddab", "name": "Paris SFR",
#     "status": "active", "wifi_split": true, "created_at": "…",
#     "device": { "id": "phone_ac862619408e", "model": "Galaxy S8",
#                 "hardware_id": "352091081234567", "hardware_type": "imei",
#                 "status": "online", "exit_ip": "77.136.66.63",
#                 "carrier": "SFR", "last_seen": "…", "paired_at": "…" } } ] }

Crie uma subscrição (sem emparelhamento), depois emparelhe ou troque o telefone. POST /subscriptions/{id}/pair devolve um PIN válido ~3 minutos; inserido na app Android, associa o telefone. Num slot que já tem um dispositivo, isto é uma troca (mode: "swap") — o telefone antigo é retirado e cada proxy mantém o seu host:port e credenciais:

curl -X POST https://mobileproxy.app/api/v1/subscriptions \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" -d '{ "name": "Paris SFR" }'
# → { "id": "sub_760c1fc8ddab", "status": "unpaired", "device": null, … }

# Pair (or swap) a phone into it
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/pair \
     -H "Authorization: Bearer mpx_live_…"
# → { "subscription_id": "sub_760c1fc8ddab", "mode": "new",
#     "pairing": { "pin": "483-119-702", "expires_at": "…" }, … }

Obtenha, atualize ou cancele uma subscrição. POST altera o nome, uma description livre (máx. 200 caracteres, null limpa-a), a preferência wifi_split (colocada em fila para o telefone emparelhado, aplicada no próximo poll ~25 s) ou shared_speed_kbps — como a velocidade do dispositivo é dividida entre os seus proxies. -1 (recomendado) partilha-a automaticamente: o plano de controlo mede a velocidade real do dispositivo a partir do throughput em direto (rebalanceamento ~3 s), os proxies ocupados ao mesmo tempo convergem para partes iguais dela e um proxy a trabalhar sozinho obtém velocidade total. Um valor > 0 divide esse total fixo do dispositivo da mesma forma. Os valores speed_limit_kbps por proxy são mantidos mas não aplicados enquanto qualquer um destes estiver ativo; 0 desliga a partilha. DELETE desmonta o seu dispositivo e proxies, liberta as portas do gateway e apaga o histórico do slot — irreversível:

# Fetch one subscription
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID \
     -H "Authorization: Bearer mpx_live_…"

# Rename / describe / set Wi-Fi split / share the device's speed equally (auto)
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Paris SFR", "description": "Client X — farm slot 2", "wifi_split": true, "shared_speed_kbps": -1 }'

# Cancel (irreversible)
curl -X DELETE https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID \
     -H "Authorization: Bearer mpx_live_…"
# → { "deleted": true, "id": "sub_760c1fc8ddab" }

Proxies

Um proxy é um endpoint de protocolo único (SOCKS5 ou HTTP) num dispositivo, com a sua própria autenticação, whitelist de IP de origem, limite de velocidade e regras de domínio. Quantos um dispositivo pode servir em simultâneo é um direito do plano (10 no Standard, 20 no Pro) — crie um por cliente ou ferramenta e revogue qualquer um sem tocar nos restantes. Uma criação acima do limite do seu plano devolve 409 proxy_limit_reached.

Crie um proxy — gera um novo utilizador/palavra-passe; a palavra-passe é devolvida em claro uma única vez, aqui. Escolha protocol (socks5 ou http) e opcionalmente passe traffic_limit_bytes para lhe dar um limite rígido de tráfego desde o início:

curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "protocol": "socks5", "traffic_limit_bytes": 5368709120 }'

# → { "id": "acc_5f734b9270e8", "subscription_id": "sub_760c1fc8ddab",
#     "protocol": "socks5",
#     "host": "173.249.36.102", "host_v6": "2a02:c207:2319:6018::1",
#     "port": 30000,
#     "username": "u04c770", "password": "k7Qp2mXe9wZ4",
#     "endpoint": "socks5h://u04c770:[email protected]:30000",
#     "endpoint_ipv6": "socks5h://u04c770:k7Qp2mXe9wZ4@[2a02:c207:2319:6018::1]:30000",
#     "ip_whitelist": [], "speed_limit_kbps": 0,
#     "domain_mode": "none", "domain_rules": [],
#     "status": "active", "traffic_limit_bytes": 5368709120, "bytes_used": 0,
#     "over_limit": false, "created_at": "…" }

Edite a política de um proxy — modo de autenticação, whitelist de IP, limite de velocidade e regras de domínio, aplicados em direto ao gateway (protocol é fixo — em vez disso, apague e recrie):

curl -X PATCH \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID \
  -H "Authorization: Bearer mpx_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "speed_limit_kbps": 2000,
        "domain_mode": "whitelist", "domain_rules": ["api.example.com"] }'

Liste os proxies — num dispositivo, ou todos os proxies em toda a conta:

# One device
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies \
     -H "Authorization: Bearer mpx_live_…"

# Account-wide
curl https://mobileproxy.app/api/v1/proxies \
     -H "Authorization: Bearer mpx_live_…"
# → { "proxies": [ { …Proxy… }, … ] }

Revogue um proxy — para de imediato esse listener; todos os outros proxies do dispositivo continuam a funcionar:

curl -X DELETE \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID \
  -H "Authorization: Bearer mpx_live_…"
# → { "deleted": true, "id": "acc_5f734b9270e8" }

Limites de utilização por proxy e expiração

Dê a qualquer proxy um limite de utilização — ideal quando revende acessos e mede cada cliente por uma franquia de dados. Defina-o ou altere-o a qualquer momento (0 limpa-o), na criação, via PATCH, ou com o endpoint dedicado abaixo. Quando bytes_used atinge o limite, o proxy é bloqueado: mantém a porta e as credenciais mas recusa todos os pedidos, e over_limit passa a true. Suba o limite acima do valor usado — ou limpe-o — e o proxy retoma de imediato, mesmo endpoint, sem reconfiguração. A listagem de proxies também reporta o traffic_limit_bytes, o bytes_used em direto e o over_limit de cada um.

curl -X POST \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID/limit \
  -H "Authorization: Bearer mpx_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "traffic_limit_bytes": 10737418240 }'   # 10 GB — or 0 to remove
# → { "proxy_id": "acc_5f734b9270e8", "subscription_id": "sub_760c1fc8ddab",
#     "traffic_limit_bytes": 10737418240, "over_limit": false }

Expiração por tempo — dê a um proxy um instante expires_at (ISO 8601, no futuro) na criação ou via PATCH; null limpa uma expiração pendente. Nesse momento, o proxy é retirado — de forma permanente, ao contrário do bloqueio reversível do limite de utilização. Para renovar um cliente, crie um novo proxy (nova porta e credenciais). Perfeito para vender passes de dia/semana:

# A proxy that stops serving in 7 days
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "protocol": "socks5", "expires_at": "2026-07-13T09:00:00Z" }'

# Extend or clear it later
curl -X PATCH \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID \
  -H "Authorization: Bearer mpx_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "expires_at": "2026-07-20T09:00:00Z" }'   # or null to remove

Configurações VPN (WireGuard e OpenVPN)

Transforme qualquer proxy numa VPN de dispositivo completo. Cada configuração é um ficheiro WireGuard (.conf) ou OpenVPN (.ovpn) que encaminha um dispositivo inteiro — telefone, portátil, router — através do IP do operador móvel desse proxy. Um proxy pode ter 1 de cada tipo — uma configuração WireGuard e uma OpenVPN. As configurações exigem um proxy SOCKS5 + utilizador/palavra-passe para que o gateway se possa autenticar nele. Criar uma configuração exige o add-on VPN na encomenda do dispositivo (403 vpn_addon_required sem ele) — as configurações existentes permanecem listadas, transferíveis e revogáveis.

# Create a WireGuard config on a proxy
curl -X POST \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID/vpn-configs \
  -H "Authorization: Bearer mpx_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "wireguard", "name": "My laptop" }'
# → { "id": "vpn_9f2c1a0b7e", "kind": "wireguard", "client_ip": "10.77.0.2",
#     "config_text": "[Interface]\nPrivateKey = …\n[Peer]\n…", … }

# ...or OpenVPN
curl -X POST \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID/vpn-configs \
  -H "Authorization: Bearer mpx_live_…" -H "Content-Type: application/json" \
  -d '{ "kind": "openvpn" }'

# List a proxy's configs (metadata + per-kind usage vs the 1-per-kind cap)
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID/vpn-configs \
     -H "Authorization: Bearer mpx_live_…"

# Re-download the file straight to disk
curl -OJ \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID/vpn-configs/vpn_9f2c1a0b7e/file \
  -H "Authorization: Bearer mpx_live_…"

# Revoke (drops the WireGuard peer / OpenVPN cert and kills any live session)
curl -X DELETE \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID/vpn-configs/vpn_9f2c1a0b7e \
  -H "Authorization: Bearer mpx_live_…"

Use o ficheiro como habitual: wg-quick up ./mpx-9f2c1a0b.conf para WireGuard, ou importe o .ovpn em qualquer cliente OpenVPN. Todo o tráfego do dispositivo sai então pelo IP do operador do telefone, e rodar o IP desse proxy roda também a saída da VPN.

Rotation de IP

A rotation pede ao operador um novo IP. É por dispositivo — todos os proxies do dispositivo recebem o novo IP — colocada em fila para o telefone e aplicada dentro de um ciclo de poll (~25 s).

Rodar agora — coloque em fila uma rotation pontual:

curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/change-ip \
     -H "Authorization: Bearer mpx_live_…"

# → { "status": "rotating", "subscription_id": "sub_760c1fc8ddab",
#     "command_id": "cmd_a41b",
#     "note": "IP rotation on mobile networks is best-effort; …" }

Rotation de IP único — passe unique: true para continuar a rodar até o IP de saída ser um não visto nos últimos window_min minutos do histórico de IP desta subscrição (padrão 60, máx. 1440), tentando até max_attempts vezes (padrão 3, máx. 5). Cada tentativa custa um ciclo completo de rotation (~30–90 s); consulte a variante GET para o progresso. Os operadores podem legitimamente reemitir um IP, por isso exhausted é um resultado honesto possível:

curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/change-ip \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "unique": true, "window_min": 60, "max_attempts": 3 }'
# → { "status": "rotating", "request_id": "rr_18d2c4", "command_id": "cmd_a41b",
#     "unique": { "window_min": 60, "max_attempts": 3 }, … }

# Poll for the outcome (active | succeeded | exhausted | superseded | expired)
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/change-ip \
     -H "Authorization: Bearer mpx_live_…"
# → { "request_id": "rr_18d2c4", "status": "succeeded",
#     "attempts_used": 2, "attempts_max": 3, "window_min": 60,
#     "started_ip": "77.136.66.63", "result_ip": "77.136.67.101", … }

Links de rotation — um URL com token que roda o IP deste dispositivo quando acedido, sem cabeçalho de autenticação (o segredo é o token). Cole-o em qualquer ferramenta que suporte um "rotation URL". Liste, crie e revogue-os:

# List rotation links
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation-links \
     -H "Authorization: Bearer mpx_live_…"
# → { "rotation_links": [ { "token": "rk_9f2c81d4e7",
#       "url": "https://mobileproxy.app/rotate/rk_9f2c81d4e7", "created_at": "…" } ] }

# Create one
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation-links \
     -H "Authorization: Bearer mpx_live_…"
# → { "token": "rk_9f2c81d4e7", "url": "https://mobileproxy.app/rotate/rk_9f2c81d4e7" }

# Revoke one
curl -X DELETE https://mobileproxy.app/api/v1/rotation-links/ROTATION_TOKEN \
     -H "Authorization: Bearer mpx_live_…"
# → { "deleted": true, "token": "rk_9f2c81d4e7" }

Rotation agendada (temporizada) — defina um intervalo de rotation automática em minutos (0 desliga-a; máx. 1440). Persiste como rotation_interval_min no dispositivo e envia um comando set_rotation_interval que o telefone aplica no próximo poll, por isso re-liga nessa cadência por conta própria:

# Read the current settings
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation \
     -H "Authorization: Bearer mpx_live_…"
# → { "subscription_id": "sub_760c1fc8ddab", "interval_minutes": 0,
#     "airplane_seconds": 5, "stale_ip_alert_minutes": 0 }

# Rotate automatically every 15 minutes
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "interval_minutes": 15 }'
# → { "status": "set", "subscription_id": "sub_760c1fc8ddab",
#     "interval_minutes": 15, "airplane_seconds": 5,
#     "stale_ip_alert_minutes": 0, "command_id": "cmd_a41b" }

Tempo em modo de voo — quanto tempo o telefone mantém o modo de voo LIGADO durante cada mudança de IP (airplane_seconds, 3–60, padrão 5). Alguns operadores só libertam o aluguer antigo após uma espera mais longa; suba este valor se as rotations continuarem a devolver o mesmo IP. Aplica-se igualmente a rotations agendadas, do dashboard e da API:

curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "airplane_seconds": 20 }'
# → { "status": "set", "subscription_id": "sub_760c1fc8ddab",
#     "interval_minutes": 15, "airplane_seconds": 20,
#     "stale_ip_alert_minutes": 0, "command_id": "cmd_b52c" }

DNS personalizado — os resolvers que o telefone usa para consultas de domínio via proxy (até 3 literais de IP; o telefone aplica o primeiro e re-liga o seu túnel). Uma lista vazia restaura o DNS padrão do operador:

# Read
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/dns \
     -H "Authorization: Bearer mpx_live_…"
# → { "subscription_id": "sub_760c1fc8ddab", "dns_servers": [] }

# Set (and later send [] to go back to carrier DNS)
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/dns \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "dns_servers": ["1.1.1.1", "8.8.8.8"] }'
# → { "status": "set", "subscription_id": "sub_760c1fc8ddab",
#     "dns_servers": ["1.1.1.1", "8.8.8.8"], "command_id": "cmd_c63d" }

Monitorização

Histórico de IP de saída — IPs de saída recentes reportados pelo telefone, sem duplicados (uma nova linha só quando o IP realmente mudou). A forma fiável de verificar que uma rotation aconteceu:

curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/ip-history \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscription_id": "sub_760c1fc8ddab", "ip_history": [
#     { "ip": "77.136.66.63", "carrier": "SFR", "ts": "…" }, … ] }

Parâmetros de consulta opcionais: from/to (ISO 8601) delimitam a janela, limit limita as entradas (padrão 50, máx. 500), e group=day devolve antes contagens de mudanças por dia — passe tz como o seu desvio UTC em minutos para que os dias sejam agrupados no seu fuso horário. É isto que alimenta o calendário de histórico de IP do dashboard:

# Entries for one day
curl "https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/ip-history?from=2026-07-04T22:00:00Z&to=2026-07-05T22:00:00Z&limit=500" \
     -H "Authorization: Bearer mpx_live_…"

# Per-day counts for a month (tz = minutes east of UTC, e.g. 120 for CEST)
curl "https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/ip-history?group=day&tz=120&from=2026-06-30T22:00:00Z&to=2026-07-31T22:00:00Z" \
     -H "Authorization: Bearer mpx_live_…"
# → { "subscription_id": "sub_760c1fc8ddab", "days": [
#     { "day": "2026-07-03", "changes": 9 }, { "day": "2026-07-05", "changes": 2 } ] }

Alertas de IP — o servidor vigia a sua frota (~a cada 60 s) e abre um alerta quando algo precisa de atenção: stale_ip quando um dispositivo está online mas o seu IP de saída não muda há mais tempo do que o limiar da subscrição (defina stale_ip_alert_minutes em /rotation; 0 = desligado, 2–10080), e duplicate_ip quando dois dos seus dispositivos reportam o mesmo IP de saída (o NAT do operador pode atribuir a dois SIM um só endereço — rode um para os separar). Os alertas resolvem-se automaticamente quando a condição desaparece; também aparecem no sino de alertas do dashboard:

# Turn on stale-IP alerts: warn after 60 min without an IP change
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "stale_ip_alert_minutes": 60 }'

# Poll open alerts (feed this to your own monitoring)
curl https://mobileproxy.app/api/v1/alerts \
     -H "Authorization: Bearer mpx_live_…"
# → { "alerts": [
#     { "id": "42", "sub_id": "sub_760c1fc8ddab", "sub_name": "Galaxy S8",
#       "kind": "stale_ip",
#       "message": "IP unchanged for 75 min (alert threshold 60 min) — still 77.136.66.44",
#       "detail": { "ip": "77.136.66.44", "age_min": 75, "threshold_min": 60 },
#       "created_at": "…", "resolved_at": null, "seen_at": null },
#     { "id": "41", "sub_id": "sub_9d8e7f6a5b4c", "sub_name": "Galaxy A32",
#       "kind": "duplicate_ip",
#       "message": "Exit IP 77.136.67.33 is also used by “Galaxy S8” — rotate one device to separate them",
#       "detail": { "ip": "77.136.67.33",
#                   "shared_with": [ { "sub_id": "sub_760c1fc8ddab", "name": "Galaxy S8" } ] },
#       "created_at": "…", "resolved_at": null, "seen_at": null } ],
#     "unseen": 2 }

# Include resolved history; filter to one subscription
curl "https://mobileproxy.app/api/v1/alerts?status=all&subscription=SUBSCRIPTION_ID" \
     -H "Authorization: Bearer mpx_live_…"

# Reset the dashboard's unseen badge (never resolves anything)
curl -X POST https://mobileproxy.app/api/v1/alerts/seen \
     -H "Authorization: Bearer mpx_live_…"
# → { "status": "ok", "marked": 2 }

Tráfego de um dispositivo — bytes contados no gateway, divididos por proxy. Útil para faturar clientes a quem revende:

curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/traffic \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscription_id": "sub_760c1fc8ddab",
#     "bytes_sent": 10485760, "bytes_recv": 262144000, "bytes_total": 272629760,
#     "per_proxy": [ { "proxy_id": "acc_5f734b9270e8",
#                      "bytes_sent": 10485760, "bytes_recv": 262144000 } ] }

Detalhe de tráfego diário — bytes enviados/recebidos por dia, a partir de amostras de resolução por minuto mantidas na camada web, para que a série sobreviva a trocas de dispositivo e à retirada de proxies. data_since marca a amostra mais antiga — os dias anteriores não têm dados, o que não é o mesmo que tráfego zero. Passe tz (o seu desvio UTC em minutos) para que os dias sejam agrupados no seu fuso horário; janelas até 92 dias:

curl "https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/traffic/by-day?tz=120" \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscription_id": "sub_760c1fc8ddab", "tz": 120, "data_since": "…",
#     "days": [ { "day": "2026-07-06", "bytes_sent": 10485760,
#                 "bytes_recv": 262144000, "bytes_total": 272629760 } ],
#     "total": { "bytes_sent": 10485760, "bytes_recv": 262144000,
#                "bytes_total": 272629760 } }

Uptime diário — segundos ativos/inativos por dia, agregados do registo de heartbeat do dispositivo (unificado entre trocas de dispositivo). Mede a vivacidade do heartbeat do dispositivo (cadência ~25 s, limiar de intervalo ~90 s), não a usabilidade ponta a ponta do túnel. current é o estado neste momento; uptime_pct cobre a parte observada de cada dia:

curl "https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/uptime?tz=120" \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscription_id": "sub_760c1fc8ddab", "tz": 120, "current": "up",
#     "data_since": "…",
#     "days": [ { "day": "2026-07-06", "up_seconds": 31547,
#                 "down_seconds": 253, "uptime_pct": 99.2 } ] }

Utilização de toda a conta — um resumo agregado de todos os dispositivos:

curl https://mobileproxy.app/api/v1/usage/summary \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscriptions": 3, "proxies": 5,
#     "bytes_sent": 31457280, "bytes_recv": 786432000, "bytes_total": 817889280 }

SMS / OTP

SMS recebidos — mensagens de entrada no SIM deste telefone, mais recentes primeiro. Útil para ler códigos de verificação únicos (OTP) em telefones que possui. Depende da permissão opcional de receção de SMS da app; se esta foi recusada no dispositivo, a lista fica vazia:

curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/sms \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscription_id": "sub_760c1fc8ddab", "messages": [
#     { "id": "1042", "sender": "+15550101",
#       "body": "Your verification code is 314159",
#       "received_at": "2026-07-05T14:12:00.000Z" }, … ] }

Servidores

Localizações de gateway — as localizações a partir das quais os seus proxies são servidos:

curl https://mobileproxy.app/api/v1/servers/locations \
     -H "Authorization: Bearer mpx_live_…"

# → { "locations": [ { "id": "eu-de-1", "host": "173.249.36.102",
#       "region": "EU · Germany (Frankfurt)", "country": "DE",
#       "protocols": ["socks5"], "pool": "mobile" } ] }

Tokens de API

Liste, crie e revogue tokens de API. O segredo de um token recém-criado é mostrado uma única vez — guarde-o de imediato; nunca mais é recuperável. A revogação tem efeito imediato:

# List (metadata only — never the secret)
curl https://mobileproxy.app/api/v1/tokens \
     -H "Authorization: Bearer mpx_live_…"
# → { "tokens": [ { "id": "tk_51ad", "name": "storefront",
#       "prefix": "mpx_live_9f2c", "created_at": "…", "last_used_at": "…" } ] }

# Create (secret shown once)
curl -X POST https://mobileproxy.app/api/v1/tokens \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "name": "storefront" }'
# → { "id": "tk_51ad", "name": "storefront",
#     "token": "mpx_live_9f2c81d4e7…", "prefix": "mpx_live_9f2c",
#     "scope_subscription_id": null, "readonly": false,
#     "note": "Store this token now — it will not be shown again." }

# Revoke
curl -X DELETE https://mobileproxy.app/api/v1/tokens/TOKEN_ID \
     -H "Authorization: Bearer mpx_live_…"
# → { "deleted": true, "id": "tk_51ad" }

Chaves com âmbito e só de leitura

Delegue acesso sem partilhar a sua conta. Passe subscription_id para limitar um token a uma única subscrição, e readonly: true para o restringir a pedidos GET. Um token com âmbito só alcança os próprios endpoints dessa subscrição (mais /me); um token só de leitura é recusado em qualquer escrita. Ambos são restrições sobrepostas à sua conta — uma chave com âmbito nunca alcança os dados de outra conta.

# A read-only key for ONE subscription — safe to hand a teammate or a monitor
curl -X POST https://mobileproxy.app/api/v1/tokens \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "name": "customer-42",
           "subscription_id": "sub_760c1fc8ddab",
           "readonly": true }'
# → { …, "scope_subscription_id": "sub_760c1fc8ddab", "readonly": true }

# With that key: a GET on its own subscription works…
curl https://mobileproxy.app/api/v1/subscriptions/sub_760c1fc8ddab/traffic \
     -H "Authorization: Bearer mpx_live_scoped…"     # 200

# …but another subscription, the account-wide list, or any write is refused.
curl -X POST https://mobileproxy.app/api/v1/subscriptions/sub_760c1fc8ddab/change-ip \
     -H "Authorization: Bearer mpx_live_scoped…"     # 401 (read-only)