{"openapi":"3.0.3","info":{"title":"Rainproxy API","version":"1.0","description":"Manage your proxies from your own code: generate proxy lists, check plans and usage, find locations and manage sub-users.\n\nAuthentication: create a key on the Public API page of your dashboard and send it with every request as `Authorization: Bearer rpc_...`.\n\nLimits: 120 requests per minute per key, of which 30 per minute for POST /proxy-strings. Errors come back as {\"error\": \"...\"} with an HTTP status code."},"servers":[{"url":"https://b2.rainproxy.io/api/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"rpc_..."}}},"security":[{"bearer":[]}],"tags":[{"name":"Proxies","description":"Generate proxy lists with the same options as the Generator."},{"name":"Plans","description":"Your active plans, data left and usage over time."},{"name":"Locations","description":"Countries, states, cities and ZIP codes you can target."},{"name":"Account","description":"Wallet balance and your account manager."},{"name":"Sub-users","description":"Extra dashboard logins for your team."},{"name":"Static ISP","description":"Buy dedicated static ISP IPs per IP: pick the carrier (ISP), how many IPs and for how many days. Paid from your wallet balance."}],"paths":{"/proxy-strings":{"post":{"tags":["Proxies"],"summary":"Generate proxies","description":"Returns a list of ready-to-use proxy lines for one of your plans. Every line is its own session. Unlimited Residential Max plans answer with their own server IP, HTTP port 10000 or SOCKS5 port 6969 (protocol), any country, US state and city, and sticky sessions of 1 to 1440 minutes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan_id"],"properties":{"plan_id":{"type":"integer","description":"Plan to use (GET /plans).","example":118300},"count":{"type":"integer","description":"How many lines, 1 to 1000. Default 10.","example":10},"country":{"type":"string","description":"Two-letter country code (GET /locations). Leave out for any country.","example":"US"},"state":{"type":"string","description":"State name (needs country). Unlimited Residential Max: US only.","example":"California"},"city":{"type":"string","description":"City name (needs country). Unlimited Residential Max: US only.","example":"Los Angeles"},"zip":{"type":"string","description":"ZIP / postal code. Premium Residential only. Any postcode of 120+ countries (GET /locations/postcodes to search; GET /locations/zips for the ones with IPs online right now). Send it with country. Spaces and dashes are removed (\"SW1A 1AA\" and \"05-230\" are fine); when no IP is online in that exact code you get the nearest one (25 km, 50 km, city/state, 100/200 km, then the country).","example":"90001"},"asn":{"type":"string","description":"Target one network (ASN number).","example":"7922"},"session":{"type":"string","enum":["rotating","sticky"],"description":"rotating = new IP on every request (default); sticky = keep the same IP."},"sticky_minutes":{"type":"integer","description":"How long a sticky IP is kept, 1 to 1440 minutes. Premium and Exclusive Residential, and Unlimited Residential Max (there the username carries -time-<seconds>, e.g. -session-k2j8d0s1-time-1800).","example":30},"protocol":{"type":"string","enum":["http","socks5"],"description":"Default http (HTTP and HTTPS)."},"format":{"type":"string","enum":["host:port:user:pass","user:pass@host:port"],"description":"Line format. Default host:port:user:pass."},"gateway":{"type":"string","enum":["us","eu"],"description":"Entry gateway closest to your servers. Residential plans."},"quality_filter":{"type":"boolean","description":"Skip low-reputation and blacklisted IPs. Residential plans."},"speed":{"type":"string","enum":["any","slow","medium","fast"],"description":"Connection speed filter. Residential plans."},"satellite":{"type":"boolean","description":"Only IPs that connect over satellite internet. Premium Residential."},"ipv6":{"type":"boolean","description":"IPv6 exit. Premium Residential only. The proxy leaves over the residential device's own IPv6 address (adds -ipv6-true to the username, e.g. rp_user-country-us-ipv6-true-session-k2j8d0s1). Works on sites that support IPv6 (Google, YouTube, Facebook, Instagram, Netflix...); a site without IPv6 answers HTTP 502 with the header x-proxy-error: no-ipv6 (SOCKS5 reply 0x04). No IPv4 fallback. Same price per GB."},"sub_user_id":{"type":"integer","description":"Generate for one of your sub-users' plans instead."}}},"example":{"plan_id":118300,"count":2,"country":"US","state":"California","session":"sticky","sticky_minutes":30}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"plan_id":118300,"count":2,"proxies":["resi-bridge-us.rainproxy.io:3333:rp_user-country-US-state-california-time-30-session-k2j8d0s1:Xk29fLq7mW","resi-bridge-us.rainproxy.io:3333:rp_user-country-US-state-california-time-30-session-q81mzt0a:Xk29fLq7mW"]}}}}}}},"/plans":{"get":{"tags":["Plans"],"summary":"List your active plans","description":"Your plans with data used and left, expiry, auto-renew and the proxy login. status is \"expired\" when the end date has passed.","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"plans":[{"id":118300,"product":"Premium Residential","plan_name":"25 GB Premium","billing":"data","data_gb":25,"used_gb":8.4,"remaining_gb":16.6,"usage_percent":33.6,"active_since":"2026-09-12","expires_at":"2027-03-11","days_left":164,"status":"active","auto_renew":true,"free_trial":false,"login":{"username":"rp_user","password":"Xk29fLq7mW"}}]}}}}}}},"/plans/{id}/usage":{"get":{"tags":["Plans"],"summary":"Usage over time","description":"Traffic per hour (24h) or per day (7d, 30d). Residential plans have history; other products return totals only (history_available false).","parameters":[{"name":"id","in":"path","required":true,"description":"Plan id.","schema":{"type":"integer"}},{"name":"range","in":"query","required":false,"description":"Default 7d.","schema":{"type":"string","enum":["24h","7d","30d"],"description":"Default 7d."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"plan_id":118300,"range":"7d","history_available":true,"interval":"day","used_gb":8.4,"remaining_gb":16.6,"history":[{"time":"2026-09-26T00:00:00Z","gb":1.21},{"time":"2026-09-27T00:00:00Z","gb":0.94}]}}}}}}},"/plans/{id}/reset-password":{"post":{"tags":["Plans"],"summary":"Reset the proxy password","description":"Makes a new proxy password. Old proxy lines stop working, so generate new ones afterwards. Plans of the same product share one login.","parameters":[{"name":"id","in":"path","required":true,"description":"Plan id.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"plan_id":118300,"login":{"username":"rp_user","password":"N3wPa55word"}}}}}}}},"/locations":{"get":{"tags":["Locations"],"summary":"Countries, states and cities","description":"Without country: the countries you can target with this plan. With country: its states and cities.","parameters":[{"name":"plan_id","in":"query","required":true,"description":"One of your active plan ids (from GET /plans).","schema":{"type":"integer","description":"One of your active plan ids (from GET /plans).","example":118300}},{"name":"country","in":"query","required":false,"description":"Two-letter country code.","schema":{"type":"string","description":"Two-letter country code.","example":"US"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"plan_id":118300,"country":{"code":"US","name":"United States"},"states":[{"name":"California","cities":["Los Angeles","San Diego"]}],"cities":["Los Angeles","San Diego"]}}}}}}},"/locations/zips":{"get":{"tags":["Locations"],"summary":"Postcode areas online now","description":"Premium Residential: postcode AREAS that have IPs online right now, with how many. IP geo data resolves to an area, not a full lettered code: US 5-digit ZIP, NL first 4 digits, UK outward code (SW1A), CA/IE first 3 characters, elsewhere the code as stored. Each row carries the area centroid (lat, lon). Target any full postcode with POST /proxy-strings: an IP in its area is used when one is online, else the nearest one.","parameters":[{"name":"plan_id","in":"query","required":true,"description":"One of your active plan ids (from GET /plans).","schema":{"type":"integer","description":"One of your active plan ids (from GET /plans).","example":118300}},{"name":"country","in":"query","required":true,"description":"Two-letter country code.","schema":{"type":"string","description":"Two-letter country code.","example":"US"}},{"name":"q","in":"query","required":false,"description":"Search by ZIP or place name.","schema":{"type":"string","description":"Search by ZIP or place name.","example":"Miami"}},{"name":"state","in":"query","required":false,"description":"Only this state.","schema":{"type":"string","description":"Only this state."}},{"name":"city","in":"query","required":false,"description":"Only this city.","schema":{"type":"string","description":"Only this city."}},{"name":"all","in":"query","required":false,"description":"Return the full list instead of the top matches.","schema":{"type":"boolean","description":"Return the full list instead of the top matches."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"plan_id":118300,"updated_at":"2026-09-28T07:00:00Z","totals":{"zips":6206,"ips":27401},"countries":[{"country":"US","zips":6206,"ips":27401}],"zips":[{"zip":"33101","area":"33101","lat":25.778,"lon":-80.199,"country":"US","state":"Florida","city":"Miami","ips":42,"online":true}]}}}}}}},"/locations/postcodes":{"get":{"tags":["Locations"],"summary":"Search postcodes","description":"Premium Residential: every postcode you can target in a country (120+ countries), whether or not an IP is online there right now. Search by the start of the code (digits, with or without spaces and dashes) or by the start of a place name. Every result carries its postcode area (`area`: the precision IP geo data has, e.g. NL 2625, UK SW1A, CA M5V) and the area centroid; compare `area` with GET /locations/zips to know whether an IP is online in that area right now. Pass the postcode value as `zip` to POST /proxy-strings together with `country`. In a proxy username the code is written without spaces or dashes (-zip-SW1A1AA); if no IP is online in that exact postcode the gateway serves the nearest available one. Postal code data (c) GeoNames (geonames.org), CC BY 4.0; UK data contains Royal Mail data (c) Royal Mail copyright and database right.","parameters":[{"name":"country","in":"query","required":true,"description":"Two-letter country code.","schema":{"type":"string","description":"Two-letter country code.","example":"NL"}},{"name":"q","in":"query","required":false,"description":"Start of the postcode or of a place name.","schema":{"type":"string","description":"Start of the postcode or of a place name.","example":"2625"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"country":"NL","total_country":468579,"results":[{"postcode":"2625 AB","key":"2625AB","place":"Delft","state":"South Holland","area":"2625","lat":51.992,"lon":4.342}]}}}}}}},"/account":{"get":{"tags":["Account"],"summary":"Wallet and account manager","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"email":"you@example.com","name":"You","wallet_balance":42.5,"currency":"USD","account_manager":{"name":"Liridon","email":"liridon@rainproxy.io","telegram":"https://t.me/liridxn"}}}}}}}},"/isp/pools":{"get":{"tags":["Static ISP"],"summary":"ISPs, stock and prices","description":"The carriers you can order dedicated static IPs from, with the cities they are in, whether they are in stock and for how many days they are sold. Prices are per IP; the volume discount applies to the whole order.","parameters":[{"name":"days","in":"query","required":false,"description":"Only ISPs sold for this many days (1, 7 or 30).","schema":{"type":"integer","description":"Only ISPs sold for this many days (1, 7 or 30).","example":30}},{"name":"country","in":"query","required":false,"description":"Only ISPs in this country (two-letter code).","schema":{"type":"string","description":"Only ISPs in this country (two-letter code).","example":"US"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"currency":"USD","prices":[{"days":1,"price_per_ip":0.99,"max_ips":500},{"days":7,"price_per_ip":1.69,"max_ips":500},{"days":30,"price_per_ip":2.49,"max_ips":500}],"volume_discounts":[{"from_ips":25,"percent_off":8},{"from_ips":100,"percent_off":15}],"isps":[{"pool":"us-verizon","isp":"Verizon Business","country":"US","asn":"701","cities":["Ashburn"],"in_stock":true,"days":[1,7,30]}]}}}}}}},"/isp/orders":{"post":{"tags":["Static ISP"],"summary":"Buy static ISP IPs","description":"Places an order paid from your wallet balance (top up in the dashboard). Most orders are ready within seconds (status active, with plan_id); some are checked by our team first (status processing) and show up in GET /plans within a few minutes. Get the IPs with POST /proxy-strings and the plan_id. The IPs end after the chosen days; to keep them longer, order the same ISP again. Limit: 10 orders per minute.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pool","days","quantity"],"properties":{"pool":{"type":"string","description":"The ISP to order from (GET /isp/pools).","example":"us-verizon"},"days":{"type":"integer","description":"1, 7 or 30.","example":30},"quantity":{"type":"integer","description":"How many IPs, 1 to 500.","example":10}}}}}},"responses":{"201":{"description":"Ordered","content":{"application/json":{"example":{"order_id":209500,"status":"active","message":"Your IPs are ready. Get them with POST /proxy-strings and this plan_id.","plan_id":120600,"isp":"Verizon Business (US)","days":30,"quantity":10,"price_per_ip":2.49,"charged":24.9,"wallet_balance":75.1}}}},"402":{"description":"Wallet balance too low (nothing charged)"},"409":{"description":"This ISP is out of stock or not sold for these days"}}}},"/sub-users":{"get":{"tags":["Sub-users"],"summary":"List sub-users","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"sub_users":[{"id":70211,"email":"team@example.com","status":"active","created_at":"2026-09-20","plan":null}]}}}}}},"post":{"tags":["Sub-users"],"summary":"Create a sub-user","description":"Creates an extra dashboard login under your account.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","description":"Login e-mail.","example":"team@example.com"},"password":{"type":"string","description":"At least 8 characters."}}},"example":{"email":"team@example.com","password":"a-long-password"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"id":70211,"email":"team@example.com","status":"active"}}}}}}},"/sub-users/{id}":{"patch":{"tags":["Sub-users"],"summary":"Enable or disable a sub-user","parameters":[{"name":"id","in":"path","required":true,"description":"Sub-user id.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","disabled"],"description":"New status."}}},"example":{"status":"disabled"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":70211,"status":"disabled"}}}}}},"delete":{"tags":["Sub-users"],"summary":"Delete a sub-user","parameters":[{"name":"id","in":"path","required":true,"description":"Sub-user id.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":70211,"deleted":true}}}}}}}}}