{ "openapi": "3.1.0", "info": { "title": "CleanProxies Reseller API", "version": "1.0.0", "summary": "Buy, deliver and manage CleanProxies ISP, rotating residential and mobile proxies, VPS and bare-metal servers from your own code.", "description": "The CleanProxies Reseller API v1 places orders paid from your CleanProxies account balance and returns the delivered proxies or servers.\n\nAuthenticate with an API key (`Authorization: Bearer cp_live_...` or `x-api-key`). Keys are created in the dashboard (Reseller Program > Settings) and unlock after $500 in deposits or when the account is approved.\n\nBodies are JSON (at most 16 KB; unknown fields are rejected). Money is in integer US cents and times are ISO 8601 UTC. Lists are `{ data, hasMore, nextCursor }`.\n\nEvery response carries `X-Request-Id` and the rate-limit headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; a 429 also carries `Retry-After`.\n\nErrors: UNAUTHENTICATED (401); KEY_REVOKED (401); ACCOUNT_BLOCKED (403); VALIDATION_ERROR (400); INVALID_JSON / UNSUPPORTED_MEDIA_TYPE (400); INVALID_QUANTITY, BELOW_MINIMUM, INVALID_PROVIDER, INVALID_CONFIG_ID, INVALID_OS (400); NOT_SUPPORTED (400); INSUFFICIENT_BALANCE (402); NOT_FOUND (404); SOLD_OUT (409); NOT_RENEWABLE, NOT_TOPUPABLE, SUBSCRIPTION_MANAGED, ORDER_NOT_ACTIVE (409); REQUEST_IN_PROGRESS (409); IDEMPOTENCY_KEY_REQUIRED / IDEMPOTENCY_KEY_INVALID (400); IDEMPOTENCY_MISMATCH (422); RATE_LIMITED, ACTION_COOLDOWN (429); OUTCOME_UNKNOWN (503); UPSTREAM_UNAVAILABLE, STOCK_UNAVAILABLE (503); INTERNAL (500).", "contact": { "name": "CleanProxies support", "email": "help@cleanproxies.com", "url": "https://www.cleanproxies.com/contact?topic=reseller" }, "termsOfService": "https://www.cleanproxies.com/terms-of-service" }, "externalDocs": { "description": "CleanProxies Reseller API documentation", "url": "https://www.cleanproxies.com/reseller-api/docs" }, "servers": [ { "url": "https://www.cleanproxies.com/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Account and catalog", "description": "Your balance, the live catalog and prices, and proxy targeting options." }, { "name": "Orders", "description": "Place, list, renew and top up orders. Every order is paid from your account balance." }, { "name": "Proxies", "description": "Proxy lists, generated rotating/mobile lines, authentication and usage of delivered orders." }, { "name": "Servers", "description": "Power state and control of VPS and bare-metal servers." }, { "name": "Customers (sub-users)", "description": "Labels for your own customers. Tag orders with a customer to group and look them up; each rotating or mobile order already has its own isolated credentials." } ], "paths": { "/account": { "get": { "operationId": "getAccount", "tags": [ "Account and catalog" ], "summary": "Get account", "description": "Your account balance (what orders are paid from), the API key making the call, and your rate limits.\n\nRate limit class: read (120 requests per minute per API key).", "x-rate-limit-class": "read", "responses": { "200": { "description": "Get account", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "Xy12AbCdEf", "email": "you@example.com", "balanceCents": 1250000, "currency": "usd", "key": { "id": "key_9QmT2xLp7VbRnA1c", "name": "Production", "prefix": "cp_live_7Hq2…x9Lm" }, "rateLimits": { "readPerMinute": 120, "quotePerMinute": 60, "writePerMinute": 20, "actionPerMinute": 30 } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/products": { "get": { "operationId": "getProducts", "tags": [ "Account and catalog" ], "summary": "List products", "description": "The live catalog: retail price tiers, ISP providers with availability, gateway hosts, and VPS / bare-metal configurations with their OS ids. API orders are charged reseller prices (resellerPricing): your whole volume sets the tier, not the order size. Volume is your active IPs on isp / isp-subnet, or the GB you bought in the last 30 days on rotating-residential / mobile, plus the order itself; every order is charged the tier your volume reaches, and never more than retail for that order. customUnitPriceCents, when set, is a price agreed for your account.\n\nRate limit class: read (120 requests per minute per API key).", "x-rate-limit-class": "read", "responses": { "200": { "description": "List products", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "isp", "name": "ISP Proxies", "billing": "monthly", "unit": "ip", "available": true, "minQuantity": 5, "maxQuantity": 10000, "tiers": [ { "minQuantity": 5000, "unitPriceCents": 84 }, { "minQuantity": 10000, "unitPriceCents": 75 } ], "resellerPricing": { "basis": "active_ips", "volume": 340, "customUnitPriceCents": null, "tiers": [ { "minVolume": 1, "unitPriceCents": 129 }, { "minVolume": 1000, "unitPriceCents": 110 }, { "minVolume": 2500, "unitPriceCents": 100 }, { "minVolume": 5000, "unitPriceCents": 90 }, { "minVolume": 10000, "unitPriceCents": 80 } ] }, "defaultProvider": "frontier", "providers": [ { "key": "frontier", "name": "Frontier", "country": "US", "available": true } ] }, { "id": "rotating-residential", "name": "Rotating Residential", "billing": "one_time", "unit": "gb", "available": true, "minQuantity": 5, "maxQuantity": 100000, "tiers": [ { "minQuantity": 5000, "unitPriceCents": 74 }, { "minQuantity": 10000, "unitPriceCents": 63 } ], "gateway": { "host": "resipro.cleanproxies.com", "port": 5555 } }, { "id": "vps", "name": "VPS", "billing": "monthly", "unit": "config", "available": true, "location": "Virginia, USA", "defaultConfig": "4x8", "defaultOs": "ubuntu", "configs": [ { "id": "4x8", "label": "4 vCPU / 8 GB", "priceCents": 2400, "available": true, "specs": [ "4 vCPU", "8 GB RAM" ] } ], "os": [ { "id": "ubuntu", "name": "Ubuntu 24.04" } ] } ] } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/locations": { "get": { "operationId": "getLocations", "tags": [ "Account and catalog" ], "summary": "List proxy locations", "description": "Countries, and for one country its regions, cities and ASNs, for generating rotating residential or mobile proxies. Region and city targeting are rotating residential only.\n\nRate limit class: action (30 requests per minute per API key).", "x-rate-limit-class": "action", "parameters": [ { "name": "product", "in": "query", "required": false, "description": "rotating-residential (default) or mobile", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "ISO 3166 alpha-2 code; adds regions, cities and ASNs", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List proxy locations", "content": { "application/json": { "schema": { "type": "object" }, "example": { "product": "rotating-residential", "cityTargeting": true, "countries": [ { "code": "us", "name": "United States", "hasAsns": true } ], "country": "us", "regions": [ { "code": "california", "name": "California" } ], "cities": [ { "code": "los_angeles", "name": "Los Angeles", "region": "california" } ], "citiesTruncated": false, "asns": [ { "code": "7922", "name": "Comcast" } ] } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/quote": { "post": { "operationId": "postQuote", "tags": [ "Account and catalog" ], "summary": "Get a quote", "description": "The server price for a product and configuration, whether it is in stock, and whether your balance covers it. Takes the same product fields as Create an order.\n\nRate limit class: quote (60 requests per minute per API key).", "x-rate-limit-class": "quote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "product": { "type": "string", "enum": [ "isp", "isp-subnet", "rotating-residential", "mobile", "vps", "bare-metal" ], "description": "isp, isp-subnet, rotating-residential, mobile, vps or bare-metal" }, "quantity": { "type": "integer", "description": "isp / isp-subnet: number of IPs (isp-subnet: 255, 510 or 1020)" }, "provider": { "type": "string", "description": "isp / isp-subnet: provider key from List products (default: the catalog default)" }, "gb": { "type": "integer", "description": "rotating-residential / mobile: GB" }, "configId": { "type": "string", "description": "vps / bare-metal: configuration and OS ids" }, "osId": { "type": "string", "description": "vps / bare-metal: configuration and OS ids" } }, "required": [ "product" ] }, "example": { "product": "isp", "quantity": 10000, "provider": "frontier" } } } }, "responses": { "200": { "description": "Get a quote", "content": { "application/json": { "schema": { "type": "object" }, "example": { "product": "isp", "planName": "ISP Proxies - Frontier", "details": "10000 IPs ~ Frontier ~ United States", "billing": "monthly", "unitPriceCents": 75, "subtotalCents": 750000, "totalCents": 750000, "currency": "usd", "inStock": true, "balanceCents": 1250000, "balanceSufficient": true, "shortfallCents": 0 } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders": { "post": { "operationId": "postOrders", "tags": [ "Orders" ], "summary": "Create an order", "description": "Places an order paid in full from your account balance; no card step. Answers 402 INSUFFICIENT_BALANCE (with shortfallCents) when the balance doesn't cover the whole price. The order starts as paid and becomes active once it is set up (seconds for rotating/mobile, up to a few minutes for ISP and servers): poll Get an order with ?wait=25. Monthly products last 30 days; renew them or set autoRenew.\n\nRate limit class: write (20 requests per minute per API key).", "x-rate-limit-class": "write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1-100 letters, digits, - and _ (a UUID is ideal). Retrying with the same key within 24 hours replays the first response instead of charging again.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "product": { "type": "string", "enum": [ "isp", "isp-subnet", "rotating-residential", "mobile", "vps", "bare-metal" ], "description": "isp, isp-subnet, rotating-residential, mobile, vps or bare-metal" }, "quantity": { "type": "integer", "description": "isp / isp-subnet: number of IPs (isp: 5-10,000; isp-subnet: 255, 510 or 1020)" }, "provider": { "type": "string", "description": "isp / isp-subnet: provider key (frontier, atnt, comcast, cox, rcn, tmobile, verizon, telus, ...)" }, "gb": { "type": "integer", "description": "rotating-residential / mobile: GB (minimum 5)" }, "configId": { "type": "string", "description": "vps / bare-metal: configuration id from List products" }, "osId": { "type": "string", "description": "vps / bare-metal: operating system id" }, "autoRenew": { "type": "boolean", "description": "Monthly products: renew from your balance 24 h before expiry" }, "customer": { "type": "string", "description": "Your customer label (a-z, 0-9, _ and -); created if new" }, "reference": { "type": "string", "description": "Your own reference, up to 100 characters" } }, "required": [ "product" ] }, "example": { "product": "isp", "quantity": 10000, "provider": "frontier", "autoRenew": true, "customer": "customer-001", "reference": "inv-1042" } } } }, "responses": { "201": { "description": "Create an order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "OcK3x9Qm2LpZt7Vb1RnA", "product": "isp", "type": "isp", "status": "paid", "planName": "ISP Proxies - Frontier", "details": "10000 IPs ~ Frontier ~ United States", "billing": "monthly", "quantity": 10000, "gb": null, "provider": "frontier", "country": "US", "configId": null, "osId": null, "autoRenew": true, "cardSubscription": false, "createdAt": "2026-10-19T12:00:00.000Z", "paidAt": "2026-10-19T12:00:01.000Z", "activatedAt": null, "expiresAt": null, "pricing": { "currency": "usd", "subtotalCents": 750000, "couponDiscountCents": 0, "walletAppliedCents": 750000, "amountDueCents": 0 }, "source": "api", "customer": "customer-001", "reference": "inv-1042", "service": null } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "get": { "operationId": "getOrders", "tags": [ "Orders" ], "summary": "List orders", "description": "Your orders, newest first (dashboard and API orders alike; balance deposits are not listed). Pass nextCursor as cursor for the next page. Connection details are only on Get an order.\n\nRate limit class: read (120 requests per minute per API key).", "x-rate-limit-class": "read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1-100, default 25", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the previous page", "schema": { "type": "string" } }, { "name": "product", "in": "query", "required": false, "description": "Only this product (also trial)", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "pending_payment, paid, provisioning, active, failed, abandoned, expired, cancelled or refunded", "schema": { "type": "string" } }, { "name": "customer", "in": "query", "required": false, "description": "Only orders tagged with this customer", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } } }, "example": { "data": [ { "id": "OcK3x9Qm2LpZt7Vb1RnA", "product": "isp", "type": "isp", "status": "active", "planName": "ISP Proxies - Frontier", "details": "10000 IPs ~ Frontier ~ United States", "billing": "monthly", "quantity": 10000, "gb": null, "provider": "frontier", "country": "US", "configId": null, "osId": null, "autoRenew": true, "cardSubscription": false, "createdAt": "2026-10-19T12:00:00.000Z", "paidAt": "2026-10-19T12:00:01.000Z", "activatedAt": "2026-10-19T12:00:40.000Z", "expiresAt": "2026-11-18T12:00:40.000Z", "pricing": { "currency": "usd", "subtotalCents": 750000, "couponDiscountCents": 0, "walletAppliedCents": 750000, "amountDueCents": 0 }, "source": "api", "customer": "customer-001", "reference": "inv-1042" } ], "hasMore": false, "nextCursor": null } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}": { "get": { "operationId": "getOrder", "tags": [ "Orders" ], "summary": "Get an order", "description": "One order with its connection details in `service` once it is active: ISP username/password (the IP list is at /proxies), the rotating/mobile gateway and password, or the server IP and login. `wait` long-polls up to that many seconds until the order is active or has ended.\n\nRate limit class: read (120 requests per minute per API key).", "x-rate-limit-class": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string" } }, { "name": "wait", "in": "query", "required": false, "description": "0-25 seconds to wait for the order to become active", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Get an order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "OcK3x9Qm2LpZt7Vb1RnA", "product": "isp", "type": "isp", "status": "active", "planName": "ISP Proxies - Frontier", "details": "10000 IPs ~ Frontier ~ United States", "billing": "monthly", "quantity": 10000, "gb": null, "provider": "frontier", "country": "US", "configId": null, "osId": null, "autoRenew": true, "cardSubscription": false, "createdAt": "2026-10-19T12:00:00.000Z", "paidAt": "2026-10-19T12:00:01.000Z", "activatedAt": "2026-10-19T12:00:40.000Z", "expiresAt": "2026-11-18T12:00:40.000Z", "pricing": { "currency": "usd", "subtotalCents": 750000, "couponDiscountCents": 0, "walletAppliedCents": 750000, "amountDueCents": 0 }, "source": "api", "customer": "customer-001", "reference": "inv-1042", "service": { "type": "isp", "authType": "user", "username": "cpuser", "password": "s3cr3tPass", "authorizedIps": [], "quantity": 10000, "proxiesEndpoint": "/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA/proxies" } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/renew": { "post": { "operationId": "postRenew", "tags": [ "Orders" ], "summary": "Renew an order", "description": "Adds one 30-day period to an active monthly order (isp, isp-subnet, vps, bare-metal) at your current reseller price, paid from your balance. Allowed until 24 hours after expiry. Orders billed by a card subscription renew by themselves.\n\nRate limit class: write (20 requests per minute per API key).", "x-rate-limit-class": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1-100 letters, digits, - and _ (a UUID is ideal). Retrying with the same key within 24 hours replays the first response instead of charging again.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} }, "example": {} } } }, "responses": { "200": { "description": "Renew an order", "content": { "application/json": { "schema": { "type": "object" }, "example": { "renewal": { "id": "OcK4aB7Qm2LpZt7Vb1Rn", "status": "applied", "amountCents": 750000 }, "order": { "id": "OcK3x9Qm2LpZt7Vb1RnA", "product": "isp", "type": "isp", "status": "active", "planName": "ISP Proxies - Frontier", "details": "10000 IPs ~ Frontier ~ United States", "billing": "monthly", "quantity": 10000, "gb": null, "provider": "frontier", "country": "US", "configId": null, "osId": null, "autoRenew": true, "cardSubscription": false, "createdAt": "2026-10-19T12:00:00.000Z", "paidAt": "2026-10-19T12:00:01.000Z", "activatedAt": "2026-10-19T12:00:40.000Z", "expiresAt": "2026-12-18T12:00:40.000Z", "pricing": { "currency": "usd", "subtotalCents": 750000, "couponDiscountCents": 0, "walletAppliedCents": 750000, "amountDueCents": 0 }, "source": "api", "customer": "customer-001", "reference": "inv-1042" } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/topup": { "post": { "operationId": "postTopup", "tags": [ "Orders" ], "summary": "Top up GB", "description": "Adds GB to an active rotating residential or mobile order. The credentials stay the same. Priced at your reseller GB price (your GB bought in the last 30 days plus this top-up sets the tier); minimum 5 GB.\n\nRate limit class: write (20 requests per minute per API key).", "x-rate-limit-class": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1-100 letters, digits, - and _ (a UUID is ideal). Retrying with the same key within 24 hours replays the first response instead of charging again.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "gb": { "type": "integer", "description": "GB to add" } }, "required": [ "gb" ] }, "example": { "gb": 250 } } } }, "responses": { "200": { "description": "Top up GB", "content": { "application/json": { "schema": { "type": "object" }, "example": { "topup": { "id": "OcK4bC8Rn3MqAu8Wc2So", "status": "applied", "amountCents": 23500, "gb": 250 }, "order": { "id": "OcK3x9Qm2LpZt7Vb1RnA", "product": "rotating-residential", "status": "active", "gb": 300 } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/auto-renew": { "post": { "operationId": "postAutoRenew", "tags": [ "Orders" ], "summary": "Set auto-renew", "description": "Turns automatic renewal from your balance on or off for a monthly order. Turning it off is how you cancel: the order then ends at expiresAt.\n\nRate limit class: write (20 requests per minute per API key).", "x-rate-limit-class": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-100 letters, digits, - and _ (a UUID is ideal). Retrying with the same key within 24 hours replays the first response instead of charging again.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "true or false" } }, "required": [ "enabled" ] }, "example": { "enabled": false } } } }, "responses": { "200": { "description": "Set auto-renew", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "OcK3x9Qm2LpZt7Vb1RnA", "autoRenew": false } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/proxies": { "get": { "operationId": "getProxies", "tags": [ "Proxies" ], "summary": "Get proxies", "description": "ISP / ISP subnet orders: the IP list, as ip:port:username:password (or ip:port under IP authentication). Rotating residential / mobile orders: generated proxy lines for the targeting you ask for; sticky sessions keep the same IP for ttl minutes.\n\nRate limit class: action (30 requests per minute per API key).", "x-rate-limit-class": "action", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "Rotating/mobile: ISO alpha-2 code, or global (default)", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Rotating residential: codes from List proxy locations (need country)", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "description": "Rotating residential: codes from List proxy locations (need country)", "schema": { "type": "string" } }, { "name": "asn", "in": "query", "required": false, "description": "Rotating/mobile: ASN such as 7922 (needs country; not with region/city)", "schema": { "type": "string" } }, { "name": "session", "in": "query", "required": false, "description": "rotating (default) or sticky", "schema": { "type": "string" } }, { "name": "ttl", "in": "query", "required": false, "description": "Sticky session minutes, 1-1440", "schema": { "type": "integer" } }, { "name": "count", "in": "query", "required": false, "description": "Lines to generate, 1-1000 (default 10)", "schema": { "type": "integer" } }, { "name": "format", "in": "query", "required": false, "description": "host:port:user:pass (default), user:pass@host:port or user:pass:host:port", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get proxies", "content": { "application/json": { "schema": { "type": "object" }, "example": { "orderId": "OcK3x9Qm2LpZt7Vb1RnA", "type": "gb", "gateway": { "host": "resipro.cleanproxies.com", "port": 5555 }, "sessionType": "sticky", "ttlMinutes": 30, "count": 2, "format": "host:port:user:pass", "proxies": [ "resipro.cleanproxies.com:5555:pkg-res1-country-us-session-a1b2c3-ttl-30:s3cr3t", "resipro.cleanproxies.com:5555:pkg-res1-country-us-session-d4e5f6-ttl-30:s3cr3t" ] } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/auth": { "post": { "operationId": "postAuth", "tags": [ "Proxies" ], "summary": "Set ISP authentication", "description": "Switches an ISP / ISP subnet order between username/password authentication and an IP whitelist of 1-20 IPv4 addresses.\n\nRate limit class: action (30 requests per minute per API key).", "x-rate-limit-class": "action", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-100 letters, digits, - and _ (a UUID is ideal). Retrying with the same key within 24 hours replays the first response instead of charging again.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "authType": { "type": "string", "description": "user or ip" }, "ips": { "type": "array", "items": { "type": "string" }, "description": "authType ip: 1-20 IPv4 addresses" } }, "required": [ "authType" ] }, "example": { "authType": "ip", "ips": [ "203.0.113.7" ] } } } }, "responses": { "200": { "description": "Set ISP authentication", "content": { "application/json": { "schema": { "type": "object" }, "example": { "orderId": "OcK3x9Qm2LpZt7Vb1RnA", "authType": "ip", "authorizedIps": [ "203.0.113.7" ] } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/usage": { "get": { "operationId": "getUsage", "tags": [ "Proxies" ], "summary": "Get usage", "description": "GB bought, used and left on a rotating residential or mobile order, with daily usage for the last 30 days (UTC).\n\nRate limit class: action (30 requests per minute per API key).", "x-rate-limit-class": "action", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get usage", "content": { "application/json": { "schema": { "type": "object" }, "example": { "orderId": "OcK3x9Qm2LpZt7Vb1RnA", "limitGb": 300, "usedGb": 41.27, "remainingGb": 258.73, "daily": [ { "date": "2026-10-18", "gb": 3.12 } ], "range": { "start": "2026-09-19", "end": "2026-10-19" } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/server": { "get": { "operationId": "getServer", "tags": [ "Servers" ], "summary": "Get server state", "description": "Live power state of a VPS or bare-metal server: running, stopped, stopping, starting, pending, error, terminated or unknown.\n\nRate limit class: action (30 requests per minute per API key).", "x-rate-limit-class": "action", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get server state", "content": { "application/json": { "schema": { "type": "object" }, "example": { "orderId": "OcK3x9Qm2LpZt7Vb1RnA", "state": "running", "ip": "198.51.100.24" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/power": { "post": { "operationId": "postPower", "tags": [ "Servers" ], "summary": "Power control", "description": "Starts, stops or reboots a server. One action per server every 30 seconds (429 ACTION_COOLDOWN otherwise).\n\nRate limit class: action (30 requests per minute per API key).", "x-rate-limit-class": "action", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-100 letters, digits, - and _ (a UUID is ideal). Retrying with the same key within 24 hours replays the first response instead of charging again.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "action": { "type": "string", "description": "start, stop or reboot" } }, "required": [ "action" ] }, "example": { "action": "reboot" } } } }, "responses": { "202": { "description": "Power control", "content": { "application/json": { "schema": { "type": "object" }, "example": { "orderId": "OcK3x9Qm2LpZt7Vb1RnA", "action": "reboot", "status": "requested" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/reinstall": { "post": { "operationId": "postReinstall", "tags": [ "Servers" ], "summary": "Reinstall OS", "description": "Reinstalls a bare-metal server with an OS from its configuration's list and answers the new login. Erases the disks. At most once every 10 minutes.\n\nRate limit class: action (30 requests per minute per API key).", "x-rate-limit-class": "action", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-100 letters, digits, - and _ (a UUID is ideal). Retrying with the same key within 24 hours replays the first response instead of charging again.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "osId": { "type": "string", "description": "OS id from List products" } }, "required": [ "osId" ] }, "example": { "osId": "ubuntu" } } } }, "responses": { "202": { "description": "Reinstall OS", "content": { "application/json": { "schema": { "type": "object" }, "example": { "orderId": "OcK3x9Qm2LpZt7Vb1RnA", "status": "reinstalling", "osId": "ubuntu", "username": "root", "password": "n3wPassw0rd" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/users": { "post": { "operationId": "postUsers", "tags": [ "Customers (sub-users)" ], "summary": "Create a customer", "description": "Creates a customer label (201), or answers the existing one (200). Orders created with this customer are listed under it.\n\nRate limit class: write (20 requests per minute per API key).", "x-rate-limit-class": "write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1-100 letters, digits, - and _ (a UUID is ideal). Retrying with the same key within 24 hours replays the first response instead of charging again.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "username": { "type": "string", "description": "1-64 characters: a-z, 0-9, _ and -" }, "note": { "type": "string", "description": "Up to 200 characters" } }, "required": [ "username" ] }, "example": { "username": "customer-001", "note": "Acme Ltd" } } } }, "responses": { "201": { "description": "Create a customer", "content": { "application/json": { "schema": { "type": "object" }, "example": { "username": "customer-001", "note": "Acme Ltd", "createdAt": "2026-10-19T12:00:00.000Z", "orderCount": 0 } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "get": { "operationId": "getUsers", "tags": [ "Customers (sub-users)" ], "summary": "List customers", "description": "Your customer labels in alphabetical order.\n\nRate limit class: read (120 requests per minute per API key).", "x-rate-limit-class": "read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1-100, default 50", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the previous page", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List customers", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "username": "customer-001", "note": "Acme Ltd", "createdAt": "2026-10-19T12:00:00.000Z", "orderCount": 2 } ], "hasMore": false, "nextCursor": null } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/users/{username}": { "get": { "operationId": "getUser", "tags": [ "Customers (sub-users)" ], "summary": "Get a customer", "description": "A customer with its latest 100 orders and totals: active orders, active ISP IPs, GB bought on active rotating/mobile orders, and active servers.\n\nRate limit class: read (120 requests per minute per API key).", "x-rate-limit-class": "read", "parameters": [ { "name": "username", "in": "path", "required": true, "description": "Customer label", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a customer", "content": { "application/json": { "schema": { "type": "object" }, "example": { "username": "customer-001", "note": "Acme Ltd", "createdAt": "2026-10-19T12:00:00.000Z", "orderCount": 1, "summary": { "activeOrders": 1, "activeIps": 10000, "gbPurchased": 0, "activeServers": 0 }, "orders": [ { "id": "OcK3x9Qm2LpZt7Vb1RnA", "product": "isp", "type": "isp", "status": "active", "planName": "ISP Proxies - Frontier", "details": "10000 IPs ~ Frontier ~ United States", "billing": "monthly", "quantity": 10000, "gb": null, "provider": "frontier", "country": "US", "configId": null, "osId": null, "autoRenew": true, "cardSubscription": false, "createdAt": "2026-10-19T12:00:00.000Z", "paidAt": "2026-10-19T12:00:01.000Z", "activatedAt": "2026-10-19T12:00:40.000Z", "expiresAt": "2026-11-18T12:00:40.000Z", "pricing": { "currency": "usd", "subtotalCents": 750000, "couponDiscountCents": 0, "walletAppliedCents": 750000, "amountDueCents": 0 }, "source": "api", "customer": "customer-001", "reference": "inv-1042" } ] } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteUser", "tags": [ "Customers (sub-users)" ], "summary": "Delete a customer", "description": "Deletes the label. Refused (409 CUSTOMER_HAS_ACTIVE_ORDERS) while the customer has pending or active orders. Orders themselves are never changed.\n\nRate limit class: write (20 requests per minute per API key).", "x-rate-limit-class": "write", "parameters": [ { "name": "username", "in": "path", "required": true, "description": "Customer label", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete a customer", "content": { "application/json": { "schema": { "type": "object" }, "example": { "username": "customer-001", "deleted": true } } } }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer cp_live_..." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "Order": { "type": "object", "required": [ "id", "product", "status", "billing", "autoRenew", "pricing", "source" ], "properties": { "id": { "type": "string", "description": "Order id" }, "product": { "type": "string", "description": "isp, isp-subnet, rotating-residential, mobile, vps, bare-metal (or trial for dashboard orders)" }, "type": { "type": [ "string", "null" ], "enum": [ "isp", "gb", "vps", "bare-metal", null ], "description": "What `service` holds once active" }, "status": { "type": "string", "enum": [ "pending_payment", "paid", "provisioning", "active", "failed", "abandoned", "expired", "cancelled", "refunded" ] }, "planName": { "type": [ "string", "null" ] }, "details": { "type": [ "string", "null" ] }, "billing": { "type": "string", "enum": [ "monthly", "one_time" ] }, "quantity": { "type": [ "integer", "null" ], "description": "ISP / ISP subnet: number of IPs" }, "gb": { "type": [ "number", "null" ], "description": "Rotating residential / mobile: GB bought" }, "provider": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "configId": { "type": [ "string", "null" ] }, "osId": { "type": [ "string", "null" ] }, "autoRenew": { "type": "boolean" }, "cardSubscription": { "type": "boolean", "description": "Billed by a card subscription (renews by itself)" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "activatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "pricing": { "type": "object", "properties": { "currency": { "type": "string", "const": "usd" }, "subtotalCents": { "type": "integer" }, "couponDiscountCents": { "type": "integer" }, "walletAppliedCents": { "type": "integer" }, "amountDueCents": { "type": "integer" } } }, "source": { "type": "string", "enum": [ "api", "dashboard" ] }, "customer": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "service": { "description": "Only on Get an order: connection details once the order is active, otherwise null.", "oneOf": [ { "$ref": "#/components/schemas/IspService" }, { "$ref": "#/components/schemas/GbService" }, { "$ref": "#/components/schemas/ServerService" }, { "type": "null" } ] } } }, "IspService": { "type": "object", "properties": { "type": { "type": "string", "const": "isp" }, "authType": { "type": "string", "enum": [ "user", "ip" ] }, "username": { "type": [ "string", "null" ] }, "password": { "type": [ "string", "null" ] }, "authorizedIps": { "type": "array", "items": { "type": "string" } }, "quantity": { "type": [ "integer", "null" ] }, "proxiesEndpoint": { "type": "string" } } }, "GbService": { "type": "object", "properties": { "type": { "type": "string", "const": "gb" }, "gateway": { "type": "object", "properties": { "host": { "type": [ "string", "null" ] }, "port": { "type": [ "integer", "null" ] } } }, "password": { "type": [ "string", "null" ] }, "dataLimitGb": { "type": [ "number", "null" ] }, "proxiesEndpoint": { "type": "string" }, "usageEndpoint": { "type": "string" } } }, "ServerService": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vps", "bare-metal" ] }, "ip": { "type": [ "string", "null" ] }, "hostname": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "password": { "type": [ "string", "null" ] }, "osId": { "type": [ "string", "null" ] }, "configId": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "cpu": { "type": [ "integer", "null" ], "description": "VPS only" }, "ramGb": { "type": [ "integer", "null" ], "description": "VPS only" }, "diskGb": { "type": [ "integer", "null" ], "description": "VPS only" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "Stable machine code (see the error table in the docs)" }, "message": { "type": "string" }, "requestId": { "type": "string" }, "field": { "type": "string" }, "requiredCents": { "type": "integer" }, "balanceCents": { "type": "integer" }, "shortfallCents": { "type": "integer" } } } } } }, "responses": { "Error": { "description": "Error envelope with a stable machine code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your account balance ($1000.00) doesn't cover this ($7500.00). Add at least $6500.00 at /dashboard/balance/deposit and retry.", "requestId": "req_8Zt2Lq9Xb3Vn1Ma7Kc4P", "requiredCents": 750000, "balanceCents": 100000, "shortfallCents": 650000 } } } } } } } }