{"openapi":"3.1.0","info":{"title":"FlashProxy API reference","version":"1.0.0","description":"Check your balance and plans, read usage, generate proxies and extend plans from your own scripts. Every endpoint returns JSON and only reads data from your own account."},"externalDocs":{"url":"https://www.flashproxy.com/docs/api"},"servers":[{"url":"https://www.flashproxy.com"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"account","description":"Account"},{"name":"usage","description":"Usage"},{"name":"proxies","description":"Proxies"},{"name":"extend","description":"Extensions"},{"name":"catalog","description":"Products & prices"}],"paths":{"/api/v1/key":{"get":{"operationId":"getKey","summary":"Current key","description":"Returns the key you are calling with: its name, prefix and permissions. Useful when a call answers 403 FORBIDDEN.\n\nRequires permission: usage","tags":["account"],"x-required-permission":"usage","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"key_id":"7d1c2b4e-…","name":"Monitoring server","key_prefix":"fpk_live_k3x9q2ma","permissions":["usage","proxies","extend"],"created_at":"2026-09-29T12:00:00.000Z","last_used_at":"2026-10-13T12:00:00.000Z"}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/balance":{"get":{"operationId":"getBalance","summary":"Account balance","description":"Returns your available account balance, the money extensions are paid from.\n\nRequires permission: usage","tags":["account"],"x-required-permission":"usage","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"balance_usd":42.18,"balance_cents":4218,"currency":"USD"}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/plans":{"get":{"operationId":"listPlans","summary":"List plans","description":"Returns your plans, newest first, with their status, expiry, data cap and whether they are extended by gb or days. Never returns proxy credentials.\n\nRequires permission: usage","tags":["account"],"x-required-permission":"usage","parameters":[{"name":"status","in":"query","required":false,"description":"all (default), active or expired.","schema":{"type":"string","example":"active"}},{"name":"limit","in":"query","required":false,"description":"How many plans to return, up to 100. Defaults to 50.","schema":{"type":"integer","example":10}},{"name":"offset","in":"query","required":false,"description":"How many plans to skip, for paging. Defaults to 0.","schema":{"type":"integer","example":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"plans":[{"plan_id":"YOUR_PLAN_ID","product":"residential","name":"Residential Proxies","status":"active","billed_by":"data","created_at":"2026-09-13T12:00:00.000Z","expires_at":"2027-03-12T12:00:00.000Z","max_bytes":10737418240,"bytes_used":4294967296,"speed_mbps":null,"extend_with":"gb"}],"total":1,"limit":10,"offset":0}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/transactions":{"get":{"operationId":"listTransactions","summary":"List transactions","description":"Returns your payments, top-ups and balance purchases, newest first, for bookkeeping.\n\nRequires permission: usage","tags":["account"],"x-required-permission":"usage","parameters":[{"name":"limit","in":"query","required":false,"description":"How many transactions to return, up to 100. Defaults to 50.","schema":{"type":"integer","example":10}},{"name":"offset","in":"query","required":false,"description":"How many transactions to skip, for paging. Defaults to 0.","schema":{"type":"integer","example":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"transactions":[{"transaction_id":"FP-1791900000000-a1b2c3d4e","type":"PURCHASE","status":"COMPLETED","amount_usd":29.8,"payment_method":"BALANCE","description":"Purchase of 1 item","created_at":"2026-10-11T12:00:00.000Z","completed_at":"2026-10-11T12:00:00.000Z"}],"total":1,"limit":10,"offset":0,"currency":"USD"}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/usage":{"get":{"operationId":"listUsage","summary":"Usage of all active plans","description":"Returns a usage record for every active plan on your account.\n\nRequires permission: usage","tags":["usage"],"x-required-permission":"usage","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"plans":[{"plan_id":"YOUR_PLAN_ID","product":"ipv6-datacenter","name":"IPv6 Datacenter Proxies","status":"active","expires_at":"2026-11-01T12:00:00.000Z","usage":{"bytes_used":2639963,"max_bytes":null,"remaining_bytes":null,"percentage_used":null},"throughput_status":"ok","throughput":{"source":"per_minute","current_mbps":412.5,"avg_mbps_5m":380.1,"peak_mbps_1h":955,"sampled_at":"2026-10-13T11:59:15.000Z","data_delay_seconds":45,"limit_mbps":1000,"utilization_pct":41.25},"generated_at":"2026-10-13T12:00:00.000Z"}]}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/plans/{plan_id}/usage":{"get":{"operationId":"planUsage","summary":"Usage of one plan","description":"Returns the usage record of one of your plans, whatever its status.\n\nRequires permission: usage","tags":["usage"],"x-required-permission":"usage","parameters":[{"name":"plan_id","in":"path","required":true,"description":"The plan ID, as returned in plan_id by List plans.","schema":{"type":"string","example":"YOUR_PLAN_ID"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"plan_id":"YOUR_PLAN_ID","product":"ipv6-datacenter","name":"IPv6 Datacenter Proxies","status":"active","expires_at":"2026-11-01T12:00:00.000Z","usage":{"bytes_used":2639963,"max_bytes":null,"remaining_bytes":null,"percentage_used":null},"throughput_status":"ok","throughput":{"source":"per_minute","current_mbps":412.5,"avg_mbps_5m":380.1,"peak_mbps_1h":955,"sampled_at":"2026-10-13T11:59:15.000Z","data_delay_seconds":45,"limit_mbps":1000,"utilization_pct":41.25},"generated_at":"2026-10-13T12:00:00.000Z"}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/plans/{plan_id}/usage/history":{"get":{"operationId":"planUsageHistory","summary":"Usage history","description":"Returns a plan's traffic and speed over time, in fixed buckets (1 minute for 1h up to 4 hours for 30d), with totals, success rate and peaks. Timestamps are UTC. Available for ISP, ISP EU, Datacenter, IPv6 and Premium Unlimited plans.\n\nRequires permission: usage","tags":["usage"],"x-required-permission":"usage","parameters":[{"name":"plan_id","in":"path","required":true,"description":"The plan ID, as returned in plan_id by List plans.","schema":{"type":"string","example":"YOUR_PLAN_ID"}},{"name":"range","in":"query","required":false,"description":"Time window: 1h, 24h, 7d, 30d. Defaults to 24h.","schema":{"type":"string","example":"24h"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"plan_id":"YOUR_PLAN_ID","range":"24h","bucket_seconds":900,"generated_at":"2026-10-13T12:00:00.000Z","totals":{"bytes":3221225472,"bytes_up":214748364.8,"bytes_down":3006477107.2,"connections":48210,"success_pct":99.2,"peak_mbps":412.5,"peak_concurrent":37},"series":[{"t":"2026-10-13T11:30:00.000Z","bytes":41943040,"bytes_up":2097152,"bytes_down":39845888,"mbps":0.37,"connections_per_sec":0.62,"concurrent":12},{"t":"2026-10-13T11:45:00.000Z","bytes":52428800,"bytes_up":3145728,"bytes_down":49283072,"mbps":0.47,"connections_per_sec":0.71,"concurrent":15}]}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/plans/{plan_id}/destinations":{"get":{"operationId":"planDestinations","summary":"Top destinations","description":"Returns the sites a plan connected to most over a time range, with traffic, connections and success rate per host (top 100).\n\nRequires permission: usage","tags":["usage"],"x-required-permission":"usage","parameters":[{"name":"plan_id","in":"path","required":true,"description":"The plan ID, as returned in plan_id by List plans.","schema":{"type":"string","example":"YOUR_PLAN_ID"}},{"name":"range","in":"query","required":false,"description":"Time window: 1h, 24h, 7d, 30d. Defaults to 24h.","schema":{"type":"string","example":"24h"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"plan_id":"YOUR_PLAN_ID","range":"24h","generated_at":"2026-10-13T12:00:00.000Z","destinations":[{"host":"example.com","bytes_down":1288490188.8,"bytes_up":107374182.4,"connections":18240,"failed":96,"success_pct":99.5}]}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/plans/{plan_id}/errors":{"get":{"operationId":"planErrors","summary":"Error breakdown","description":"Returns what went wrong over a time range, grouped by category, each with a readable label and a hint on what to check.\n\nRequires permission: usage","tags":["usage"],"x-required-permission":"usage","parameters":[{"name":"plan_id","in":"path","required":true,"description":"The plan ID, as returned in plan_id by List plans.","schema":{"type":"string","example":"YOUR_PLAN_ID"}},{"name":"range","in":"query","required":false,"description":"Time window: 1h, 24h, 7d, 30d. Defaults to 24h.","schema":{"type":"string","example":"24h"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"plan_id":"YOUR_PLAN_ID","range":"24h","generated_at":"2026-10-13T12:00:00.000Z","errors":[{"category":"timeout","label":"Connection timed out","hint":"The destination did not answer in time. Usually a slow or overloaded target site; retry with a longer client timeout, and check whether one destination dominates.","count":214}]}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/plans/{plan_id}/locations":{"get":{"operationId":"planLocations","summary":"Plan locations","description":"Returns the countries a plan can target with the country field when you generate proxies. When any_country is true, any two-letter code is accepted and there is no list.\n\nRequires permission: usage","tags":["proxies"],"x-required-permission":"usage","parameters":[{"name":"plan_id","in":"path","required":true,"description":"The plan ID, as returned in plan_id by List plans.","schema":{"type":"string","example":"YOUR_PLAN_ID"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"plan_id":"YOUR_PLAN_ID","product":"ipv6-datacenter","any_country":false,"countries":[{"code":"CA","name":"Canada"},{"code":"FR","name":"France"},{"code":"US","name":"United States"}]}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/plans/{plan_id}/proxies":{"post":{"operationId":"generateProxies","summary":"Generate proxies","description":"Builds ready-to-use proxy lines for one of your active plans, the same way the dashboard generator does.\n\nRequires permission: proxies","tags":["proxies"],"x-required-permission":"proxies","parameters":[{"name":"plan_id","in":"path","required":true,"description":"The plan ID, as returned in plan_id by List plans.","schema":{"type":"string","example":"YOUR_PLAN_ID"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","example":2,"description":"How many lines to return, 1 to 1000. Defaults to 10."},"country":{"type":"string","example":"US","description":"Two-letter country code to target, for example US. Leave it out for any country."},"session":{"type":"string","example":"sticky","description":"rotating for a new IP on every request (default), or sticky to keep the same IP."},"sticky_minutes":{"type":"integer","example":30,"description":"How long a sticky IP is kept, 1 to 1000 minutes. Residential and mobile cap it at 120. Defaults to 30."},"protocol":{"type":"string","example":"http","description":"http (default) or socks5."},"format":{"type":"string","example":"hostport","description":"hostport for host:port:user:pass (default), or url for scheme://user:pass@host:port."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"plan_id":"YOUR_PLAN_ID","count":2,"protocol":"http","format":"hostport","proxies":["adam.flashproxy.io:8080:USERNAME-country-US-session-k3x9q2ma-time-30:PASSWORD","adam.flashproxy.io:8080:USERNAME-country-US-session-p7d1v8tc-time-30:PASSWORD"]}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/plans/{plan_id}/ips":{"get":{"operationId":"planIps","summary":"Fixed IP list","description":"Returns the plan's fixed IPs with its login: live exit IPs for Datacenter plans, or the leased IPs for Dedicated ISP plans. Rotating-gateway plans use Generate proxies instead.\n\nRequires permission: proxies","tags":["proxies"],"x-required-permission":"proxies","parameters":[{"name":"plan_id","in":"path","required":true,"description":"The plan ID, as returned in plan_id by List plans.","schema":{"type":"string","example":"YOUR_PLAN_ID"}},{"name":"protocol","in":"query","required":false,"description":"http (default) or socks5. Dedicated ISP v2 plans support http only.","schema":{"type":"string","example":"http"}},{"name":"format","in":"query","required":false,"description":"hostport for host:port:user:pass (default), or url for scheme://user:pass@host:port.","schema":{"type":"string","example":"hostport"}},{"name":"limit","in":"query","required":false,"description":"How many IPs to return, up to 10000. Defaults to 1000. total always shows the full count.","schema":{"type":"integer","example":2}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"plan_id":"YOUR_PLAN_ID","product":"datacenter","source":"live","protocol":"http","format":"hostport","total":2048,"count":2,"proxies":["203.0.113.10:777:USERNAME:PASSWORD","203.0.113.11:777:USERNAME:PASSWORD"]}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/plans/{plan_id}/extend/quote":{"get":{"operationId":"quoteExtension","summary":"Quote an extension","description":"Returns what an extension would cost, running the same checks as Extend a plan, without buying anything.\n\nRequires permission: usage","tags":["extend"],"x-required-permission":"usage","parameters":[{"name":"plan_id","in":"path","required":true,"description":"The plan ID, as returned in plan_id by List plans.","schema":{"type":"string","example":"YOUR_PLAN_ID"}},{"name":"gb","in":"query","required":false,"description":"GB to quote, for plans billed by data.","schema":{"type":"integer","example":10}},{"name":"days","in":"query","required":false,"description":"Days to quote, for plans billed by time. Send gb or days, not both.","schema":{"type":"integer","example":30}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"plan_id":"YOUR_PLAN_ID","added":{"gb":10},"price_usd":35,"currency":"USD"}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/plans/{plan_id}/extend":{"post":{"operationId":"extendPlan","summary":"Extend a plan","description":"Adds data (gb) or time (days) to one of your plans and pays from your account balance, at the same price as the dashboard.\n\nRequires permission: extend","tags":["extend"],"x-required-permission":"extend","parameters":[{"name":"plan_id","in":"path","required":true,"description":"The plan ID, as returned in plan_id by List plans.","schema":{"type":"string","example":"YOUR_PLAN_ID"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"A unique string for this extension. See Idempotency below.","schema":{"type":"string","example":"extend-2026-10-13-001"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"gb":{"type":"integer","example":10,"description":"GB to add, for plans billed by data. A whole number from 1 to 2,000,000."},"days":{"type":"integer","example":30,"description":"Days to add, for plans billed by time: 1 to 365, or 1, 7, 30, 60 for Premium Unlimited Residential. Send gb or days, not both."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"plan_id":"YOUR_PLAN_ID","charged_usd":35,"added":{"gb":10},"plan":{"status":"active","expires_at":"2027-04-11T12:00:00.000Z","max_bytes":21474836480},"replayed":false}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}},"/api/v1/products":{"get":{"operationId":"listProducts","summary":"Products and prices","description":"Returns every product with its per-GB tiers (the whole amount is billed at the rate of the tier it falls in) and its speed-and-days prices. Use Quote an extension for the exact price of a specific plan.\n\nRequires permission: usage","tags":["catalog"],"x-required-permission":"usage","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"success":true,"data":{"products":[{"product":"datacenter","name":"Datacenter Proxies","billed_by":["data","time"],"data_pricing":[{"up_to_gb":1,"per_gb_usd":0.7},{"up_to_gb":5,"per_gb_usd":0.65}],"time_pricing":[{"mbps":10,"days":1,"price_usd":1},{"mbps":10,"days":30,"price_usd":18}]}],"currency":"USD"}}}}},"default":{"description":"Errors share one shape: success is false and error holds a code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"fpk_live_…"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Error":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST","IDEMPOTENCY_KEY_REQUIRED","PAYMENT_REFUSED","UNAUTHORIZED","INSUFFICIENT_BALANCE","FORBIDDEN","NOT_FOUND","PLAN_NOT_ACTIVE","PLAN_NOT_READY","IDEMPOTENCY_KEY_REUSED","REQUEST_IN_PROGRESS","PRICE_MISMATCH","EXTENSION_NOT_SUPPORTED","PROXIES_NOT_SUPPORTED","USAGE_HISTORY_NOT_SUPPORTED","IPS_NOT_SUPPORTED","CUSTOM_PLAN_EXTEND_VIA_SUPPORT","RATE_LIMITED","INTERNAL_ERROR","EXTENSION_FAILED","IPS_UNAVAILABLE"]},"message":{"type":"string"}}}}}}}}