Sovereign
Dashboard
OpenAPI 3.1 Specification

Management API Reference

Contrato único del plano de gestión para Sovereign Proxy Network. Consumible por el dashboard frontend, SDKs oficiales (TypeScript, Python, Go) y agentes de automatización.

Base URL: https://api.sovereignip.com·Local: http://127.0.0.1:4000

Interactive API Playground ("Try it out")

Demo token habilitado para pruebas

Interactive API Playground ("Try it out")

OpenAPI 3.1

Retorna el desglose de gigabytes consumidos por cada producto (Residential, Mobile, ISP, Datacenter). No expone precios directos respetando la separación de boundaries.

Query Parameters

accountId (string): ID de la cuenta a consultar (por defecto la cuenta del token)

Client Code Example
curl -X GET "https://api.sovereignip.com/v1/usage" \
  -H "Authorization: Bearer ${SOVEREIGN_API_KEY}"
Live Response

Hacé click en Execute Request para enviar la petición a la Management API o evaluar la simulación en vivo.

Totalmente funcional en frontend con contrato OpenAPI 3.1.

Anti-SSRF fail-closed guardContract: management-api.yaml

Endpoints de la Management API

Especificación completa de operaciones extraída directamente de packages/contracts/openapi/management-api.yaml.

GET/v1/usage
Usage & Metrics

Resumen agregado de consumo de tráfico

Retorna el desglose de gigabytes consumidos por cada producto (Residential, Mobile, ISP, Datacenter). No expone precios directos respetando la separación de boundaries.

Parameters
NameInTypeDescription
accountIdquerystringID de la cuenta a consultar (por defecto la cuenta del token)
Sample Response (200 Agregado de bytes consumidos por producto de proxy)
{
  "accountId": "acme",
  "period": "Oct 2026",
  "totalGb": 209.3,
  "usage": [
    {
      "label": "Residential",
      "gb": 128.4,
      "width": "72%",
      "rateUsd": 4.5,
      "poolHealth": "99 score · 42ms"
    },
    {
      "label": "Mobile",
      "gb": 22.1,
      "width": "28%",
      "rateUsd": 8.5,
      "poolHealth": "96 score · 58ms"
    },
    {
      "label": "ISP",
      "gb": 18.6,
      "width": "22%",
      "rateUsd": 2.4,
      "poolHealth": "98 score · 31ms"
    },
    {
      "label": "Datacenter",
      "gb": 40.2,
      "width": "40%",
      "rateUsd": 0.9,
      "poolHealth": "100 score · 14ms"
    }
  ]
}
POST/v1/credentials
Credentials & Proxy

Crear credencial proxy con targeting

Genera una cadena de autenticación proxy con reglas de targeting (país, ciudad, ASN, sesión sticky y carrier celular).

Sample Response (201 Credencial proxy emitida exitosamente)
{
  "id": "cred_live_992",
  "username": "acme-subuser-qabot-product-residential-mode-sticky-country-us-city-newyork-asn-as7922-session-sess42-sesstime-30",
  "password": "demo-secret-token",
  "proxyHost": "gateway.sovereignip.com",
  "proxyPort": 9000,
  "proxyLine": "gateway.sovereignip.com:9000:acme-subuser-qabot-product-residential-mode-sticky-country-us-session-sess42-sesstime-30:demo-secret-token",
  "createdAt": "2026-10-26T16:00:00Z"
}
GET/v1/credentials
Credentials & Proxy

Listar credenciales proxy activas

Obtiene todas las credenciales generadas y vigentes asignadas a la cuenta u organización.

Sample Response (200 Lista de credenciales)
[
  {
    "id": "cred_live_992",
    "subUser": "qa-bot",
    "product": "residential",
    "mode": "sticky",
    "country": "us",
    "createdAt": "2026-10-26T14:20:00Z"
  },
  {
    "id": "cred_live_991",
    "subUser": "research",
    "product": "mobile",
    "mode": "rotating",
    "country": "de",
    "createdAt": "2026-10-26T12:00:00Z"
  }
]
GET/v1/sub-users
Sub-Users & Quotas

Listar sub-usuarios y estado de cuotas

Consulta sub-usuarios creados para equipos de crawling, límites asignados en bytes y consumo acumulado.

Sample Response (200 Sub-usuarios registrados)
{
  "accountId": "acme",
  "subUsers": [
    {
      "name": "qa-bot",
      "cap": "40 GB",
      "used": "12.4 GB",
      "status": "Active"
    },
    {
      "name": "research",
      "cap": "80 GB",
      "used": "61.0 GB",
      "status": "Active"
    },
    {
      "name": "staging",
      "cap": "10 GB",
      "used": "10.0 GB",
      "status": "Capped"
    }
  ]
}
GET/v1/balance
Billing & Balance

Consultar saldo y balance de créditos prepago

Consulta el ledger contable de doble entrada (TigerBeetle), saldo disponible sin vencimiento, retenciones pendientes y créditos totales.

Sample Response (200 Estado del ledger prepago)
{
  "accountId": "acme",
  "availableFormatted": "$125.00",
  "availableCents": 12500,
  "creditsPostedCents": 15000,
  "debitsPostedCents": 2000,
  "debitsPendingCents": 500,
  "currency": "usd",
  "invariantStatus": "debits_must_not_exceed_credits (Strict 0 negative)"
}
POST/v1/gateway/simulate
Unlocker & Gateway

Simular evaluación de pipeline Anti-SSRF y salida

Verifica si una URL o IP de destino es permitida por el guardián Anti-SSRF de Sovereign (bloquea RFC1918, CGNAT, Cloud Metadata y dominios gubernamentales) y cuál nodo de salida resolvería la conexión.

Sample Response (200 Destino permitido hacia Internet público)
{
  "allowed": true,
  "status": 200,
  "egressReason": "ALLOW_PUBLIC_UNICAST",
  "quotaStatus": "Active",
  "assignedNode": "exit-us-01 (tuxly/frp)",
  "healthScore": 99,
  "matchLevel": "exact",
  "cloudEventType": "sovereign.traffic.bytes (CloudEvents 1.0)"
}
POST/v1/unlock
Unlocker & Gateway

Web Unlocker API (URL -> HTML renderizado)

Desbloquea páginas protegidas por Cloudflare Turnstile, DataDome o Akamai BMP. Conecta con Scraping Browser y perfiles de evasión stealth en tiempo real.

Sample Response (200 Contenido desbloqueado con éxito)
{
  "url": "https://example.com/products",
  "allowed": true,
  "challengeDetected": "Cloudflare Turnstile",
  "attempts": 2,
  "profileUsed": "chrome-128-macos (sec-ch-ua / residential egress)",
  "statusCode": 200,
  "htmlPreview": "<!DOCTYPE html><html><head><title>Products Catalog</title></head><body>...</body></html>"
}