{"openapi":"3.1.0","info":{"title":"Datafuel API","version":"v1","description":"The Datafuel API lets your own servers and scripts buy and manage ISP, data center and residential proxies and web scraping plans.\n\nAuthenticate every request with an API key from **Settings → API keys**, sent as `Authorization: Bearer <key>`. Keys are secrets: call the API from your backend only, never from a browser or an app you ship to users.\n\nEach operation names the scope its key needs. Lists take `limit` and `offset`, and every order needs an `Idempotency-Key` header. The guides next to this reference cover authentication, orders and payments, idempotency, errors and rate limits."},"servers":[{"url":"https://api.datafuel.ai"}],"tags":[{"name":"Account","description":"The key's owner and the key itself."},{"name":"Payment methods","description":"The balance and saved cards orders are charged to."},{"name":"Orders","description":"Orders across every service."},{"name":"Subscriptions","description":"The subscriptions that renew plans."},{"name":"ISP proxies","description":"Static residential (ISP) IPs, announced by consumer internet providers."},{"name":"Data center proxies","description":"Static data center IPs."},{"name":"Residential proxies","description":"Plans of residential traffic: buying and topping them up, generating their proxies and reading their usage."},{"name":"Web scraping","description":"Your Scraping API plan, its credits and its API key."}],"paths":{"/api/v1/account":{"get":{"operationId":"account.getAccount","summary":"Get the account and this key","description":"Who the key belongs to and what it may do: its permissions, services, limits and this month's spending. A cheap way to check a key works.\n\nRequires the `read` level on at least one service.","tags":["Account"],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardAccountResponse"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.<service>.read"}},"/api/v1/account/personal-data":{"get":{"operationId":"account.getPersonalData","summary":"Export the account's personal data","description":"Everything held about the account, for a data access request: the profile and sign-in methods, orders, plans at every service, the wallet with payments, invoices and billing details, notifications and saved preferences. Secrets such as proxy passwords are left out.\n\nRequires the `manage` level on at least one service.","tags":["Account"],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.<service>.manage"}},"/api/v1/payment-methods":{"get":{"operationId":"paymentMethods.listPaymentMethods","summary":"List payment methods","description":"The balance orders can be paid from and the saved cards they can be charged to. Pass a card's `id` as `payment.card_id` to charge that card; without it the default card is charged. Cards are added in the dashboard.\n\nRequires the `purchase` level on at least one service.","tags":["Payment methods"],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardPaymentmethodResponse"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.<service>.purchase"}},"/api/v1/orders":{"get":{"operationId":"orders.listOrders","summary":"List orders","description":"Orders placed through the API or the dashboard, newest first, for the services this key may read. A summary: `payment` and `paid_at` are on GET /api/v1/orders/{id}.\n\nRequires the `read` level on at least one service.","tags":["Orders"],"parameters":[{"name":"limit","in":"query","description":"How many results to return, 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"How many results to skip.","schema":{"type":"integer","default":0,"minimum":0}},{"name":"service","in":"query","description":"Only this service's orders, e.g. static or residential.","schema":{"type":"string"}},{"name":"status","in":"query","description":"Only orders in this state.","schema":{"type":"string","enum":["pending","requires_action","paid","completed","delivery_failed","failed","expired","refunded"]}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/DashboardSummary"}},"count":{"type":"integer","format":"int64","description":"How many results match in total."},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["results","count"]}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.<service>.read"}},"/api/v1/orders/{order}":{"get":{"operationId":"orders.getOrder","summary":"Get an order","description":"Poll this after a 202 until the status is `completed`, `delivery_failed`, `failed`, `expired` or `refunded`, and stop after a few minutes: a delivery normally takes seconds. `plan_id` is the delivered plan's id, usable with that service's `/plans/{plan}`.\n\nRequires the `read` level on at least one service.","tags":["Orders"],"parameters":[{"name":"order","in":"path","description":"The order's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.<service>.read"}},"/api/v1/subscriptions":{"get":{"operationId":"subscriptions.listSubscriptions","summary":"List subscriptions","description":"The subscriptions that renew your plans, for the services this key may read.\n\nRequires the `read` level on at least one service.","tags":["Subscriptions"],"parameters":[{"name":"limit","in":"query","description":"How many results to return, 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"How many results to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/DashboardSubscriptionResponse"}},"count":{"type":"integer","format":"int64","description":"How many results match in total."},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["results","count"]}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.<service>.read"}},"/api/v1/subscriptions/{subscription}/auto-renew":{"put":{"operationId":"subscriptions.setAutoRenew","summary":"Turn auto-renew on or off","description":"Needs `manage` on the subscription's service. Turning it off keeps the plan until `period_ends_at`; turning it on again before then resumes renewals. Asking for the state the subscription is already in changes nothing and answers it. For a subscription paid by card, `card_id` switches the card renewals are charged to. `409` `subscription_ended` once it has expired, `no_saved_card` when a card subscription has no card left to resume on.\n\nRequires the `manage` level on at least one service.","tags":["Subscriptions"],"parameters":[{"name":"subscription","in":"path","description":"The subscription's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardAutoRenewRequest"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardSubscriptionResponse"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.<service>.manage"}},"/api/v1/isp/products":{"get":{"operationId":"isp.listProducts","summary":"List products","description":"The plans on sale and the periods each can be bought for. Prices depend on the quantity and locations, so ask `POST /quote` for one.\n\nRequires the `api.static.read` scope.","tags":["ISP proxies"],"parameters":[{"name":"limit","in":"query","description":"How many results to return, 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"How many results to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/StaticProduct"}},"count":{"type":"integer","format":"int64","description":"How many results match in total."},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["results","count"]}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/isp/products/{product}":{"get":{"operationId":"isp.getProduct","summary":"Get a product","description":"The product with every country and region it can be ordered in, its stock level and how many IPs one order may take there.\n\nRequires the `api.static.read` scope.","tags":["ISP proxies"],"parameters":[{"name":"product","in":"path","description":"The product's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticProductDetail"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/isp/plans":{"get":{"operationId":"isp.listPlans","summary":"List your plans","description":"Requires the `api.static.read` scope.","tags":["ISP proxies"],"parameters":[{"name":"limit","in":"query","description":"How many results to return, 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"How many results to skip.","schema":{"type":"integer","default":0,"minimum":0}},{"name":"status","in":"query","description":"Only plans in this state.","schema":{"type":"string","enum":["provisioning","active","past_due","suspended","expired"]}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/StaticPlan"}},"count":{"type":"integer","format":"int64","description":"How many results match in total."},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["results","count"]}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/isp/plans/{plan}":{"get":{"operationId":"isp.getPlan","summary":"Get a plan","description":"The plan with its authentication settings and locations. The username and password are at `GET /plans/{plan}/credentials`.\n\nRequires the `api.static.read` scope.","tags":["ISP proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticPlanDetail"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/isp/plans/{plan}/proxies":{"get":{"operationId":"isp.listProxies","summary":"List a plan's proxies","description":"Every IP of the plan with its port and location, plus the credentials to use them with. It carries the password, so it needs the manage level and is never cached.\n\nRequires the `api.static.manage` scope.","tags":["ISP proxies"],"parameters":[{"name":"format","in":"query","description":"json (the default) or txt.","schema":{"type":"string","enum":["json","txt"]}},{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticProxiesResponse"}},"text/plain":{"schema":{"type":"string","description":"With `?format=txt`: one `ip:port:username:password` per line."}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.manage"}},"/api/v1/isp/plans/{plan}/credentials":{"get":{"operationId":"isp.getCredentials","summary":"Get the credentials","description":"The username and password every IP of the plan accepts in credentials mode. They are a secret, so reading them needs the manage level and the answer is never cached.\n\nRequires the `api.static.manage` scope. Every call is recorded in the account's audit log.","tags":["ISP proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticCredentials"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.manage"}},"/api/v1/isp/plans/{plan}/credentials/reset":{"post":{"operationId":"isp.resetCredentials","summary":"Reset the credentials","description":"Issues a new password for every IP of the plan at once and answers the credentials; the old password stops working. The username stays. 409 `plan_not_active` unless the plan is active, `plan_provisioning` while some of its IPs are still being delivered.\n\nRequires the `api.static.manage` scope. Every call is recorded in the account's audit log.","tags":["ISP proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticCredentials"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.manage"}},"/api/v1/isp/plans/{plan}/auth":{"put":{"operationId":"isp.setAuth","summary":"Set how the proxies authenticate","description":"`credentials` asks for the username and password; `ip` lets only `allowed_ips` in. The list replaces the one the plan has. 409 `plan_not_active` unless the plan is active, `plan_provisioning` while some of its IPs are still being delivered.\n\nRequires the `api.static.manage` scope.","tags":["ISP proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticAuthRequest"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticPlanDetail"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.manage"}},"/api/v1/isp/plans/{plan}/replace":{"post":{"operationId":"isp.replaceIPs","summary":"Replace the IPs","description":"Swaps every IP of the plan for new ones in the same locations and spends one of `replacements_left`. Buy more with `POST /plans/{plan}/orders`. 409 `plan_not_active` unless the plan is active, `plan_provisioning` while some of its IPs are still being delivered, `no_replacements_left` when none are left.\n\nRequires the `api.static.manage` scope.","tags":["ISP proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticPlanDetail"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.manage"}},"/api/v1/isp/quote":{"post":{"operationId":"isp.quote","summary":"Price a new plan","description":"What `POST /orders` with the same body would charge, including discounts, tax and the payment method's fee, or why it cannot be ordered. Nothing is reserved. 404 when the product does not exist; 422 `promo_code_invalid` when the promo code is refused.\n\nRequires the `api.static.read` scope.","tags":["ISP proxies"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticNewPlanQuote"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseQuote"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request is well formed but cannot be carried out; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/isp/orders":{"post":{"operationId":"isp.order","summary":"Buy a new plan","description":"Charges the balance or a saved card straight away, without asking the customer, and delivers the plan. 201 answers the delivered plan; 202 means it is paid and still being delivered, or the bank asked for 3-D Secure (`order.action_url`). 404 when the product does not exist.\n\nRequires the `api.static.purchase` scope. Send a unique `Idempotency-Key` per order; repeating it with the same body answers the first order instead of charging again.","tags":["ISP proxies"],"parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value per order, sent again only to retry the same order.","required":true,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticNewPlanOrder"}}}},"responses":{"200":{"description":"A repeated `Idempotency-Key`: the order it placed first, with `replayed: true`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"201":{"description":"Paid and delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"202":{"description":"Paid and still being delivered (poll `GET /api/v1/orders/{id}`), or waiting for 3-D Secure at `order.action_url`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The payment was declined; `error` names why and `meta.order` is the failed order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required`, is used from an IP it does not allow, the order would pass the key's monthly spending limit (`spend_limit_exceeded`), or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such product or plan, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`in_progress`: another order of the account is still being placed, retry shortly with the same key; `idempotency_conflict`: the `Idempotency-Key` was already used for a different order; `duplicate_request`: the key was already used and its order is still being recorded, look it up instead of sending it again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The order cannot be placed; `error` names why: `not_purchasable` (with `meta.issues` when the order itself is at fault, e.g. out of stock), `promo_code_invalid`, `amount_too_small` or `payment_rejected`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.purchase"}},"/api/v1/isp/plans/{plan}/quote":{"post":{"operationId":"isp.quoteAddOn","summary":"Price an add-on","description":"What `POST /plans/{plan}/orders` with the same body would charge. 422 `promo_code_invalid` when the promo code is refused.\n\nRequires the `api.static.read` scope.","tags":["ISP proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticAddOnQuote"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseQuote"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request is well formed but cannot be carried out; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/isp/plans/{plan}/orders":{"post":{"operationId":"isp.orderAddOn","summary":"Buy an add-on","description":"Buys more IP replacements for a plan you hold, charged straight away.\n\nRequires the `api.static.purchase` scope. Send a unique `Idempotency-Key` per order; repeating it with the same body answers the first order instead of charging again.","tags":["ISP proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value per order, sent again only to retry the same order.","required":true,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticAddOnOrder"}}}},"responses":{"200":{"description":"A repeated `Idempotency-Key`: the order it placed first, with `replayed: true`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"201":{"description":"Paid and delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"202":{"description":"Paid and still being delivered (poll `GET /api/v1/orders/{id}`), or waiting for 3-D Secure at `order.action_url`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The payment was declined; `error` names why and `meta.order` is the failed order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required`, is used from an IP it does not allow, the order would pass the key's monthly spending limit (`spend_limit_exceeded`), or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such product or plan, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`in_progress`: another order of the account is still being placed, retry shortly with the same key; `idempotency_conflict`: the `Idempotency-Key` was already used for a different order; `duplicate_request`: the key was already used and its order is still being recorded, look it up instead of sending it again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The order cannot be placed; `error` names why: `not_purchasable` (with `meta.issues` when the order itself is at fault, e.g. out of stock), `promo_code_invalid`, `amount_too_small` or `payment_rejected`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.purchase"}},"/api/v1/dc/products":{"get":{"operationId":"dc.listProducts","summary":"List products","description":"The plans on sale and the periods each can be bought for. Prices depend on the quantity and locations, so ask `POST /quote` for one.\n\nRequires the `api.static.read` scope.","tags":["Data center proxies"],"parameters":[{"name":"limit","in":"query","description":"How many results to return, 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"How many results to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/StaticProduct"}},"count":{"type":"integer","format":"int64","description":"How many results match in total."},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["results","count"]}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/dc/products/{product}":{"get":{"operationId":"dc.getProduct","summary":"Get a product","description":"The product with every country and region it can be ordered in, its stock level and how many IPs one order may take there.\n\nRequires the `api.static.read` scope.","tags":["Data center proxies"],"parameters":[{"name":"product","in":"path","description":"The product's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticProductDetail"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/dc/plans":{"get":{"operationId":"dc.listPlans","summary":"List your plans","description":"Requires the `api.static.read` scope.","tags":["Data center proxies"],"parameters":[{"name":"limit","in":"query","description":"How many results to return, 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"How many results to skip.","schema":{"type":"integer","default":0,"minimum":0}},{"name":"status","in":"query","description":"Only plans in this state.","schema":{"type":"string","enum":["provisioning","active","past_due","suspended","expired"]}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/StaticPlan"}},"count":{"type":"integer","format":"int64","description":"How many results match in total."},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["results","count"]}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/dc/plans/{plan}":{"get":{"operationId":"dc.getPlan","summary":"Get a plan","description":"The plan with its authentication settings and locations. The username and password are at `GET /plans/{plan}/credentials`.\n\nRequires the `api.static.read` scope.","tags":["Data center proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticPlanDetail"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/dc/plans/{plan}/proxies":{"get":{"operationId":"dc.listProxies","summary":"List a plan's proxies","description":"Every IP of the plan with its port and location, plus the credentials to use them with. It carries the password, so it needs the manage level and is never cached.\n\nRequires the `api.static.manage` scope.","tags":["Data center proxies"],"parameters":[{"name":"format","in":"query","description":"json (the default) or txt.","schema":{"type":"string","enum":["json","txt"]}},{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticProxiesResponse"}},"text/plain":{"schema":{"type":"string","description":"With `?format=txt`: one `ip:port:username:password` per line."}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.manage"}},"/api/v1/dc/plans/{plan}/credentials":{"get":{"operationId":"dc.getCredentials","summary":"Get the credentials","description":"The username and password every IP of the plan accepts in credentials mode. They are a secret, so reading them needs the manage level and the answer is never cached.\n\nRequires the `api.static.manage` scope. Every call is recorded in the account's audit log.","tags":["Data center proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticCredentials"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.manage"}},"/api/v1/dc/plans/{plan}/credentials/reset":{"post":{"operationId":"dc.resetCredentials","summary":"Reset the credentials","description":"Issues a new password for every IP of the plan at once and answers the credentials; the old password stops working. The username stays. 409 `plan_not_active` unless the plan is active, `plan_provisioning` while some of its IPs are still being delivered.\n\nRequires the `api.static.manage` scope. Every call is recorded in the account's audit log.","tags":["Data center proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticCredentials"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.manage"}},"/api/v1/dc/plans/{plan}/auth":{"put":{"operationId":"dc.setAuth","summary":"Set how the proxies authenticate","description":"`credentials` asks for the username and password; `ip` lets only `allowed_ips` in. The list replaces the one the plan has. 409 `plan_not_active` unless the plan is active, `plan_provisioning` while some of its IPs are still being delivered.\n\nRequires the `api.static.manage` scope.","tags":["Data center proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticAuthRequest"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticPlanDetail"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.manage"}},"/api/v1/dc/plans/{plan}/replace":{"post":{"operationId":"dc.replaceIPs","summary":"Replace the IPs","description":"Swaps every IP of the plan for new ones in the same locations and spends one of `replacements_left`. Buy more with `POST /plans/{plan}/orders`. 409 `plan_not_active` unless the plan is active, `plan_provisioning` while some of its IPs are still being delivered, `no_replacements_left` when none are left.\n\nRequires the `api.static.manage` scope.","tags":["Data center proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticPlanDetail"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.manage"}},"/api/v1/dc/quote":{"post":{"operationId":"dc.quote","summary":"Price a new plan","description":"What `POST /orders` with the same body would charge, including discounts, tax and the payment method's fee, or why it cannot be ordered. Nothing is reserved. 404 when the product does not exist; 422 `promo_code_invalid` when the promo code is refused.\n\nRequires the `api.static.read` scope.","tags":["Data center proxies"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticNewPlanQuote"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseQuote"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request is well formed but cannot be carried out; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/dc/orders":{"post":{"operationId":"dc.order","summary":"Buy a new plan","description":"Charges the balance or a saved card straight away, without asking the customer, and delivers the plan. 201 answers the delivered plan; 202 means it is paid and still being delivered, or the bank asked for 3-D Secure (`order.action_url`). 404 when the product does not exist.\n\nRequires the `api.static.purchase` scope. Send a unique `Idempotency-Key` per order; repeating it with the same body answers the first order instead of charging again.","tags":["Data center proxies"],"parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value per order, sent again only to retry the same order.","required":true,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticNewPlanOrder"}}}},"responses":{"200":{"description":"A repeated `Idempotency-Key`: the order it placed first, with `replayed: true`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"201":{"description":"Paid and delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"202":{"description":"Paid and still being delivered (poll `GET /api/v1/orders/{id}`), or waiting for 3-D Secure at `order.action_url`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The payment was declined; `error` names why and `meta.order` is the failed order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required`, is used from an IP it does not allow, the order would pass the key's monthly spending limit (`spend_limit_exceeded`), or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such product or plan, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`in_progress`: another order of the account is still being placed, retry shortly with the same key; `idempotency_conflict`: the `Idempotency-Key` was already used for a different order; `duplicate_request`: the key was already used and its order is still being recorded, look it up instead of sending it again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The order cannot be placed; `error` names why: `not_purchasable` (with `meta.issues` when the order itself is at fault, e.g. out of stock), `promo_code_invalid`, `amount_too_small` or `payment_rejected`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.purchase"}},"/api/v1/dc/plans/{plan}/quote":{"post":{"operationId":"dc.quoteAddOn","summary":"Price an add-on","description":"What `POST /plans/{plan}/orders` with the same body would charge. 422 `promo_code_invalid` when the promo code is refused.\n\nRequires the `api.static.read` scope.","tags":["Data center proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticAddOnQuote"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseQuote"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request is well formed but cannot be carried out; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.read"}},"/api/v1/dc/plans/{plan}/orders":{"post":{"operationId":"dc.orderAddOn","summary":"Buy an add-on","description":"Buys more IP replacements for a plan you hold, charged straight away.\n\nRequires the `api.static.purchase` scope. Send a unique `Idempotency-Key` per order; repeating it with the same body answers the first order instead of charging again.","tags":["Data center proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value per order, sent again only to retry the same order.","required":true,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticAddOnOrder"}}}},"responses":{"200":{"description":"A repeated `Idempotency-Key`: the order it placed first, with `replayed: true`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"201":{"description":"Paid and delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"202":{"description":"Paid and still being delivered (poll `GET /api/v1/orders/{id}`), or waiting for 3-D Secure at `order.action_url`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticOrderResponse"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The payment was declined; `error` names why and `meta.order` is the failed order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required`, is used from an IP it does not allow, the order would pass the key's monthly spending limit (`spend_limit_exceeded`), or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such product or plan, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`in_progress`: another order of the account is still being placed, retry shortly with the same key; `idempotency_conflict`: the `Idempotency-Key` was already used for a different order; `duplicate_request`: the key was already used and its order is still being recorded, look it up instead of sending it again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The order cannot be placed; `error` names why: `not_purchasable` (with `meta.issues` when the order itself is at fault, e.g. out of stock), `promo_code_invalid`, `amount_too_small` or `payment_rejected`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.static.purchase"}},"/api/v1/residential/products":{"get":{"operationId":"residential.listProducts","summary":"List products","description":"The products on sale, each with your price per GB at each volume. The final price, with discounts, tax and fees, comes from `POST /quote`.\n\nRequires the `api.residential.read` scope.","tags":["Residential proxies"],"parameters":[{"name":"limit","in":"query","description":"How many results to return, 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"How many results to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ResidentialProduct"}},"count":{"type":"integer","format":"int64","description":"How many results match in total."},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["results","count"]}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.read"}},"/api/v1/residential/products/{product}":{"get":{"operationId":"residential.getProduct","summary":"Get a product","description":"The product with its prices and every country its proxies can exit in.\n\nRequires the `api.residential.read` scope.","tags":["Residential proxies"],"parameters":[{"name":"product","in":"path","description":"The product's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialProductDetail"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.read"}},"/api/v1/residential/plans":{"get":{"operationId":"residential.listPlans","summary":"List your plans","description":"The plans you hold, newest first, with the traffic left on each.\n\nRequires the `api.residential.read` scope.","tags":["Residential proxies"],"parameters":[{"name":"limit","in":"query","description":"How many results to return, 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"How many results to skip.","schema":{"type":"integer","default":0,"minimum":0}},{"name":"status","in":"query","description":"Only plans in this state.","schema":{"type":"string","enum":["provisioning","active","past_due","suspended","expired"]}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ResidentialPlan"}},"count":{"type":"integer","format":"int64","description":"How many results match in total."},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["results","count"]}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.read"}},"/api/v1/residential/plans/{plan}":{"get":{"operationId":"residential.getPlan","summary":"Get a plan","description":"The plan with the countries `POST /plans/{plan}/proxies` accepts. Its username and password come from `GET /plans/{plan}/credentials`; the usernames and gateways to connect with differ per proxy, so they come from `POST /plans/{plan}/proxies`.\n\nRequires the `api.residential.read` scope.","tags":["Residential proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialPlanDetail"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.read"}},"/api/v1/residential/plans/{plan}/locations":{"get":{"operationId":"residential.listLocations","summary":"List regions and cities","description":"The region and city codes in one of the plan's countries, for the `region` and `city` of `POST /plans/{plan}/proxies`; at most 200 of each. 409 `product_withdrawn` once the plan's product is no longer sold.\n\nRequires the `api.residential.read` scope.","tags":["Residential proxies"],"parameters":[{"name":"country","in":"query","description":"ISO 3166-1 alpha-2 code of one of the plan's countries.","required":true,"schema":{"type":"string"}},{"name":"region","in":"query","description":"Only the cities in this region, by its code from `regions`.","schema":{"type":"string"}},{"name":"search","in":"query","description":"Only regions and cities whose name matches, at most 64 characters.","schema":{"type":"string"}},{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialLocations"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.read"}},"/api/v1/residential/plans/{plan}/usage":{"get":{"operationId":"residential.getUsage","summary":"Get a plan's usage","description":"The requests and traffic the plan used between `from` and `to`, at most 400 days apart, as a series of points with their totals.\n\nRequires the `api.residential.read` scope.","tags":["Residential proxies"],"parameters":[{"name":"from","in":"query","description":"The start of the window, RFC 3339.","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"The end of the window, RFC 3339; after `from`.","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"timezone","in":"query","description":"The IANA time zone to lay the series out in, e.g. `Europe/Warsaw`.","schema":{"type":"string"}},{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialUsage"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.read"}},"/api/v1/residential/plans/{plan}/proxies":{"post":{"operationId":"residential.generateProxies","summary":"Generate proxies","description":"Builds `quantity` proxies on the plan, each with the gateway for its country, a username carrying its targeting and session, and the plan's password. Nothing is created or changed, but the answer carries the password, so it needs the `manage` level. Without `country`, each proxy exits in a random country of the plan. 409 `product_withdrawn` once the plan's product is no longer sold.\n\nRequires the `api.residential.manage` scope.","tags":["Residential proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialProxiesRequest"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialProxiesResponse"}},"text/plain":{"schema":{"type":"string","description":"With `\"format\": \"txt\"`: one `host:port:username:password` per line."}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.manage"}},"/api/v1/residential/plans/{plan}/credentials":{"get":{"operationId":"residential.getCredentials","summary":"Get the credentials","description":"The plan's base proxy username and the password of every proxy of the plan. They are secrets, so reading them needs the `manage` level, and the answer is never cached.\n\nRequires the `api.residential.manage` scope. Every call is recorded in the account's audit log.","tags":["Residential proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialCredentials"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.manage"}},"/api/v1/residential/plans/{plan}/credentials/reset":{"post":{"operationId":"residential.resetCredentials","summary":"Reset the credentials","description":"Issues a new password for every proxy of the plan at once and answers the credentials with it; proxies using the old one stop working. The username does not change. The answer is never cached.\n\nRequires the `api.residential.manage` scope. Every call is recorded in the account's audit log.","tags":["Residential proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialCredentials"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.manage"}},"/api/v1/residential/plans/{plan}/auto-top-up":{"delete":{"operationId":"residential.deleteAutoTopUp","summary":"Remove the auto top-up","description":"Stops topping the plan up automatically. 409 `auto_top_up_blocked` when support turned the rule off: it can only be removed by support.\n\nRequires the `api.residential.manage` scope.","tags":["Residential proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Done."},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.manage"},"get":{"operationId":"residential.getAutoTopUp","summary":"Get the auto top-up","description":"The plan's auto top-up, `null` when it has none, and the limits a rule on the plan must respect.\n\nRequires the `api.residential.read` scope.","tags":["Residential proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialAutoTopUpResponse"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.read"},"put":{"operationId":"residential.setAutoTopUp","summary":"Set the auto top-up","description":"Creates the plan's auto top-up, armed, or replaces the settings of the one it has; `paused` pauses or re-arms it, and left out keeps its status. Whenever the plan's remaining traffic falls to `threshold_gb`, `amount_gb` more is bought and charged without asking to `payment` (the balance, a saved card from GET /api/v1/payment-methods, or the default card when `card_id` is left out); the charges do not count towards this key's monthly spending limit, which is why it needs the `purchase` level. A top-up the card refuses, or one charged to a card that was since removed, fails like one the balance cannot cover. Send every field each time; one left out is cleared, `promo_code` included, except `paused` and `payment`, which the rule keeps. 409 `auto_top_up_disabled` while auto top-ups are switched off for the service (`limits.enabled`), `auto_top_up_blocked` when support turned the rule off, `product_withdrawn` once the plan's product is no longer sold.\n\nRequires the `api.residential.purchase` scope.","tags":["Residential proxies"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialAutoTopUpRequest"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialAutoTopUpResponse"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.purchase"}},"/api/v1/residential/quote":{"post":{"operationId":"residential.quote","summary":"Price traffic","description":"What `POST /orders` with the same body would charge, including discounts, tax and the payment method's fee, or why it cannot be ordered. Nothing is reserved.\n\nRequires the `api.residential.read` scope.","tags":["Residential proxies"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialTrafficQuote"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseQuote"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request is well formed but cannot be carried out; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.read"}},"/api/v1/residential/orders":{"post":{"operationId":"residential.order","summary":"Buy traffic","description":"Buys `traffic_gb` of traffic on a product, charged to the balance or a saved card straight away without asking the customer. You hold at most one plan per product and its `id` is the product's id: the traffic is added to that plan, or the plan is created by the first order. 201 answers the plan; 202 means it is paid and still being delivered, or the bank asked for 3-D Secure (`order.action_url`).\n\nRequires the `api.residential.purchase` scope. Send a unique `Idempotency-Key` per order; repeating it with the same body answers the first order instead of charging again.","tags":["Residential proxies"],"parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value per order, sent again only to retry the same order.","required":true,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialTrafficOrder"}}}},"responses":{"200":{"description":"A repeated `Idempotency-Key`: the order it placed first, with `replayed: true`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialOrderResponse"}}}},"201":{"description":"Paid and delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialOrderResponse"}}}},"202":{"description":"Paid and still being delivered (poll `GET /api/v1/orders/{id}`), or waiting for 3-D Secure at `order.action_url`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResidentialOrderResponse"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The payment was declined; `error` names why and `meta.order` is the failed order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required`, is used from an IP it does not allow, the order would pass the key's monthly spending limit (`spend_limit_exceeded`), or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such product or plan, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`in_progress`: another order of the account is still being placed, retry shortly with the same key; `idempotency_conflict`: the `Idempotency-Key` was already used for a different order; `duplicate_request`: the key was already used and its order is still being recorded, look it up instead of sending it again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The order cannot be placed; `error` names why: `not_purchasable` (with `meta.issues` when the order itself is at fault, e.g. out of stock), `promo_code_invalid`, `amount_too_small` or `payment_rejected`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.residential.purchase"}},"/api/v1/scraping/products":{"get":{"operationId":"scraping.listProducts","summary":"List products","description":"The plans on sale. A `subscription` product grants a credit allowance each cycle for a price per term; `payg` only sets the price of credits bought as needed. Prices carry no currency; `POST /quote` and `POST /plans/{plan}/quote` answer the exact total.\n\nRequires the `api.scraping.read` scope.","tags":["Web scraping"],"parameters":[{"name":"limit","in":"query","description":"How many results to return, 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"How many results to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ScrapingProduct"}},"count":{"type":"integer","format":"int64","description":"How many results match in total."},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["results","count"]}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.read"}},"/api/v1/scraping/products/{product}":{"get":{"operationId":"scraping.getProduct","summary":"Get a product","description":"The product with its allowance, the price of each term and what extra credits cost at its rate. The price per 1,000 credits of a purchase is the step of `credits.steps` with the highest `min_credits` the purchase reaches.\n\nRequires the `api.scraping.read` scope.","tags":["Web scraping"],"parameters":[{"name":"product","in":"path","description":"The product's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingProduct"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.read"}},"/api/v1/scraping/plans":{"get":{"operationId":"scraping.listPlans","summary":"List your plans","description":"Your account holds one scraping plan at most, so the list has 0 or 1 entries. It stays empty until you subscribe or activate the Scraping API in the dashboard.\n\nRequires the `api.scraping.read` scope.","tags":["Web scraping"],"parameters":[{"name":"limit","in":"query","description":"How many results to return, 1–100.","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"How many results to skip.","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ScrapingPlan"}},"count":{"type":"integer","format":"int64","description":"How many results match in total."},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["results","count"]}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.read"}},"/api/v1/scraping/plans/{plan}":{"get":{"operationId":"scraping.getPlan","summary":"Get a plan","description":"The plan with its credit balance, concurrency, current term and credit cycle, and a masked preview of its API key. The key itself is only answered by `GET /plans/{plan}/credentials`.\n\nRequires the `api.scraping.read` scope.","tags":["Web scraping"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingPlanDetail"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.read"}},"/api/v1/scraping/plans/{plan}/credentials":{"get":{"operationId":"scraping.getCredentials","summary":"Get the credentials","description":"The plan's Datafuel Scraping API key, sent as the `X-API-Key` header to the Scraping API. It is a secret, so reading it needs the manage level, and it is answered with `Cache-Control: no-store`. 409 `plan_suspended` while the plan is suspended, `plan_provisioning` while it is still being set up.\n\nRequires the `api.scraping.manage` scope. Every call is recorded in the account's audit log.","tags":["Web scraping"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingCredentials"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.manage"}},"/api/v1/scraping/plans/{plan}/credentials/reset":{"post":{"operationId":"scraping.resetCredentials","summary":"Reset the credentials","description":"Issues a new API key and answers it with `Cache-Control: no-store`; the old key stops working at once, so update every integration that uses it. 409 as for `GET /plans/{plan}/credentials`. 502 `upstream_error`: Datafuel refused and the old key still works. 503 `unavailable`: Datafuel could not be reached and nothing changed, so retry later. 504 `outcome_unknown`: Datafuel did not confirm, the key may have changed, so read the credentials before retrying. 429 `upstream_rate_limited` carries `Retry-After`.\n\nRequires the `api.scraping.manage` scope. Every call is recorded in the account's audit log.","tags":["Web scraping"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingCredentials"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The upstream provider refused the request; nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.manage"}},"/api/v1/scraping/plans/{plan}/auto-top-up":{"delete":{"operationId":"scraping.deleteAutoTopUp","summary":"Remove the auto top-up","description":"Deletes the plan's rule, so no more credits are bought automatically. 404 when the plan has none; 409 `auto_top_up_blocked` while support has blocked the rule.\n\nRequires the `api.scraping.manage` scope.","tags":["Web scraping"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Done."},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.manage"},"get":{"operationId":"scraping.getAutoTopUp","summary":"Get the auto top-up","description":"The plan's auto top-up rule, `null` when none is set, and the limits a rule must respect.\n\nRequires the `api.scraping.read` scope.","tags":["Web scraping"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingAutoTopUpResponse"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.read"},"put":{"operationId":"scraping.setAutoTopUp","summary":"Set the auto top-up","description":"Creates the plan's rule or replaces its settings. `paused` left out keeps the rule's status (a new rule starts `armed`), `true` pauses it and `false` re-arms a paused or suspended rule. While `armed`, it buys `amount_credits` whenever the balance falls to `threshold_credits` or below, charged without asking to `payment` (the balance, a saved card from GET /api/v1/payment-methods, or the default card when `card_id` is left out) and outside this key's monthly spending limit, which is why it needs the purchase level. A top-up the card refuses, or one charged to a card that was since removed, fails like one the balance cannot cover. 409 `auto_top_up_disabled` while auto top-up is turned off (`limits.enabled`), `auto_top_up_blocked` while support has blocked the rule.\n\nRequires the `api.scraping.purchase` scope.","tags":["Web scraping"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingAutoTopUpRequest"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingAutoTopUpResponse"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the resource's current state; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.purchase"}},"/api/v1/scraping/quote":{"post":{"operationId":"scraping.quote","summary":"Price a plan","description":"What `POST /orders` with the same body would charge, including discounts, tax and the payment method's fee, or why it cannot be ordered, e.g. `plan_held` while you already hold a plan. Nothing is reserved. 404 for an unknown product; 422 `promo_code_invalid` for a promo code that cannot be used.\n\nRequires the `api.scraping.read` scope.","tags":["Web scraping"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingNewPlanQuote"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseQuote"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request is well formed but cannot be carried out; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.read"}},"/api/v1/scraping/orders":{"post":{"operationId":"scraping.order","summary":"Subscribe to a plan","description":"Charges the balance or a saved card straight away, without asking the customer, and opens the subscription. 201 answers the plan; 202 means it is paid and still being set up, or the bank asked for 3-D Secure (`order.action_url`). `order.plan_id` is the plan's `id` once it is delivered, null before. You hold one plan at most; while you do, a new one is refused with `plan_held`. 404 for an unknown product.\n\nRequires the `api.scraping.purchase` scope. Send a unique `Idempotency-Key` per order; repeating it with the same body answers the first order instead of charging again.","tags":["Web scraping"],"parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value per order, sent again only to retry the same order.","required":true,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingNewPlanOrder"}}}},"responses":{"200":{"description":"A repeated `Idempotency-Key`: the order it placed first, with `replayed: true`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingOrderResponse"}}}},"201":{"description":"Paid and delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingOrderResponse"}}}},"202":{"description":"Paid and still being delivered (poll `GET /api/v1/orders/{id}`), or waiting for 3-D Secure at `order.action_url`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingOrderResponse"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The payment was declined; `error` names why and `meta.order` is the failed order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required`, is used from an IP it does not allow, the order would pass the key's monthly spending limit (`spend_limit_exceeded`), or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such product or plan, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`in_progress`: another order of the account is still being placed, retry shortly with the same key; `idempotency_conflict`: the `Idempotency-Key` was already used for a different order; `duplicate_request`: the key was already used and its order is still being recorded, look it up instead of sending it again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The order cannot be placed; `error` names why: `not_purchasable` (with `meta.issues` when the order itself is at fault, e.g. out of stock), `promo_code_invalid`, `amount_too_small` or `payment_rejected`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.purchase"}},"/api/v1/scraping/plans/{plan}/quote":{"post":{"operationId":"scraping.quoteAddOn","summary":"Price credits","description":"What `POST /plans/{plan}/orders` with the same body would charge. Credits are priced per 1,000 at the highest step of the plan's product `credits.steps` the amount reaches. 422 `not_purchasable` while credits are not on sale, `promo_code_invalid` for a promo code that cannot be used.\n\nRequires the `api.scraping.read` scope.","tags":["Web scraping"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingAddOnQuote"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseQuote"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required` (or the level in `meta.required_level`), is used from an IP it does not allow, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request is well formed but cannot be carried out; `error` names why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.read"}},"/api/v1/scraping/plans/{plan}/orders":{"post":{"operationId":"scraping.orderAddOn","summary":"Buy credits","description":"Adds credits to the plan's balance, charged straight away. Credits are bought in whole thousands and do not expire, unless a plan you hold lapses. `order.plan_id` is the plan's `id`.\n\nRequires the `api.scraping.purchase` scope. Send a unique `Idempotency-Key` per order; repeating it with the same body answers the first order instead of charging again.","tags":["Web scraping"],"parameters":[{"name":"plan","in":"path","description":"The plan's id.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value per order, sent again only to retry the same order.","required":true,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingAddOnOrder"}}}},"responses":{"200":{"description":"A repeated `Idempotency-Key`: the order it placed first, with `replayed: true`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingOrderResponse"}}}},"201":{"description":"Paid and delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingOrderResponse"}}}},"202":{"description":"Paid and still being delivered (poll `GET /api/v1/orders/{id}`), or waiting for 3-D Secure at `order.action_url`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapingOrderResponse"}}}},"400":{"description":"The request is malformed: `message` maps each invalid field to its problem, or is a sentence when the body cannot be read at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The payment was declined; `error` names why and `meta.order` is the failed order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope named in `meta.required`, is used from an IP it does not allow, the order would pass the key's monthly spending limit (`spend_limit_exceeded`), or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such product or plan, or it does not belong to the key's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`in_progress`: another order of the account is still being placed, retry shortly with the same key; `idempotency_conflict`: the `Idempotency-Key` was already used for a different order; `duplicate_request`: the key was already used and its order is still being recorded, look it up instead of sending it again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The order cannot be placed; `error` names why: `not_purchasable` (with `meta.issues` when the order itself is at fault, e.g. out of stock), `promo_code_invalid`, `amount_too_small` or `payment_rejected`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; retry after the `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something failed on our side and was logged; read the resource again before retrying a change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; nothing was changed, try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Something upstream did not answer in time and the change may still happen; read the resource (or the order) again before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"apiKey":[]}],"x-scope":"api.scraping.purchase"}}},"components":{"schemas":{"DashboardAccountResponse":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"key":{"$ref":"#/components/schemas/DashboardKey","description":"The key making this call."}},"required":["user_id","email","key"]},"DashboardAutoRenewRequest":{"type":"object","properties":{"enabled":{"type":"boolean"},"card_id":{"type":"string","description":"Only with enabled true, for a subscription paid by card: the saved card renewals are charged to from now on. Omitted, a running subscription keeps its card and a cancelled one resumes on its previous card, or the default card when that one is gone.","maxLength":255}},"required":["enabled"]},"DashboardBalanceResponse":{"type":"object","properties":{"available":{"type":"number","description":"What orders paid with method balance can spend."},"currency":{"type":"string","examples":["usd"]}},"required":["available","currency"]},"DashboardCardResponse":{"type":"object","properties":{"id":{"type":"string","description":"Pass it as payment.card_id.","examples":["pm_1QxYz"]},"brand":{"type":"string","examples":["visa"]},"last4":{"type":"string","examples":["4242"]},"exp_month":{"type":"integer","format":"int64"},"exp_year":{"type":"integer","format":"int64"},"default":{"type":"boolean","description":"Charged when payment.card_id is omitted."}},"required":["id","brand","last4","exp_month","exp_year","default"]},"DashboardKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string","description":"The key's public start; the secret is never shown again.","examples":["lc_live_7Qm2Xa9k…"]},"permissions":{"type":"array","description":"read, manage and purchase; read is always granted.","items":{"type":"string"}},"services":{"type":"array","description":"The services the permissions apply to; * is every service, including future ones.","items":{"type":"string"}},"allowed_ips":{"type":"array","description":"The addresses or CIDR ranges the key works from; empty means any.","items":{"type":"string"}},"monthly_limit":{"type":["number","null"],"description":"The most orders placed with the key may spend per calendar month (UTC); null means no limit."},"spent_this_month":{"type":"number"},"expires_at":{"type":["string","null"],"format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","prefix","permissions","services","allowed_ips","monthly_limit","spent_this_month","expires_at","last_used_at","created_at"]},"DashboardPaymentmethodResponse":{"type":"object","properties":{"balance":{"$ref":"#/components/schemas/DashboardBalanceResponse"},"cards":{"type":"array","items":{"$ref":"#/components/schemas/DashboardCardResponse"}}},"required":["balance","cards"]},"DashboardRenewalPayment":{"type":"object","properties":{"method":{"type":"string","enum":["balance","card"]},"card_id":{"type":"string","description":"The saved card renewals are charged to."}},"required":["method"]},"DashboardSubscriptionResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"service":{"type":"string","examples":["static"]},"product":{"type":"string","examples":["isp"]},"plan_id":{"type":["string","null"],"format":"uuid","description":"The plan it renews."},"status":{"type":"string","description":"pending: the first payment is not settled yet; active: renews at period_ends_at; past_due: the last renewal is unpaid and is being retried; cancelled: auto-renew is off and the plan ends at period_ends_at; expired: ended.","enum":["pending","active","past_due","cancelled","expired"]},"auto_renew":{"type":"boolean","description":"Whether the plan renews at period_ends_at."},"period_ends_at":{"type":["string","null"],"format":"date-time","description":"When the current term ends: the next renewal while auto_renew is on, the end of the plan otherwise."},"period_days":{"type":"integer","format":"int64"},"price":{"type":"number","description":"What each renewal costs."},"currency":{"type":"string","examples":["usd"]},"payment":{"description":"What renewals are charged to.","anyOf":[{"$ref":"#/components/schemas/DashboardRenewalPayment"},{"type":"null"}]}},"required":["id","service","product","plan_id","status","auto_renew","period_ends_at","period_days","price","currency","payment"]},"DashboardSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"As on GET /api/v1/orders/{id}.","enum":["pending","requires_action","paid","completed","delivery_failed","failed","expired","refunded"]},"service":{"type":"string","description":"The service that sold it: static, residential, hybrid, server or scraping."},"product":{"type":"string","description":"The product within the service, e.g. isp or dc for static."},"action":{"type":"string","enum":["new","topup","replace"]},"total":{"type":"number"},"currency":{"type":"string","examples":["usd"]},"plan_id":{"type":["string","null"],"format":"uuid","description":"The plan the order delivered or topped up, once known."},"action_url":{"type":["string","null"],"format":"uri","description":"Where the customer completes 3-D Secure, while status is requires_action."},"error":{"description":"Why the payment failed, when status is failed.","anyOf":[{"$ref":"#/components/schemas/PurchaseFailure"},{"type":"null"}]},"created_at":{"type":["string","null"],"format":"date-time"}},"required":["id","status","service","product","action","total","currency","plan_id","action_url","error","created_at"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"A stable, machine-readable code such as `insufficient_scope` or `insufficient_balance`."},"message":{"description":"A human-readable explanation, or for validation errors an object mapping each field to its problem.","anyOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"string"}}]},"meta":{"type":"object","description":"Details that depend on the error, e.g. `required`, `order`, `issues` or `retry_after`."}},"required":["error","message"]},"PurchaseFailure":{"type":"object","properties":{"code":{"type":"string","description":"insufficient_balance: the balance does not cover it; insufficient_funds, card_declined, expired_card, incorrect_cvc: the card was refused; authentication_required: the card wants 3-D Secure, which only the dashboard can do; payment_method_required: there is no saved card; payment_failed: anything else.","enum":["insufficient_balance","insufficient_funds","card_declined","expired_card","incorrect_cvc","authentication_required","payment_method_required","payment_failed"]},"message":{"type":"string"}},"required":["code"]},"PurchaseOrder":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The order's id; poll GET /api/v1/orders/{id} while it is pending, requires_action or paid."},"status":{"type":"string","description":"pending: not charged yet; requires_action: waiting for 3-D Secure at action_url; paid: charged, being delivered; completed: delivered; delivery_failed: charged but the delivery could not be finished, support is alerted and delivers or refunds it; failed: the payment was refused, see error; expired: never paid; refunded: the money went back.","enum":["pending","requires_action","paid","completed","delivery_failed","failed","expired","refunded"]},"service":{"type":"string","description":"The service that sold it: static, residential, hybrid, server or scraping."},"product":{"type":"string","description":"The product within the service, e.g. isp or dc for static."},"action":{"type":"string","enum":["new","topup","replace"]},"total":{"type":"number"},"currency":{"type":"string","examples":["usd"]},"payment":{"description":"How the order was paid: the method only, never the card.","anyOf":[{"$ref":"#/components/schemas/PurchasePayment"},{"type":"null"}]},"plan_id":{"type":["string","null"],"format":"uuid","description":"The plan the order delivered or topped up, once known."},"action_url":{"type":["string","null"],"format":"uri","description":"Where the customer completes 3-D Secure, while status is requires_action."},"error":{"description":"Why the payment failed, when status is failed.","anyOf":[{"$ref":"#/components/schemas/PurchaseFailure"},{"type":"null"}]},"replayed":{"type":"boolean","description":"True when this answers a repeated Idempotency-Key instead of placing a new order."},"created_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"}},"required":["id","status","service","product","action","total","currency","payment","plan_id","action_url","error","created_at","paid_at"]},"PurchasePayment":{"type":"object","properties":{"method":{"type":"string","description":"balance charges the account balance; card charges a saved card without asking the customer.","enum":["balance","card"]},"card_id":{"type":"string","description":"A saved card's id from GET /api/v1/payment-methods; the default card when omitted. Only with method card.","maxLength":255}},"required":["method"]},"PurchaseIssue":{"type":"object","properties":{"code":{"type":"string","description":"Why the order cannot be placed, e.g. insufficient_stock or max_order_size."},"message":{"type":"string"},"field":{"type":"string","description":"The request field the issue is about."},"limit":{"type":["integer","null"],"format":"int64","description":"The most that can be ordered, when the issue is a limit."}},"required":["code"]},"PurchaseQuote":{"type":"object","properties":{"purchasable":{"type":"boolean","description":"Whether the same body can be ordered now."},"issues":{"type":"array","description":"Why it cannot, when purchasable is false.","items":{"$ref":"#/components/schemas/PurchaseIssue"}},"net":{"type":"number","description":"Price before discounts, tax and fees."},"discount":{"type":"number"},"tax":{"type":"number"},"fee":{"type":"number","description":"The payment method's fee."},"total":{"type":"number","description":"What the order will be charged."},"currency":{"type":"string","examples":["usd"]}},"required":["purchasable","net","discount","tax","fee","total","currency"]},"StaticAddOnOrder":{"type":"object","properties":{"replacements":{"type":"integer","format":"int64","description":"How many IP replacements to buy; each one swaps every IP of the plan once.","minimum":1,"maximum":1000},"payment":{"$ref":"#/components/schemas/PurchasePayment"},"promo_code":{"type":"string","description":"A promo code; an invalid one is refused, never silently dropped.","maxLength":64}},"required":["replacements","payment"]},"StaticAddOnQuote":{"type":"object","properties":{"replacements":{"type":"integer","format":"int64","description":"How many IP replacements to buy; each one swaps every IP of the plan once.","minimum":1,"maximum":1000},"payment":{"description":"The payment method, when its fee should be included.","anyOf":[{"$ref":"#/components/schemas/PurchasePayment"},{"type":"null"}]},"promo_code":{"type":"string","description":"A promo code; an invalid one is refused, never silently dropped.","maxLength":64}},"required":["replacements"]},"StaticAuth":{"type":"object","properties":{"mode":{"type":"string","description":"credentials: connect with the plan's username and password (GET /plans/{plan}/credentials); ip: only allowed_ips may connect.","enum":["credentials","ip"]},"allowed_ips":{"type":"array","description":"The addresses allowed in ip mode.","items":{"type":"string"}}},"required":["mode","allowed_ips"]},"StaticAuthRequest":{"type":"object","properties":{"mode":{"type":"string","description":"credentials: connect with the username and password; ip: only allowed_ips may connect.","enum":["credentials","ip"]},"allowed_ips":{"type":"array","description":"Replaces the whole list, at most 20 addresses; ip mode needs at least one.","maxItems":20,"items":{"type":"string","format":"ip"}}},"required":["mode"]},"StaticCredentials":{"type":"object","properties":{"username":{"type":"string","description":"The proxy username, the same on every IP of the plan."},"password":{"type":"string","description":"The proxy password, the same on every IP of the plan."}},"required":["username","password"]},"StaticLocationRequest":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code, from GET /products/{product}.","examples":["US"],"minLength":2,"maxLength":2},"region":{"type":"string","description":"A region within the country; leave it out to take IPs anywhere in the country.","examples":["CA"],"minLength":2,"maxLength":16},"ips":{"type":"integer","format":"int64","description":"How many IPs in this location.","minimum":1}},"required":["country","ips"]},"StaticNewPlanOrder":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","description":"A product id from GET /products."},"period_days":{"type":"integer","format":"int64","description":"One of the product's period_days.","minimum":1},"locations":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/StaticLocationRequest"}},"payment":{"$ref":"#/components/schemas/PurchasePayment"},"promo_code":{"type":"string","description":"A promo code; an invalid one is refused, never silently dropped.","maxLength":64}},"required":["product_id","period_days","locations","payment"]},"StaticNewPlanQuote":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","description":"A product id from GET /products."},"period_days":{"type":"integer","format":"int64","description":"One of the product's period_days.","minimum":1},"locations":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/StaticLocationRequest"}},"payment":{"description":"The payment method, when its fee should be included.","anyOf":[{"$ref":"#/components/schemas/PurchasePayment"},{"type":"null"}]},"promo_code":{"type":"string","description":"A promo code; an invalid one is refused, never silently dropped.","maxLength":64}},"required":["product_id","period_days","locations"]},"StaticOrderResponse":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/PurchaseOrder"},"plan":{"description":"The delivered plan, when the order completed within the call.","anyOf":[{"$ref":"#/components/schemas/StaticPlanDetail"},{"type":"null"}]}},"required":["order"]},"StaticPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid","description":"The product the plan was bought as."},"status":{"type":"string","description":"provisioning: bought, its IPs are still being delivered; active: usable; past_due: the term ended and the renewal is not paid yet, so the proxies refuse connections until it is paid or the plan expires; suspended: switched off by us, e.g. while the account is suspended; expired: ended for good and its IPs released, kept for history.","enum":["provisioning","active","past_due","suspended","expired"]},"ips":{"type":"integer","format":"int64","description":"How many IPs the plan has."},"period_days":{"type":"integer","format":"int64","description":"The plan's term in days."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the current term ends; the proxies stop answering then unless the renewal is paid."},"subscription_id":{"type":["string","null"],"format":"uuid","description":"The subscription that renews it; see GET /api/v1/subscriptions."},"created_at":{"type":"string","format":"date-time"}},"required":["id","product_id","status","ips","period_days","expires_at","subscription_id","created_at"]},"StaticPlanDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid","description":"The product the plan was bought as."},"status":{"type":"string","description":"provisioning: bought, its IPs are still being delivered; active: usable; past_due: the term ended and the renewal is not paid yet, so the proxies refuse connections until it is paid or the plan expires; suspended: switched off by us, e.g. while the account is suspended; expired: ended for good and its IPs released, kept for history.","enum":["provisioning","active","past_due","suspended","expired"]},"ips":{"type":"integer","format":"int64","description":"How many IPs the plan has."},"period_days":{"type":"integer","format":"int64","description":"The plan's term in days."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the current term ends; the proxies stop answering then unless the renewal is paid."},"subscription_id":{"type":["string","null"],"format":"uuid","description":"The subscription that renews it; see GET /api/v1/subscriptions."},"created_at":{"type":"string","format":"date-time"},"auth":{"$ref":"#/components/schemas/StaticAuth"},"replacements_left":{"type":"integer","format":"int64","description":"How many more times POST /plans/{plan}/replace may swap the IPs."},"locations":{"type":"array","items":{"$ref":"#/components/schemas/StaticPlanLocation"}}},"required":["id","product_id","status","ips","period_days","expires_at","subscription_id","created_at","auth","replacements_left","locations"]},"StaticPlanLocation":{"type":"object","properties":{"country":{"type":"string","examples":["US"]},"region":{"type":"string","examples":["CA"]},"ips":{"type":"integer","format":"int64"}},"required":["country","ips"]},"StaticProduct":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"max_ips":{"type":["integer","null"],"format":"int64","description":"The most IPs one order may take; null when the product sets no limit."},"period_days":{"type":"array","description":"The periods, in days, the product can be bought for.","items":{"type":"integer","format":"int64"}}},"required":["id","name","description","max_ips","period_days"]},"StaticProductDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"max_ips":{"type":["integer","null"],"format":"int64","description":"The most IPs one order may take; null when the product sets no limit."},"period_days":{"type":"array","description":"The periods, in days, the product can be bought for.","items":{"type":"integer","format":"int64"}},"locations":{"type":"array","items":{"$ref":"#/components/schemas/StaticProductLocation"}}},"required":["id","name","description","max_ips","period_days","locations"]},"StaticProductLocation":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code.","examples":["US"]},"region":{"type":"string","description":"A region within the country; without it, the order takes IPs anywhere in the country.","examples":["CA"]},"region_name":{"type":"string","examples":["California"]},"stock_level":{"type":"string","description":"out_of_stock: nothing can be ordered here right now.","enum":["high","low","out_of_stock"]},"max_ips":{"type":"integer","format":"int64","description":"The most IPs one order may take here, given the product's limit and the stock; 0 while out of stock."}},"required":["country","stock_level","max_ips"]},"StaticProxiesResponse":{"type":"object","properties":{"username":{"type":"string"},"password":{"type":"string"},"proxies":{"type":"array","items":{"$ref":"#/components/schemas/StaticProxy"}}},"required":["username","password","proxies"]},"StaticProxy":{"type":"object","properties":{"ip":{"type":"string"},"port":{"type":"integer"},"country":{"type":"string"},"region":{"type":"string"}},"required":["ip","port","country"]},"ResidentialAutoTopUp":{"type":"object","properties":{"status":{"type":"string","description":"armed: tops up when needed. paused: waits until PUT sends paused false. suspended: stopped after too many failed top-ups in a row, or because the plan could no longer be topped up; PUT with paused false re-arms it. blocked: turned off by support; it cannot be changed with this API.","enum":["armed","paused","suspended","blocked"]},"reason":{"type":"string","description":"Why it is suspended or blocked."},"threshold_gb":{"type":"integer","format":"int64","description":"Tops up when the plan's remaining traffic falls to this many GB or below."},"amount_gb":{"type":"integer","format":"int64","description":"How many GB each top-up buys."},"max_per_day":{"type":"integer","format":"int64","description":"The most top-ups a day; 0 is limits.max_per_day."},"max_per_month_gb":{"type":"integer","format":"int64","description":"The most GB topped up a month; 0 is limits.max_per_month_gb."},"promo_code":{"type":"string","description":"The promo code for every top-up; removed when it is refused."},"payment":{"$ref":"#/components/schemas/PurchasePayment","description":"What each top-up is charged to."},"last_fired_at":{"type":["string","null"],"format":"date-time","description":"When it last placed a top-up."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["status","threshold_gb","amount_gb","max_per_day","max_per_month_gb","promo_code","payment","last_fired_at","created_at","updated_at"]},"ResidentialAutoTopUpLimits":{"type":"object","properties":{"enabled":{"type":"boolean","description":"false while auto top-ups are switched off for the service: rules are kept but do not fire, and PUT answers 409 auto_top_up_disabled."},"min_threshold_gb":{"type":"integer","format":"int64","description":"The smallest threshold_gb."},"min_amount_gb":{"type":"integer","format":"int64","description":"The smallest amount_gb."},"max_amount_gb":{"type":"integer","format":"int64","description":"The largest amount_gb: the service's limit, or the product's max_traffic_gb when that is lower."},"max_per_day":{"type":["integer","null"],"format":"int64","description":"The daily cap on top-ups of a rule whose max_per_day is 0; null when there is none."},"max_per_month_gb":{"type":["integer","null"],"format":"int64","description":"The monthly cap, in GB, on top-ups of a rule whose max_per_month_gb is 0; null when there is none."}},"required":["enabled","min_threshold_gb","min_amount_gb","max_amount_gb","max_per_day","max_per_month_gb"]},"ResidentialAutoTopUpRequest":{"type":"object","properties":{"threshold_gb":{"type":"integer","format":"int64","description":"Top up when the plan's remaining traffic falls to this many GB or below; at least limits.min_threshold_gb.","minimum":1,"maximum":100000},"amount_gb":{"type":"integer","format":"int64","description":"How many GB each top-up buys, from limits.min_amount_gb to limits.max_amount_gb.","minimum":1,"maximum":100000},"max_per_day":{"type":"integer","format":"int64","description":"The most top-ups a day; 0 or left out for limits.max_per_day.","minimum":0},"max_per_month_gb":{"type":"integer","format":"int64","description":"The most GB topped up a month, at least amount_gb; 0 or left out for limits.max_per_month_gb.","minimum":0,"maximum":100000},"promo_code":{"type":"string","description":"A promo code for every top-up.","maxLength":64},"paused":{"type":["boolean","null"],"description":"true pauses the rule; false re-arms a paused or suspended one. Left out, the rule keeps its status, and a new one starts armed."},"payment":{"description":"What each top-up is charged to. Left out keeps the rule's payment; a new rule charges the balance.","anyOf":[{"$ref":"#/components/schemas/PurchasePayment"},{"type":"null"}]}},"required":["threshold_gb","amount_gb"]},"ResidentialAutoTopUpResponse":{"type":"object","properties":{"rule":{"description":"The plan's auto top-up; null when it has none.","anyOf":[{"$ref":"#/components/schemas/ResidentialAutoTopUp"},{"type":"null"}]},"limits":{"$ref":"#/components/schemas/ResidentialAutoTopUpLimits","description":"What a rule on this plan must respect."}},"required":["rule","limits"]},"ResidentialCredentials":{"type":"object","properties":{"username":{"type":"string","description":"The plan's base proxy username. Each generated proxy extends it with its targeting and session, so connect with the usernames POST /plans/{plan}/proxies answers."},"password":{"type":"string","description":"The password of every proxy of the plan."}},"required":["username","password"]},"ResidentialLocation":{"type":"object","properties":{"code":{"type":"string","description":"The provider's code for the region or city.","examples":["california"]},"name":{"type":"string","examples":["California"]}},"required":["code","name"]},"ResidentialLocations":{"type":"object","properties":{"country":{"type":"string","description":"The country asked for.","examples":["US"]},"regions":{"type":"array","description":"The country's regions; send a code as region.","items":{"$ref":"#/components/schemas/ResidentialLocation"}},"cities":{"type":"array","description":"The country's cities, or only the region's when region was given; send a code as city.","items":{"$ref":"#/components/schemas/ResidentialLocation"}}},"required":["country","regions","cities"]},"ResidentialOrderResponse":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/PurchaseOrder"},"plan":{"description":"The plan the traffic went to, when the order completed within the call.","anyOf":[{"$ref":"#/components/schemas/ResidentialPlanDetail"},{"type":"null"}]}},"required":["order"]},"ResidentialPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The plan's id, which is also the id of the product it was bought as: ordering that product again adds traffic to this plan."},"name":{"type":"string","description":"The product's name; Residential plan once the product is no longer sold."},"status":{"type":"string","description":"provisioning: bought, not usable yet. active: usable. past_due: the term ended and the renewal is not paid yet; access is paused until it is paid or the plan expires. suspended: switched off by us (a staff block, abuse, the account suspended or the provider's block); its proxies do not connect. expired: ended for good, kept for history. A residential plan is usable as soon as it is bought and has no term, so it is only ever active or suspended.","enum":["provisioning","active","past_due","suspended","expired"]},"traffic":{"$ref":"#/components/schemas/ResidentialTraffic"},"subscription_id":{"type":["string","null"],"description":"Always null: a residential plan is paid by traffic, not by a subscription."},"expires_at":{"type":["string","null"],"format":"date-time","description":"Always null: a residential plan has no term."},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","status","traffic","subscription_id","expires_at","created_at"]},"ResidentialPlanCountry":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code.","examples":["US"]},"continent":{"type":"string","description":"The country's continent code.","examples":["NA"]}},"required":["country"]},"ResidentialPlanDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The plan's id, which is also the id of the product it was bought as: ordering that product again adds traffic to this plan."},"name":{"type":"string","description":"The product's name; Residential plan once the product is no longer sold."},"status":{"type":"string","description":"provisioning: bought, not usable yet. active: usable. past_due: the term ended and the renewal is not paid yet; access is paused until it is paid or the plan expires. suspended: switched off by us (a staff block, abuse, the account suspended or the provider's block); its proxies do not connect. expired: ended for good, kept for history. A residential plan is usable as soon as it is bought and has no term, so it is only ever active or suspended.","enum":["provisioning","active","past_due","suspended","expired"]},"traffic":{"$ref":"#/components/schemas/ResidentialTraffic"},"subscription_id":{"type":["string","null"],"description":"Always null: a residential plan is paid by traffic, not by a subscription."},"expires_at":{"type":["string","null"],"format":"date-time","description":"Always null: a residential plan has no term."},"created_at":{"type":"string","format":"date-time"},"countries":{"type":"array","description":"The countries POST /plans/{plan}/proxies accepts; empty once the plan's product is no longer sold, and then the plan cannot generate proxies.","items":{"$ref":"#/components/schemas/ResidentialPlanCountry"}}},"required":["id","name","status","traffic","subscription_id","expires_at","created_at","countries"]},"ResidentialProduct":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"max_traffic_gb":{"type":["integer","null"],"format":"int64","description":"The most GB one order may buy; null when there is no limit."},"tiers":{"type":"array","description":"Your price per GB by order size; the highest tier an order reaches prices all of it.","items":{"$ref":"#/components/schemas/ResidentialTier"}}},"required":["id","name","description","max_traffic_gb","tiers"]},"ResidentialProductCountry":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code.","examples":["US"]},"continent":{"type":"string","description":"The country's continent code.","examples":["NA"]}},"required":["country"]},"ResidentialProductDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"max_traffic_gb":{"type":["integer","null"],"format":"int64","description":"The most GB one order may buy; null when there is no limit."},"tiers":{"type":"array","description":"Your price per GB by order size; the highest tier an order reaches prices all of it.","items":{"$ref":"#/components/schemas/ResidentialTier"}},"countries":{"type":"array","description":"The countries this product's proxies can exit in.","items":{"$ref":"#/components/schemas/ResidentialProductCountry"}}},"required":["id","name","description","max_traffic_gb","tiers","countries"]},"ResidentialProxiesRequest":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 code of one of the plan's countries; required with region or city. Without it, each proxy exits in a random country of the plan.","examples":["US"],"minLength":2,"maxLength":2},"region":{"type":"string","description":"A region code from GET /plans/{plan}/locations: letters, digits and underscores.","maxLength":64},"city":{"type":"string","description":"A city code from GET /plans/{plan}/locations: letters, digits and underscores.","maxLength":64},"rotation":{"type":"string","description":"rotating (the default): the exit IP changes between requests; sticky: each proxy keeps its IP for a session.","enum":["rotating","sticky"]},"session_minutes":{"type":"integer","description":"How long a sticky session keeps its IP, in minutes; only with rotation sticky, the provider's default when left out.","minimum":1,"maximum":1440},"quantity":{"type":"integer","description":"How many proxies to generate.","minimum":1,"maximum":1000},"format":{"type":"string","description":"json (the default), or txt for one host:port:username:password per line.","enum":["json","txt"]}},"required":["quantity"]},"ResidentialProxiesResponse":{"type":"object","properties":{"proxies":{"type":"array","items":{"$ref":"#/components/schemas/ResidentialProxy"}}},"required":["proxies"]},"ResidentialProxy":{"type":"object","properties":{"host":{"type":"string","description":"The gateway for the proxy's country."},"port":{"type":"integer","format":"int64"},"username":{"type":"string","description":"The plan's base username with the proxy's targeting and session; use it as it is."},"password":{"type":"string","description":"The plan's proxy password."},"country":{"type":"string","description":"The country the proxy exits in.","examples":["US"]}},"required":["host","port","username","password","country"]},"ResidentialTier":{"type":"object","properties":{"min_gb":{"type":"integer","format":"int64","description":"The order size, in GB, from which this price applies."},"price_per_gb":{"type":"number","description":"The price of one GB before discounts, tax and fees, in the currency POST /quote answers with."}},"required":["min_gb","price_per_gb"]},"ResidentialTraffic":{"type":"object","properties":{"total_gb":{"type":"number","description":"All the traffic the plan has had, in GB: used_gb plus remaining_gb."},"used_gb":{"type":"number","description":"Traffic used, in GB."},"remaining_gb":{"type":"number","description":"Traffic left, in GB; add more by ordering the same product again (POST /orders) or with an auto top-up."},"updated_at":{"type":["string","null"],"format":"date-time","description":"When the provider last counted the traffic; null before its first count."}},"required":["total_gb","used_gb","remaining_gb","updated_at"]},"ResidentialTrafficOrder":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","description":"A product id from GET /products."},"traffic_gb":{"type":"integer","format":"int64","description":"How many GB of traffic to buy; at most the product's max_traffic_gb.","minimum":1,"maximum":100000},"payment":{"$ref":"#/components/schemas/PurchasePayment"},"promo_code":{"type":"string","description":"A promo code; an invalid one is refused, never silently dropped.","maxLength":64}},"required":["product_id","traffic_gb","payment"]},"ResidentialTrafficQuote":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","description":"A product id from GET /products."},"traffic_gb":{"type":"integer","format":"int64","description":"How many GB of traffic to buy; at most the product's max_traffic_gb.","minimum":1,"maximum":100000},"payment":{"description":"The payment method, when its fee should be included.","anyOf":[{"$ref":"#/components/schemas/PurchasePayment"},{"type":"null"}]},"promo_code":{"type":"string","description":"A promo code; an invalid one is refused, never silently dropped.","maxLength":64}},"required":["product_id","traffic_gb"]},"ResidentialUsage":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"timezone":{"type":"string","description":"The time zone the points are laid out in.","examples":["Europe/Warsaw"]},"requests":{"type":"integer","format":"int64","description":"Requests in the window."},"traffic_gb":{"type":"number","description":"Traffic in the window, in GB."},"points":{"type":"array","items":{"$ref":"#/components/schemas/ResidentialUsagePoint"}}},"required":["from","to","timezone","requests","traffic_gb","points"]},"ResidentialUsagePoint":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"requests":{"type":"integer","format":"int64"},"traffic_gb":{"type":"number","description":"Traffic in GB."}},"required":["at","requests","traffic_gb"]},"ScrapingAddOnOrder":{"type":"object","properties":{"credits":{"type":"integer","format":"int64","description":"Credits to add, in whole thousands.","examples":[50000],"minimum":1000,"maximum":1000000000},"payment":{"$ref":"#/components/schemas/PurchasePayment"},"promo_code":{"type":"string","description":"A promo code; an invalid one is refused, never silently dropped.","maxLength":64}},"required":["credits","payment"]},"ScrapingAddOnQuote":{"type":"object","properties":{"credits":{"type":"integer","format":"int64","description":"Credits to add, in whole thousands.","examples":[50000],"minimum":1000,"maximum":1000000000},"payment":{"description":"The payment method, when its fee should be included.","anyOf":[{"$ref":"#/components/schemas/PurchasePayment"},{"type":"null"}]},"promo_code":{"type":"string","description":"A promo code; an invalid one is refused, never silently dropped.","maxLength":64}},"required":["credits"]},"ScrapingAllowance":{"type":"object","properties":{"credits":{"type":"integer","format":"int64","description":"Credits granted each cycle."},"cycle_days":{"type":"integer","format":"int64","description":"How many days a credit cycle lasts."},"concurrency":{"type":"integer","format":"int64","description":"How many requests may run at once."}},"required":["credits","cycle_days","concurrency"]},"ScrapingAutoTopUp":{"type":"object","properties":{"status":{"type":"string","description":"armed: buys credits when the balance falls to threshold_credits; paused: paused by you; suspended: stopped after top-ups failed repeatedly, PUT paused false to re-arm it; blocked: stopped by support.","enum":["armed","paused","suspended","blocked"]},"reason":{"type":"string","description":"Why the rule is suspended or blocked."},"threshold_credits":{"type":"integer","format":"int64","description":"Credits are bought when the balance falls to this many or below."},"amount_credits":{"type":"integer","format":"int64","description":"Credits bought each time, in whole thousands."},"max_per_day":{"type":"integer","format":"int64","description":"The most top-ups per UTC day; 0 means limits.max_per_day."},"promo_code":{"type":"string","description":"Applied to every top-up; dropped once it is refused."},"payment":{"$ref":"#/components/schemas/PurchasePayment","description":"What each top-up is charged to."},"last_fired_at":{"type":["string","null"],"format":"date-time","description":"When credits were last ordered."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["status","threshold_credits","amount_credits","max_per_day","promo_code","payment","last_fired_at","created_at","updated_at"]},"ScrapingAutoTopUpLimits":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether auto top-ups run at all; while false, setting a rule answers 409 auto_top_up_disabled."},"min_threshold_credits":{"type":"integer","format":"int64","description":"The lowest threshold_credits a rule may set."},"min_amount_credits":{"type":"integer","format":"int64","description":"The fewest credits one top-up may buy."},"max_amount_credits":{"type":"integer","format":"int64","description":"The most credits one top-up may buy."},"max_per_day":{"type":"integer","format":"int64","description":"The daily limit of a rule whose max_per_day is 0."}},"required":["enabled","min_threshold_credits","min_amount_credits","max_amount_credits","max_per_day"]},"ScrapingAutoTopUpRequest":{"type":"object","properties":{"threshold_credits":{"type":"integer","format":"int64","description":"Buy credits when the balance falls to this many or below; at least limits.min_threshold_credits.","examples":[5000],"minimum":0},"amount_credits":{"type":"integer","format":"int64","description":"Credits to buy each time, in whole thousands, between limits.min_amount_credits and limits.max_amount_credits.","examples":[50000],"minimum":1000},"max_per_day":{"type":"integer","format":"int64","description":"The most top-ups per UTC day; 0 or left out for limits.max_per_day.","minimum":0,"maximum":100},"promo_code":{"type":"string","description":"A promo code applied to every top-up; dropped once it is refused.","maxLength":64},"paused":{"type":["boolean","null"],"description":"Left out keeps the rule's status (a new rule starts armed); true pauses it; false re-arms a paused or suspended rule."},"payment":{"description":"What each top-up is charged to. Left out keeps the rule's payment; a new rule charges the balance.","anyOf":[{"$ref":"#/components/schemas/PurchasePayment"},{"type":"null"}]}},"required":["amount_credits"]},"ScrapingAutoTopUpResponse":{"type":"object","properties":{"rule":{"description":"null when the plan has no auto top-up.","anyOf":[{"$ref":"#/components/schemas/ScrapingAutoTopUp"},{"type":"null"}]},"limits":{"$ref":"#/components/schemas/ScrapingAutoTopUpLimits"}},"required":["rule","limits"]},"ScrapingConcurrency":{"type":"object","properties":{"current":{"type":"integer","format":"int64","description":"Requests running now."},"limit":{"type":"integer","format":"int64","description":"The most requests that may run at once."}},"required":["current","limit"]},"ScrapingCredentials":{"type":"object","properties":{"api_key":{"type":"string","description":"The Datafuel Scraping API key, sent as the X-API-Key header."},"rotated_at":{"type":["string","null"],"format":"date-time","description":"When the key last changed; null if it never has."}},"required":["api_key","rotated_at"]},"ScrapingCreditRate":{"type":"object","properties":{"steps":{"type":"array","description":"A purchase is priced per 1,000 credits at the highest step whose min_credits it reaches.","items":{"$ref":"#/components/schemas/ScrapingCreditStep"}}},"required":["steps"]},"ScrapingCreditStep":{"type":"object","properties":{"min_credits":{"type":"integer","format":"int64","description":"The smallest purchase this step prices, in credits.","examples":[100000]},"per_thousand":{"type":"number","description":"The price of 1,000 credits."}},"required":["min_credits","per_thousand"]},"ScrapingCredits":{"type":"object","properties":{"balance":{"type":["integer","null"],"format":"int64","description":"Credits left to spend; null until the balance has been read once."},"used_24h":{"type":["integer","null"],"format":"int64","description":"Credits spent in the last 24 hours; null while usage cannot be read."},"stale":{"type":"boolean","description":"True when balance is the last known figure rather than a live one."}},"required":["balance","used_24h","stale"]},"ScrapingCycle":{"type":"object","properties":{"credits":{"type":"integer","format":"int64","description":"Credits the cycle grants."},"used":{"type":["integer","null"],"format":"int64","description":"Credits spent this cycle; null while usage cannot be read."},"started_at":{"type":["string","null"],"format":"date-time","description":"When the cycle started; null until known."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When the next cycle starts; null until known."}},"required":["credits","used","started_at","resets_at"]},"ScrapingNewPlanOrder":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","description":"A subscription product's id from GET /products."},"period_days":{"type":"integer","format":"int64","description":"The period_days of one of the product's prices.","minimum":1},"payment":{"$ref":"#/components/schemas/PurchasePayment"},"promo_code":{"type":"string","description":"A promo code; an invalid one is refused, never silently dropped.","maxLength":64}},"required":["product_id","period_days","payment"]},"ScrapingNewPlanQuote":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","description":"A subscription product's id from GET /products."},"period_days":{"type":"integer","format":"int64","description":"The period_days of one of the product's prices.","minimum":1},"payment":{"description":"The payment method, when its fee should be included.","anyOf":[{"$ref":"#/components/schemas/PurchasePayment"},{"type":"null"}]},"promo_code":{"type":"string","description":"A promo code; an invalid one is refused, never silently dropped.","maxLength":64}},"required":["product_id","period_days"]},"ScrapingOrderResponse":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/PurchaseOrder"},"plan":{"description":"The plan, when the order completed within the call.","anyOf":[{"$ref":"#/components/schemas/ScrapingPlanDetail"},{"type":"null"}]}},"required":["order"]},"ScrapingPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Your scraping account's id, the {plan} of every /plans/{plan} route."},"product_id":{"type":["string","null"],"format":"uuid","description":"The product you subscribe to, else the payg product your credits are priced at; null when there is neither."},"status":{"type":"string","description":"provisioning: the account, or the subscription just bought, is still being set up and its credits are not granted yet; active: usable; past_due: the paid term ended and the renewal is not paid yet, so no new credit cycle starts, and the subscription ends unless it is paid soon; suspended: switched off by support, the API key is withheld; expired: not used here, a plan whose subscription ended stays usable on pay-as-you-go credits.","enum":["provisioning","active","past_due","suspended","expired"]},"subscription_id":{"type":["string","null"],"format":"uuid","description":"The billing subscription that renews the plan, see GET /api/v1/subscriptions; null on payg or when it does not renew through one."},"period_days":{"type":["integer","null"],"format":"int64","description":"The term each payment covers, in days; null on payg."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the paid term ends, plus a few hours for the renewal payment to settle; null on payg."},"cycle":{"description":"The subscription's current credit cycle; null on payg or while the plan's allowance cannot be read.","anyOf":[{"$ref":"#/components/schemas/ScrapingCycle"},{"type":"null"}]},"credits":{"$ref":"#/components/schemas/ScrapingCredits"},"concurrency":{"description":"null while the account's live figures cannot be read.","anyOf":[{"$ref":"#/components/schemas/ScrapingConcurrency"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","product_id","status","subscription_id","period_days","expires_at","cycle","credits","concurrency","created_at"]},"ScrapingPlanDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Your scraping account's id, the {plan} of every /plans/{plan} route."},"product_id":{"type":["string","null"],"format":"uuid","description":"The product you subscribe to, else the payg product your credits are priced at; null when there is neither."},"status":{"type":"string","description":"provisioning: the account, or the subscription just bought, is still being set up and its credits are not granted yet; active: usable; past_due: the paid term ended and the renewal is not paid yet, so no new credit cycle starts, and the subscription ends unless it is paid soon; suspended: switched off by support, the API key is withheld; expired: not used here, a plan whose subscription ended stays usable on pay-as-you-go credits.","enum":["provisioning","active","past_due","suspended","expired"]},"subscription_id":{"type":["string","null"],"format":"uuid","description":"The billing subscription that renews the plan, see GET /api/v1/subscriptions; null on payg or when it does not renew through one."},"period_days":{"type":["integer","null"],"format":"int64","description":"The term each payment covers, in days; null on payg."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the paid term ends, plus a few hours for the renewal payment to settle; null on payg."},"cycle":{"description":"The subscription's current credit cycle; null on payg or while the plan's allowance cannot be read.","anyOf":[{"$ref":"#/components/schemas/ScrapingCycle"},{"type":"null"}]},"credits":{"$ref":"#/components/schemas/ScrapingCredits"},"concurrency":{"description":"null while the account's live figures cannot be read.","anyOf":[{"$ref":"#/components/schemas/ScrapingConcurrency"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"api_key_preview":{"type":"string","description":"The API key with all but its first and last four characters masked; GET /plans/{plan}/credentials reveals it."}},"required":["id","product_id","status","subscription_id","period_days","expires_at","cycle","credits","concurrency","created_at","api_key_preview"]},"ScrapingPrice":{"type":"object","properties":{"period_days":{"type":"integer","format":"int64","description":"The term, in days."},"price":{"type":"number","description":"The price of one term before discounts and tax, in the currency POST /quote answers."}},"required":["period_days","price"]},"ScrapingProduct":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","description":"subscription: a credit allowance granted each cycle for a price per term; payg: no allowance, credits are bought as needed at the credits rate.","enum":["subscription","payg"]},"name":{"type":"string"},"tagline":{"type":"string"},"description":{"type":"string"},"allowance":{"description":"What a subscription grants; null for payg.","anyOf":[{"$ref":"#/components/schemas/ScrapingAllowance"},{"type":"null"}]},"prices":{"type":"array","description":"The terms the product can be bought for, each with its price; empty for payg.","items":{"$ref":"#/components/schemas/ScrapingPrice"}},"credits":{"description":"What extra credits cost at this product's rate, with your account's own prices applied; null when it sells none.","anyOf":[{"$ref":"#/components/schemas/ScrapingCreditRate"},{"type":"null"}]}},"required":["id","type","name","tagline","description","allowance","prices","credits"]}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from the dashboard's Settings → API keys, sent as `Authorization: Bearer <key>`."}}}}