Proxies, from code.

GET/catalog

Prices, allowed values and current datacenter stock. No key needed.

curl https://ghostconnect.io/api/v1/catalog

{
  "ok": true,
  "data": {
    "currency": "USD",
    "pays_from": "balance",
    "products": {
      "datacenter": { "price_per_ip_per_31_days_usd": "1.79", "days": [7, 14, 31, ...], "stock": { "ipv4": { "us": 120, ... } } },
      "residential": { "price_per_gb_usd": "2.99", ... },
      "rotating": { ... },
      "isp": { "use_cases": { "us": ["pkc", "ticket", ...] }, ... }
    }
  }
}

GET/account

The account this key belongs to and its balance.

curl -H "Authorization: Bearer $GT_KEY" https://ghostconnect.io/api/v1/account

{
  "ok": true,
  "data": { "id": 48, "balance_usd": "133.68", "created_at": 1789350000, "api_keys": 1 }
}

POST/quote

The exact price of an order, renewal or top-up, without buying it. Takes kind plus the same fields as the matching purchase; renewals and top-ups also take the proxy id.

curl -X POST -H "Authorization: Bearer $GT_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"isp","country":"us","months":1,"quantity":2}' \
  https://ghostconnect.io/api/v1/quote

{
  "ok": true,
  "data": {
    "kind": "isp",
    "description": "ISP x2, US, 1 month",
    "amount_usd": "10.00",
    "lines": { "Country": "United States", "Use case": "Social media", "Term": "1 month", "IPs": 2 },
    "balance_usd": "133.68",
    "balance_covers": true
  }
}

POST/orders

Buy proxies. Pays from the balance and returns 201 with the invoice and the new proxies, credentials included, in the same response. Send an Idempotency-Key.

curl -X POST -H "Authorization: Bearer $GT_KEY" \
  -H "Idempotency-Key: order-dc-0001" \
  -H "Content-Type: application/json" \
  -d '{"type":"datacenter","country":"us","ip_type":"ipv4","days":31,"quantity":2}' \
  https://ghostconnect.io/api/v1/orders

{
  "ok": true,
  "data": {
    "invoice": {
      "id": "d3z0sya3", "type": "proxy_datacenter_create",
      "description": "Datacenter IPv4 x2, US, 31 days", "amount_usd": "3.58",
      "payment_method": "balance", "status": "completed",
      "proxy_type": "datacenter", "proxy_id": "k2m9x4qa",
      "created_at": 1789350000, "paid_at": 1789350000, "completed_at": 1789350003
    },
    "proxies": [
      {
        "id": "k2m9x4qa", "type": "datacenter", "created_at": 1789350003,
        "country": "us", "ip_type": "ipv4", "ip": "203.0.113.121",
        "port_http": 10242, "port_socks5": 10243,
        "username": "dxq8m2p", "password": "Zk4pQ9wLr2mT7c",
        "allowlist": [], "expires_at": 1792028403,
        "auto_renew": { "enabled": false, "days": 31 }
      },
      { "id": "p7c1v0ne", ... }
    ],
    "balance_usd": "130.10"
  }
}

Residential proxies come back with a host, credentials and bandwidth in GB, three decimals: total_gb, used_gb and remaining_gb, plus synced_at, when that figure was last read from the network. Rotating proxies come back with host, port, threads and credentials (HTTP only); the allowlist is optional. ISP orders come back as one object with an ips array.

{
  "id": "obcl4126", "type": "residential", "created_at": 1789350000,
  "host": "residential.ghostconnect.io", "port_http": 1080, "port_socks5": 1081,
  "username": "rJxYKRe2U", "password": "Yxa5WGCUkvP9km",
  "bandwidth": { "total_gb": 10, "used_gb": 0.257, "remaining_gb": 9.743 },
  "allowlist": [], "expires_at": null, "synced_at": 1789353600
}

A proxy id is the 8-character lowercase id in these responses, the same one the dashboard shows. An id of any other shape is answered with a 404 that says so.

GET/proxies

Every proxy on the account, oldest first, in the same shape as orders returns. Filter with ?type=. GET /proxies/{type}/{id} returns one as {"proxy": ...}; for ISP, the id of any IP in an order returns the whole order.

curl -H "Authorization: Bearer $GT_KEY" "https://ghostconnect.io/api/v1/proxies?type=residential"

POST/proxies/{type}/{id}/renew

Add time to a datacenter, rotating or ISP proxy. An ISP renewal covers every IP in the order. Returns the invoice and the updated proxy. Send an Idempotency-Key: a renewal is not undone by retrying, it is repeated.

curl -X POST -H "Authorization: Bearer $GT_KEY" -H "Idempotency-Key: renew-k2m9x4qa-2026-10" \
  -H "Content-Type: application/json" -d '{"days":31}' \
  https://ghostconnect.io/api/v1/proxies/datacenter/k2m9x4qa/renew

POST/proxies/residential/{id}/topup

Add bandwidth to a residential proxy. Returns the invoice and the updated proxy.

curl -X POST -H "Authorization: Bearer $GT_KEY" -H "Idempotency-Key: topup-0001" \
  -H "Content-Type: application/json" -d '{"gb":10}' \
  https://ghostconnect.io/api/v1/proxies/residential/obcl4126/topup

POST/proxies/{type}/{id}/allowlist

