Sign In
public documentation

API Reference

Automate proxy purchases and renewals.

Manage keys
Reference
en

Introduction

Programmatic interface for listing plans, viewing subscriptions, purchasing new proxies, renewing active subscriptions, and configuring automatic IP rotation.

The API uses a single endpoint: /api/proxy. For GET operations, pass op in the query string; for POST operations, pass op in the JSON body.

Quickstart

Create an API key in Dashboard -> API Keys and send it in the header of every request.

BASE="https://your-domain.com"
API_KEY="rk_your_long_lived_api_key"

All IDs are lowercase alphanumeric values.

Trial issuance via POST /api/proxy with {"op":"trial","planId":"..."} is available only for selected API keys. Contact support to enable this capability for your key. Trial usage is monitored and may be limited or disabled in case of abuse.

Available plans

Returns active proxy plans available to the API key owner.

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=plans"
{
  "ok": true,
  "plans": [
    {
      "id": "k17m3q5v7n9p1r2t4w6y8z0a",
      "connectionType": "private",
      "durationMs": 2592000000,
      "priceAmountCents": 1200,
      "popular": true,
      "network": {
        "name": "NL-AMS",
        "city": "Amsterdam",
        "country": "NL",
        "networkType": "mobile"
      }
    }
  ]
}

Active subscriptions

Returns your subscriptions, including credentials, protocol URLs, and IP rotation data.

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=subscriptions"
{
  "ok": true,
  "subscriptions": [
    {
      "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1762592000000,
      "userNote": "Client A",
      "rotationPolicy": 10,
      "label": "12001 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam",
      "credentials": {
        "username": "u_6k8s9d",
        "password": "p_2n4m6q"
      },
      "protocols": {
        "http": "http://u_6k8s9d:p_2n4m6q@proxy.example.com:12001",
        "socks5": "socks5://u_6k8s9d:p_2n4m6q@proxy.example.com:12001",
        "vless": "vless://...",
        "shadowsocks": "ss://..."
      },
      "rotate": {
        "rotatePath": "/r/abcd1234",
        "available": true
      }
    }
  ]
}

Renewal plans

Returns plans that are eligible for renewing a specific subscription.

SUB_ID="j97b2f6m1k4n8p3r5t7v9x0z"

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=renewal-plans&subscriptionId=$SUB_ID"
{
  "ok": true,
  "renewalPlans": [
    {
      "id": "k17m3q5v7n9p1r2t4w6y8z0a",
      "connectionType": "private",
      "durationMs": 2592000000,
      "priceAmountCents": 1200
    }
  ]
}

Available networks

Returns networks available for switching a specific subscription.

SUB_ID="j97b2f6m1k4n8p3r5t7v9x0z"

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=available-networks&subscriptionId=$SUB_ID"
{
  "ok": true,
  "networks": [
    {
      "id": "b1c2d3e4f5g6h7j8k9m0n1p2",
      "networkLabel": "DE-BER Berlin",
      "country": "DE"
    }
  ]
}

Use networks[].id as targetNetwork in the switch-network request.

Purchase subscription

Creates one or more new subscriptions from your balance using the selected plan.

Optional fields:

  • couponCode: applies a valid coupon to the purchase.
  • repeatCount: positive integer, defaults to 1; multiplies the duration and price of each created subscription.
  • quantity: positive integer, defaults to 1; creates multiple subscriptions in a single request.
{
  "op": "purchase",
  "planId": "k17m3q5v7n9p1r2t4w6y8z0a",
  "couponCode": "MYCODE",
  "repeatCount": 3,
  "quantity": 2
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"purchase","planId":"k17m3q5v7n9p1r2t4w6y8z0a","repeatCount":3,"quantity":2}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "subscriptionIds": [
    "j97b2f6m1k4n8p3r5t7v9x0z",
    "n38k2f6m1k4n8p3r5t7v9x0z"
  ],
  "subscriptions": [
    {
      "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1767776000000,
      "label": "12001 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam"
    },
    {
      "subscriptionId": "n38k2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1767776000000,
      "label": "12002 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam"
    }
  ]
}

If a single subscription is created, the gateway may return subscription instead of subscriptions. Items in subscription/subscriptions use the same shape as GET /api/proxy?op=subscriptions.

Renew subscription

Renews an existing subscription with an eligible renewal plan.

Optional fields:

  • couponCode: applies a valid coupon to the renewal.
  • repeatCount: positive integer, defaults to 1; multiplies both renewal duration and price.
{
  "op": "renew",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "planId": "q2w4e6r8t0y2u4i6o8p0a2s4",
  "couponCode": "MYCODE",
  "repeatCount": 3
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"renew","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","planId":"q2w4e6r8t0y2u4i6o8p0a2s4","repeatCount":3}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "endAt": 1770368000000
}

Change connection credentials

Regenerates connection credentials for an active subscription owned by the authenticated user (JWT) or API key owner.

{
  "op": "change-credentials",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z"
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"change-credentials","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z"}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "password": "q7N3x9Lp",
  "vpn": "7f3d9d4a-8b9f-4a93-9f55-2d5e3b7f1c24"
}

Set auto-rotation policy

Configures automatic IP rotation for an active subscription. Available only for connections with "rotate": { "available": true }.

Allowed values for rotationPolicy: 0, 5, 10, 15, 30, 60 minutes. Use 0 to disable auto-rotation.

{
  "op": "set-rotation-policy",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "rotationPolicy": 10
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"set-rotation-policy","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","rotationPolicy":10}' 
  "$BASE/api/proxy"
{
  "ok": true
}

Change connection network

Moves an active subscription to another available network.

{
  "op": "switch-network",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "targetNetwork": "b1c2d3e4f5g6h7j8k9m0n1p2"
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"switch-network","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","targetNetwork":"b1c2d3e4f5g6h7j8k9m0n1p2"}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "subscription": {
    "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
    "status": "active",
    "activeUntil": 1762592000000,
    "userNote": "Client A",
    "rotationPolicy": 10,
    "label": "12001 - DE - Private",
    "networkLabel": "DE-BER Berlin",
    "credentials": {
      "username": "u_6k8s9d",
      "password": "p_2n4m6q"
    },
    "protocols": {
      "http": "http://u_6k8s9d:p_2n4m6q@proxy.example.com:12001",
      "socks5": "socks5://u_6k8s9d:p_2n4m6q@proxy.example.com:12001",
      "vless": "vless://...",
      "shadowsocks": "ss://..."
    },
    "rotate": {
      "rotatePath": "/r/abcd1234",
      "available": true
    }
  }
}

Gateway errors

  • 400 Invalid JSON body
  • 400 Body must be an object
  • 400 Missing or unknown op
  • 400 Missing or invalid planId/subscriptionId/targetNetwork/rotationPolicy
  • 400 Invalid repeatCount or quantity
  • 401 Unauthorized
  • 402 Insufficient balance
  • 403 Forbidden
  • 404 Subscription not found
  • 409 Rotation policy not available for this subscription
  • 409 Sold out, inactive plan/network, or invalid subscription state
  • 429 Rate limited
  • 500 Internal error