{ "openapi": "3.0.3", "info": { "title": "PreProx Marketplace API", "version": "1.0.0", "description": "API for static marketplace proxy leases only: each lease period is 24 hours with unlimited proxy bandwidth, subject to the acceptable-use policy. Shared and private plans, with Mobile or WiFi inventory, depend on availability. This API does not cover GB-based residential or mobile data packages, SMS, or phone-number products. A PreProx bearer key is required. Purchases and billable 24-hour auto-renewal periods use your existing USD wallet balance at PreProx marketplace prices. API key expiry (1, 3, 6, or 12 months, or Never) controls authentication only and does not extend a lease. API request rate limits are separate from proxy bandwidth: limits apply per key, across all keys belonging to one account, and per client IP before authentication. Follow Retry-After on HTTP 429." }, "servers": [ { "url": "https://preprox.com/api/v1/marketplace", "description": "PreProx Marketplace API" } ], "security": [ { "marketplaceKey": [] } ], "tags": [ { "name": "Marketplace", "description": "Account, static 24-hour marketplace proxy discovery, quotes and purchases. Proxy bandwidth is unlimited, subject to the acceptable-use policy; GB-based data packages, SMS and phone-number products are outside this API." }, { "name": "Lease management", "description": "Account-owned lease details and lifecycle." } ], "paths": { "/account": { "get": { "summary": "Read your account and wallet", "operationId": "getAccount", "tags": [ "Marketplace" ], "description": "Requires marketplace:read.", "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "The request limit per minute for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Requests remaining for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Limit": { "description": "The request limit per minute shared by all keys of the account.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Remaining": { "description": "Requests remaining across all keys of the account.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } } }, "401": { "description": "Missing, invalid, expired, or revoked key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key ability or account access denied.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Respect Retry-After.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Marketplace operation unavailable. No private upstream detail is exposed.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Marketplace API requests are paused by the administrator.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/proxies": { "get": { "summary": "Discover marketplace inventory", "operationId": "listProxies", "tags": [ "Marketplace" ], "description": "Requires marketplace:read. Discover shared and private static marketplace proxy plans with 24-hour lease periods and unlimited proxy bandwidth, subject to the acceptable-use policy. Mobile (cell) and WiFi (wifi) availability varies. GB-based data packages, SMS and phone-number products are outside this API.", "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "The request limit per minute for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Requests remaining for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Limit": { "description": "The request limit per minute shared by all keys of the account.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Remaining": { "description": "Requests remaining across all keys of the account.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryResponse" } } } }, "401": { "description": "Missing, invalid, expired, or revoked key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key ability or account access denied.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Respect Retry-After.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Marketplace operation unavailable. No private upstream detail is exposed.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Marketplace API requests are paused by the administrator.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid request fields or missing Idempotency-Key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "example": "US" }, "description": "" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "" }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "" }, { "name": "zip", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 20 } }, { "name": "isp", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 150 }, "description": "" }, { "name": "connection_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "wifi", "cell" ] }, "description": "" }, { "name": "plan", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "shared", "private" ] }, "description": "" }, { "name": "min_stars", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5 }, "description": "" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{1,30}$" }, "description": "Use meta.next_cursor from the previous response." } ] } }, "/proxies/{proxy_id}": { "get": { "summary": "Read current proxy details", "operationId": "getProxy", "tags": [ "Marketplace" ], "description": "Requires marketplace:read. Read an available static marketplace proxy and its shared/private 24-hour plans. Proxy bandwidth is unlimited, subject to the acceptable-use policy.", "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "The request limit per minute for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Requests remaining for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Limit": { "description": "The request limit per minute shared by all keys of the account.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Remaining": { "description": "Requests remaining across all keys of the account.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyResponse" } } } }, "401": { "description": "Missing, invalid, expired, or revoked key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key ability or account access denied.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Respect Retry-After.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Marketplace operation unavailable. No private upstream detail is exposed.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Marketplace API requests are paused by the administrator.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by the account.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quote, price, purchase, or lease state conflict. Inspect error.code.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "proxy_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^px_" } } ] } }, "/quotes": { "post": { "summary": "Create a five-minute purchase quote", "operationId": "createQuote", "tags": [ "Marketplace" ], "description": "Requires marketplace:write. A quote belongs to its account, expires in five minutes, and does not reserve inventory. Quotes are for one 24-hour static proxy lease period with unlimited proxy bandwidth, subject to the acceptable-use policy. The five-minute quote expiry is the checkout deadline, not the lease duration.", "responses": { "201": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "The request limit per minute for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Requests remaining for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Limit": { "description": "The request limit per minute shared by all keys of the account.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Remaining": { "description": "Requests remaining across all keys of the account.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "401": { "description": "Missing, invalid, expired, or revoked key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key ability or account access denied.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Respect Retry-After.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Marketplace operation unavailable. No private upstream detail is exposed.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Marketplace API requests are paused by the administrator.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by the account.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quote, price, purchase, or lease state conflict. Inspect error.code.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid request fields or missing Idempotency-Key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuote" } } } } } }, "/leases": { "get": { "summary": "List your leases", "operationId": "listLeases", "tags": [ "Lease management" ], "description": "Requires marketplace:read.", "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "The request limit per minute for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Requests remaining for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Limit": { "description": "The request limit per minute shared by all keys of the account.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Remaining": { "description": "Requests remaining across all keys of the account.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeasesResponse" } } } }, "401": { "description": "Missing, invalid, expired, or revoked key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key ability or account access denied.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Respect Retry-After.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Marketplace operation unavailable. No private upstream detail is exposed.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Marketplace API requests are paused by the administrator.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid request fields or missing Idempotency-Key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "description": "" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ] }, "post": { "summary": "Purchase a quoted marketplace lease", "operationId": "purchaseLease", "tags": [ "Marketplace" ], "description": "Requires marketplace:write. Debits the account wallet once. Price and availability are checked again. A repeated account/key/body returns the existing lease with Idempotency-Replayed: true. A changed body or consumed quote returns 409. An uncertain checkout must not be retried with a new key. One purchase buys a 24-hour static proxy lease period with unlimited proxy bandwidth, subject to the acceptable-use policy. It does not buy a GB data balance or SMS service.", "responses": { "201": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Idempotency-Replayed": { "description": "true for a completed replay; false for a new purchase.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, "X-RateLimit-Limit": { "description": "The request limit per minute for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Requests remaining for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Limit": { "description": "The request limit per minute shared by all keys of the account.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Remaining": { "description": "Requests remaining across all keys of the account.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseResponse" } } } }, "401": { "description": "Missing, invalid, expired, or revoked key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key ability or account access denied.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Respect Retry-After.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Marketplace operation unavailable. No private upstream detail is exposed.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Marketplace API requests are paused by the administrator.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by the account.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quote, price, purchase, or lease state conflict. Inspect error.code.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid request fields or missing Idempotency-Key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient account wallet balance.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "example": "order-UNIQUE_ORDER_ID", "pattern": "^[A-Za-z0-9._:-]{8,128}$" }, "description": "8\u2013128 letters, digits, dots, underscores, colons or hyphens. Persist one key with each purchase body. Reuse both on retries." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseLease" } } } } } }, "/leases/{lease_id}": { "get": { "summary": "Read an owned lease", "operationId": "getLease", "tags": [ "Lease management" ], "description": "Requires marketplace:read.", "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "The request limit per minute for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Requests remaining for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Limit": { "description": "The request limit per minute shared by all keys of the account.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Remaining": { "description": "Requests remaining across all keys of the account.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseResponse" } } } }, "401": { "description": "Missing, invalid, expired, or revoked key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key ability or account access denied.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Respect Retry-After.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Marketplace operation unavailable. No private upstream detail is exposed.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Marketplace API requests are paused by the administrator.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by the account.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "lease_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ] }, "delete": { "summary": "Cancel and refund an eligible lease", "operationId": "refundLease", "tags": [ "Lease management" ], "description": "Requires marketplace:write. Checks live usage and allows only active, unused leases. Fails closed when usage cannot be verified. A completed cancellation never creates a second wallet credit. Repeated cancellation of an already cancelled lease returns 200 without another credit. An uncertain cancellation returns 409 refund_pending on later attempts and requires support reconciliation.", "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "The request limit per minute for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Requests remaining for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Limit": { "description": "The request limit per minute shared by all keys of the account.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Remaining": { "description": "Requests remaining across all keys of the account.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseResponse" } } } }, "401": { "description": "Missing, invalid, expired, or revoked key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key ability or account access denied.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Respect Retry-After.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Marketplace operation unavailable. No private upstream detail is exposed.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Marketplace API requests are paused by the administrator.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by the account.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quote, price, purchase, or lease state conflict. Inspect error.code.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "lease_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ] } }, "/leases/{lease_id}/refresh": { "post": { "summary": "Refresh status, expiry, usage, and renewal", "operationId": "refreshLease", "tags": [ "Lease management" ], "description": "Requires marketplace:write.", "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "The request limit per minute for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Requests remaining for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Limit": { "description": "The request limit per minute shared by all keys of the account.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Remaining": { "description": "Requests remaining across all keys of the account.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseResponse" } } } }, "401": { "description": "Missing, invalid, expired, or revoked key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key ability or account access denied.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Respect Retry-After.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Marketplace operation unavailable. No private upstream detail is exposed.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Marketplace API requests are paused by the administrator.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by the account.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quote, price, purchase, or lease state conflict. Inspect error.code.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "lease_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ] } }, "/leases/{lease_id}/auto-renew": { "patch": { "summary": "Set lease auto-renew", "operationId": "setLeaseAutoRenew", "tags": [ "Lease management" ], "description": "Requires marketplace:write. Enabling authorizes wallet charges when the lease renews. An observed owed renewal is settled before changing the setting. Insufficient balance returns 402 and leaves the setting unchanged. Each renewal is another billable 24-hour lease period. API key expiry or revocation does not extend the lease or change its auto-renew setting.", "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "The request limit per minute for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Requests remaining for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Limit": { "description": "The request limit per minute shared by all keys of the account.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Remaining": { "description": "Requests remaining across all keys of the account.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseResponse" } } } }, "401": { "description": "Missing, invalid, expired, or revoked key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key ability or account access denied.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Respect Retry-After.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Marketplace operation unavailable. No private upstream detail is exposed.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Marketplace API requests are paused by the administrator.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by the account.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quote, price, purchase, or lease state conflict. Inspect error.code.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid request fields or missing Idempotency-Key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient wallet funds to settle a renewal. The auto-renew setting remains unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "lease_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRenew" } } } } } }, "/leases/{lease_id}/whitelist": { "put": { "summary": "Set the lease IP whitelist", "operationId": "setLeaseWhitelist", "tags": [ "Lease management" ], "description": "Requires marketplace:write.", "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "The request limit per minute for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Requests remaining for this key.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Limit": { "description": "The request limit per minute shared by all keys of the account.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Account-Remaining": { "description": "Requests remaining across all keys of the account.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseResponse" } } } }, "401": { "description": "Missing, invalid, expired, or revoked key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key ability or account access denied.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Respect Retry-After.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Marketplace operation unavailable. No private upstream detail is exposed.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Marketplace API requests are paused by the administrator.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by the account.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quote, price, purchase, or lease state conflict. Inspect error.code.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid request fields or missing Idempotency-Key.", "headers": { "X-Request-ID": { "description": "Request identifier for support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "lease_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Whitelist" } } } } } } }, "components": { "securitySchemes": { "marketplaceKey": { "type": "http", "scheme": "bearer", "bearerFormat": "PreProx marketplace key", "description": "A scoped key created in the dashboard or issued by an administrator for an active, verified account. Keep it server-side. Key expiry (1, 3, 6, or 12 calendar months, or Never) controls authentication only and does not change a 24-hour lease or its auto-renew setting." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "validation_failed" }, "message": { "type": "string" }, "details": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "code", "message" ] }, "request_id": { "type": "string", "format": "uuid" } }, "required": [ "error", "request_id" ] }, "Account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "wallet_balance": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "0.42", "description": "USD decimal amount, represented as a string." }, "currency": { "type": "string", "enum": [ "USD" ] } }, "required": [ "id", "name", "email", "wallet_balance", "currency" ] }, "Location": { "type": "object", "properties": { "country_code": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true }, "isp": { "type": "string", "nullable": true } } }, "Plan": { "type": "object", "properties": { "available": { "type": "boolean" }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "0.42", "description": "USD decimal amount, represented as a string." }, "currency": { "type": "string", "enum": [ "USD" ] }, "duration_hours": { "type": "integer", "example": 24, "description": "Lease duration in hours: 24 per purchase or renewal period. Independent of API key expiry." } }, "required": [ "available", "amount", "currency", "duration_hours" ], "description": "A shared or private static marketplace proxy plan for one 24-hour lease period. Proxy bandwidth is unlimited during the period, subject to the acceptable-use policy; this is not a GB-based data package." }, "Proxy": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^px_", "example": "px_OPAQUE_ID" }, "ip": { "type": "string", "description": "Masked inventory IP address.", "example": "192.0.2.*", "nullable": true }, "location": { "$ref": "#/components/schemas/Location" }, "connection_type": { "type": "string", "example": "wifi", "description": "WiFi (wifi) or Mobile (cell) marketplace connection, subject to inventory availability. These are static proxy leases, not GB-based data packages." }, "stars": { "type": "number", "minimum": 0, "maximum": 5 }, "plans": { "type": "object", "properties": { "shared": { "$ref": "#/components/schemas/Plan" }, "private": { "$ref": "#/components/schemas/Plan" } }, "required": [ "shared", "private" ] } }, "required": [ "id", "ip", "location", "connection_type", "stars", "plans" ] }, "Quote": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^q_", "example": "q_OPAQUE_QUOTE" }, "proxy_id": { "type": "string", "pattern": "^px_" }, "plan": { "type": "string", "enum": [ "shared", "private" ] }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "0.42", "description": "USD decimal amount, represented as a string." }, "currency": { "type": "string", "enum": [ "USD" ] }, "duration_hours": { "type": "integer", "example": 24, "description": "Quoted static proxy lease period in hours: 24. The quote itself expires after five minutes." }, "expires_at": { "type": "string", "format": "date-time", "description": "Checkout deadline for this quote; not the expiry of the purchased 24-hour lease or API key." } }, "required": [ "id", "proxy_id", "plan", "amount", "currency", "duration_hours", "expires_at" ] }, "Connection": { "type": "object", "properties": { "host": { "type": "string", "nullable": true }, "port": { "type": "integer", "nullable": true }, "username": { "type": "string", "nullable": true }, "password": { "type": "string", "nullable": true }, "whitelist_ip": { "type": "string", "nullable": true }, "no_auth_host": { "type": "string", "nullable": true }, "no_auth_port": { "type": "integer", "nullable": true } }, "required": [ "host", "port", "username", "password", "whitelist_ip", "no_auth_host", "no_auth_port" ] }, "Lease": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "proxy_id": { "type": "string", "pattern": "^px_", "nullable": true }, "status": { "type": "string", "example": "active" }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "0.42", "description": "USD decimal amount, represented as a string." }, "currency": { "type": "string", "enum": [ "USD" ] }, "starts_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiry of the current lease period; independent of API key expiry." }, "auto_renew": { "type": "boolean", "description": "Whether additional billable 24-hour lease periods are authorized. API key expiry or revocation does not change this setting." }, "used_bytes": { "type": "integer", "minimum": 0, "description": "Observed proxy usage for management and refund eligibility. This is not a GB quota or a per-GB charge; proxy bandwidth is unlimited during the lease period, subject to the acceptable-use policy." }, "connection": { "$ref": "#/components/schemas/Connection" } }, "required": [ "id", "proxy_id", "status", "amount", "currency", "starts_at", "expires_at", "auto_renew", "used_bytes", "connection" ], "description": "An account-owned static marketplace proxy lease. Each purchased or renewed period is 24 hours with unlimited proxy bandwidth, subject to the acceptable-use policy." }, "AccountResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Account" } }, "required": [ "data" ] }, "ProxyResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Proxy" } }, "required": [ "data" ] }, "QuoteResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quote" } }, "required": [ "data" ] }, "LeaseResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Lease" } }, "required": [ "data" ] }, "InventoryResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Proxy" } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": "string", "description": "Pass unchanged as cursor; null ends pagination.", "nullable": true }, "total": { "type": "integer", "nullable": true } }, "required": [ "next_cursor", "total" ] } }, "required": [ "data", "meta" ] }, "LeasesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lease" } }, "meta": { "type": "object", "properties": { "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } }, "additionalProperties": true } }, "required": [ "data", "meta" ] }, "CreateQuote": { "type": "object", "properties": { "proxy_id": { "type": "string", "pattern": "^px_", "example": "px_OPAQUE_ID" }, "plan": { "type": "string", "enum": [ "shared", "private" ] } }, "required": [ "proxy_id", "plan" ], "additionalProperties": false }, "PurchaseLease": { "type": "object", "properties": { "quote_id": { "type": "string", "pattern": "^q_", "example": "q_OPAQUE_QUOTE" }, "max_price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$", "example": "0.42", "description": "Maximum authorized USD charge, 0.01\u2013999999.99; up to two decimal places and a leading digit are required. Purchase must also match the quote price." } }, "required": [ "quote_id", "max_price" ], "additionalProperties": false }, "AutoRenew": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "Whitelist": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP address to allow for IP authentication.", "example": "203.0.113.10" } }, "required": [ "ip" ], "additionalProperties": false } } } }