Allow a source address to use a datacenter, residential or rotating proxy without the password. POST /proxies/{type}/{id}/allowlist/remove with the same body removes one. ISP proxies authenticate by username and password only.

curl -X POST -H "Authorization: Bearer $GT_KEY" -H "Content-Type: application/json" \
  -d '{"ip":"198.51.100.7"}' https://ghostconnect.io/api/v1/proxies/rotating/r4t8b2kd/allowlist

POST/proxies/{type}/{id}/auto-renew

Renew automatically from the balance about a day before expiry. For ISP the setting applies to the whole order. On a proxy object auto_renew is an object, {"enabled": false, "days": 31} (months for ISP), not a flag: read enabled, since the object itself is never empty.

curl -X POST -H "Authorization: Bearer $GT_KEY" -H "Content-Type: application/json" \
  -d '{"enabled":true,"period":31}' https://ghostconnect.io/api/v1/proxies/datacenter/k2m9x4qa/auto-renew

POST/proxies/{type}/{id}/reset-credentials

Issue a new username and password for a datacenter, residential or rotating proxy. The old ones stop working at once. No body.

curl -X POST -H "Authorization: Bearer $GT_KEY" https://ghostconnect.io/api/v1/proxies/datacenter/k2m9x4qa/reset-credentials

POST/proxies/{type}/{id}/terminate

Delete a datacenter, residential or rotating proxy for good. It stops working at once, and unused time or bandwidth is not refunded. DELETE /proxies/{type}/{id} does the same. ISP proxies cannot be ended early and return 400 not_supported. If the deletion cannot be confirmed the proxy is kept and you get 502 terminate_failed, so retrying is always safe.

curl -X POST -H "Authorization: Bearer $GT_KEY" https://ghostconnect.io/api/v1/proxies/datacenter/k2m9x4qa/terminate

{
  "ok": true,
  "data": { "message": "Proxy terminated.", "terminated": { "type": "datacenter", "id": "k2m9x4qa" } }
}

POST/proxies/isp/{id}/swap

Replace every IP in an ISP order with new ones. The old IPs stop working at once. Free, once per term; a renewal grants the next. No body. Returns the order with its new ips.

curl -X POST -H "Authorization: Bearer $GT_KEY" https://ghostconnect.io/api/v1/proxies/isp/m4k2v9xa/swap

{
  "ok": true,
  "data": {
    "message": "IPs swapped; the old ones have stopped working. The next free swap comes with the next renewal.",
    "proxy": { "id": "m4k2v9xa", "type": "isp", "ips": [ { "ip": "203.0.113.77", ... }, { "ip": "203.0.113.78", ... } ], ... }
  }
}

GET/proxies/residential/{id}/connection-string

A ready connection with targeting and session appended to the password (that is how the gateway reads them: pass the whole password field as the password). The response carries it as connection (host:port:username:password), as a url, and as its parts. Nothing is stored: generate as many as you need.

curl -H "Authorization: Bearer $GT_KEY" "https://ghostconnect.io/api/v1/proxies/residential/obcl4126/connection-string?session=sticky&minutes=10&country=us&state=new%20york&city=brooklyn"

{
  "ok": true,
  "data": {
    "connection": "residential.ghostconnect.io:1080:rJxYKRe2U:Yxa5WGCUkvP9km_country-US_state-new.york_city-brooklyn_lifetime-10_session-k2p9x7vq",
    "connections": ["...one line per requested quantity..."],
    "format": "host:port:user:pass",
    "url": "http://rJxYKRe2U:Yxa5WGCUkvP9km_country-US_state-new.york_city-brooklyn_lifetime-10_session-k2p9x7vq@residential.ghostconnect.io:1080",
    "host": "residential.ghostconnect.io", "port": 1080,
    "session": "sticky", "protocol": "http", "country": "us", "state": "new.york", "city": "brooklyn", "sticky_minutes": 10
  }
}

GET/proxies/residential/{id}/usage

Bandwidth used over time, the series the dashboard graphs: hourly for the last 24 hours, per two hours for 7 days, daily for 30 days. Each point is a bucket start in Unix seconds (UTC) and the GB used in it, three decimals. Read live from the network on every call, so bandwidth comes back refreshed too.

curl -H "Authorization: Bearer $GT_KEY" "https://ghostconnect.io/api/v1/proxies/residential/obcl4126/usage?window=7d"

{
  "ok": true,
  "data": {
    "proxy_id": "obcl4126", "window": "7d", "bucket_hours": 2,
    "from": 1788746400, "to": 1789351200,
    "points": [
      { "at": 1788746400, "used_gb": 0.012 },
      { "at": 1788753600, "used_gb": 0 },
      { "at": 1788760800, "used_gb": 0.041 },
      "...84 points"
    ],
    "total_gb": 0.257, "peak_gb": 0.041,
    "bandwidth": { "total_gb": 10, "used_gb": 0.257, "remaining_gb": 9.743 },
    "synced_at": 1789351260
  }
}

GET/invoices

The latest 100 invoices, newest first. GET /invoices/{id} returns one, with the proxies it created. Status is one of completed, credited (paid, not deliverable, refunded to the balance), or a payment state for website payments still in progress.

curl -H "Authorization: Bearer $GT_KEY" https://ghostconnect.io/api/v1/invoices