{
  "openapi": "3.0.3",
  "info": {
    "title": "NinjaProxy Customer API",
    "version": "2026-05-05",
    "description": "Current customer-facing NinjaProxy API derived from the live public-api router in services/control-plane/cmd/public-api/main.go. This spec covers the legacy apiKey compatibility surface under /api/v1 and the authenticated account API under /v2. It intentionally excludes stale routes that are not currently served.",
    "license": {
      "name": "Proprietary"
    }
  },
  "security": [],
  "servers": [
    {
      "url": "https://api.ninjasproxy.com",
      "description": "Production"
    },
    {
      "url": "https://api.staging.ninjasproxy.dev",
      "description": "Staging"
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "Liveness and readiness probes."
    },
    {
      "name": "Auth",
      "description": "Login and password-reset flows."
    },
    {
      "name": "Account",
      "description": "Authenticated account profile and portal state."
    },
    {
      "name": "Usage",
      "description": "Historical and live traffic usage."
    },
    {
      "name": "Proxy",
      "description": "Proxy inventory, credentials, and allowlisted client IPs."
    },
    {
      "name": "Billing",
      "description": "Wallet, transactions, and top-up checkout flows."
    },
    {
      "name": "Affiliate",
      "description": "Affiliate enrollment, payout email, and referral codes."
    },
    {
      "name": "Subscriptions",
      "description": "Subscription catalog and subscription-management operations."
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT returned by POST /v2/auth/login."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "ArbitraryObject": {
        "type": "object",
        "additionalProperties": true
      },
      "LoginRequest": {
        "type": "object",
        "required": [
          "username",
          "password"
        ],
        "properties": {
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string",
            "format": "password"
          }
        }
      },
      "MeResponse": {
        "type": "object",
        "required": [
          "id",
          "uuid",
          "username",
          "email",
          "status",
          "plan_code",
          "plan_name",
          "balance_microcents",
          "credits_remaining",
          "assigned_ips",
          "onboarding_complete",
          "affiliate_only",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "uuid": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "status": {
            "type": "string"
          },
          "plan_code": {
            "type": "string"
          },
          "plan_name": {
            "type": "string"
          },
          "balance_microcents": {
            "type": "integer",
            "format": "int64"
          },
          "credits_remaining": {
            "type": "integer",
            "format": "int64"
          },
          "assigned_ips": {
            "type": "integer"
          },
          "onboarding_complete": {
            "type": "boolean"
          },
          "affiliate_only": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "LoginResponse": {
        "type": "object",
        "required": [
          "token",
          "expires_in",
          "user"
        ],
        "properties": {
          "token": {
            "type": "string"
          },
          "expires_in": {
            "type": "integer",
            "format": "int64"
          },
          "user": {
            "$ref": "#/components/schemas/MeResponse"
          }
        }
      },
      "AffiliateSignupRequest": {
        "type": "object",
        "required": [
          "username",
          "email"
        ],
        "properties": {
          "username": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          }
        }
      },
      "AffiliateSignupResponse": {
        "type": "object",
        "required": [
          "status",
          "affiliate_only",
          "username",
          "email",
          "message"
        ],
        "properties": {
          "status": {
            "type": "string"
          },
          "affiliate_only": {
            "type": "boolean"
          },
          "username": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ForgotPasswordRequest": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          }
        }
      },
      "ResetPasswordRequest": {
        "type": "object",
        "required": [
          "token",
          "new_password"
        ],
        "properties": {
          "token": {
            "type": "string"
          },
          "new_password": {
            "type": "string",
            "format": "password"
          }
        }
      },
      "ChangePasswordRequest": {
        "type": "object",
        "required": [
          "current_password",
          "new_password"
        ],
        "properties": {
          "current_password": {
            "type": "string",
            "format": "password"
          },
          "new_password": {
            "type": "string",
            "format": "password"
          }
        }
      },
      "StatusMessageResponse": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string"
          }
        }
      },
      "ValidateTokenResponse": {
        "type": "object",
        "required": [
          "valid"
        ],
        "properties": {
          "valid": {
            "type": "boolean"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "purpose": {
            "type": "string"
          }
        }
      },
      "PasswordRequirements": {
        "type": "object",
        "required": [
          "min_length",
          "require_uppercase",
          "require_lowercase",
          "require_digit",
          "require_special",
          "check_common",
          "check_compromised",
          "history_check_count"
        ],
        "properties": {
          "min_length": {
            "type": "integer"
          },
          "require_uppercase": {
            "type": "boolean"
          },
          "require_lowercase": {
            "type": "boolean"
          },
          "require_digit": {
            "type": "boolean"
          },
          "require_special": {
            "type": "boolean"
          },
          "check_common": {
            "type": "boolean"
          },
          "check_compromised": {
            "type": "boolean"
          },
          "history_check_count": {
            "type": "integer"
          }
        }
      },
      "UsageStats": {
        "type": "object",
        "required": [
          "period",
          "total_bytes",
          "total_requests",
          "total_cost_microcents"
        ],
        "properties": {
          "period": {
            "type": "string"
          },
          "total_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "total_requests": {
            "type": "integer",
            "format": "int64"
          },
          "total_cost_microcents": {
            "type": "integer",
            "format": "int64"
          },
          "max_ips_assigned": {
            "type": "integer"
          },
          "ip_days": {
            "type": "integer"
          }
        }
      },
      "DailyUsage": {
        "type": "object",
        "required": [
          "date",
          "bytes",
          "requests",
          "cost_microcents"
        ],
        "properties": {
          "date": {
            "type": "string"
          },
          "bytes": {
            "type": "integer",
            "format": "int64"
          },
          "requests": {
            "type": "integer",
            "format": "int64"
          },
          "cost_microcents": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "UsageResponse": {
        "type": "object",
        "required": [
          "current_month"
        ],
        "properties": {
          "current_month": {
            "$ref": "#/components/schemas/UsageStats"
          },
          "last_month": {
            "$ref": "#/components/schemas/UsageStats"
          },
          "daily_usage": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DailyUsage"
            }
          }
        }
      },
      "TopEndpointEntry": {
        "type": "object",
        "required": [
          "server",
          "requests",
          "bytes"
        ],
        "properties": {
          "server": {
            "type": "string"
          },
          "requests": {
            "type": "integer",
            "format": "int64"
          },
          "bytes": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "UsageSummaryResponse": {
        "type": "object",
        "required": [
          "period_start",
          "period_end",
          "bytes_total",
          "bytes_in",
          "bytes_out",
          "requests_total",
          "gb_used",
          "top_endpoints"
        ],
        "properties": {
          "period_start": {
            "type": "string",
            "format": "date-time"
          },
          "period_end": {
            "type": "string",
            "format": "date-time"
          },
          "bytes_total": {
            "type": "integer",
            "format": "int64"
          },
          "bytes_in": {
            "type": "integer",
            "format": "int64"
          },
          "bytes_out": {
            "type": "integer",
            "format": "int64"
          },
          "requests_total": {
            "type": "integer",
            "format": "int64"
          },
          "gb_used": {
            "type": "number"
          },
          "gb_remaining": {
            "type": "number",
            "nullable": true
          },
          "top_endpoints": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TopEndpointEntry"
            }
          }
        }
      },
      "HourlyUsagePoint": {
        "type": "object",
        "required": [
          "hour",
          "requests",
          "bytes"
        ],
        "properties": {
          "hour": {
            "type": "string",
            "format": "date-time"
          },
          "requests": {
            "type": "integer",
            "format": "int64"
          },
          "bytes": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "HourlyUsageResponse": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HourlyUsagePoint"
            }
          }
        }
      },
      "DailyUsagePoint": {
        "type": "object",
        "required": [
          "date",
          "requests",
          "bytes",
          "bytes_in",
          "bytes_out",
          "gb"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "requests": {
            "type": "integer",
            "format": "int64"
          },
          "bytes": {
            "type": "integer",
            "format": "int64"
          },
          "bytes_in": {
            "type": "integer",
            "format": "int64"
          },
          "bytes_out": {
            "type": "integer",
            "format": "int64"
          },
          "gb": {
            "type": "number"
          }
        }
      },
      "DailyUsageBucketsResponse": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DailyUsagePoint"
            }
          }
        }
      },
      "LiveUsageResponse": {
        "type": "object",
        "required": [
          "today_requests",
          "today_bytes",
          "today_gb"
        ],
        "properties": {
          "today_requests": {
            "type": "integer",
            "format": "int64"
          },
          "today_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "today_gb": {
            "type": "number"
          }
        }
      },
      "PlanResponse": {
        "type": "object",
        "required": [
          "id",
          "code",
          "name",
          "type",
          "billing_model",
          "base_price_monthly",
          "price_per_ip_monthly",
          "price_per_gb",
          "price_per_request",
          "credit_price",
          "min_ips",
          "max_ips",
          "included_gb",
          "included_requests",
          "max_concurrent_connections",
          "pool_access",
          "pool_geo_targeting",
          "is_active"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "billing_model": {
            "type": "string"
          },
          "base_price_monthly": {
            "type": "number"
          },
          "price_per_ip_monthly": {
            "type": "number"
          },
          "price_per_gb": {
            "type": "number"
          },
          "price_per_request": {
            "type": "number"
          },
          "credit_price": {
            "type": "number"
          },
          "min_ips": {
            "type": "integer"
          },
          "max_ips": {
            "type": "integer"
          },
          "included_gb": {
            "type": "number"
          },
          "included_requests": {
            "type": "integer"
          },
          "max_concurrent_connections": {
            "type": "integer"
          },
          "pool_access": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pool_geo_targeting": {
            "type": "boolean"
          },
          "is_active": {
            "type": "boolean"
          }
        }
      },
      "CurrentMonthUsage": {
        "type": "object",
        "required": [
          "total_bytes",
          "total_requests",
          "total_cost_microcents",
          "max_ips_assigned",
          "ip_days"
        ],
        "properties": {
          "total_bytes": {
            "type": "integer",
            "format": "int64"
          },
          "total_requests": {
            "type": "integer",
            "format": "int64"
          },
          "total_cost_microcents": {
            "type": "integer",
            "format": "int64"
          },
          "max_ips_assigned": {
            "type": "integer"
          },
          "ip_days": {
            "type": "integer"
          }
        }
      },
      "BillingResponse": {
        "type": "object",
        "required": [
          "balance_microcents",
          "credits_remaining",
          "plan_code",
          "plan_name"
        ],
        "properties": {
          "balance_microcents": {
            "type": "integer",
            "format": "int64"
          },
          "credits_remaining": {
            "type": "integer",
            "format": "int64"
          },
          "plan_code": {
            "type": "string"
          },
          "plan_name": {
            "type": "string"
          },
          "current_month_usage": {
            "$ref": "#/components/schemas/CurrentMonthUsage"
          }
        }
      },
      "Transaction": {
        "type": "object",
        "required": [
          "id",
          "uuid",
          "type",
          "amount_microcents",
          "balance_before",
          "balance_after",
          "description",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "uuid": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "amount_microcents": {
            "type": "integer",
            "format": "int64"
          },
          "balance_before": {
            "type": "integer",
            "format": "int64"
          },
          "balance_after": {
            "type": "integer",
            "format": "int64"
          },
          "description": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TransactionsResponse": {
        "type": "object",
        "required": [
          "transactions",
          "count",
          "limit",
          "offset"
        ],
        "properties": {
          "transactions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Transaction"
            }
          },
          "count": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          }
        }
      },
      "AutoTopUpSettings": {
        "type": "object",
        "required": [
          "enabled",
          "threshold_microcents",
          "max_topups_per_month"
        ],
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "threshold_microcents": {
            "type": "integer",
            "format": "int64"
          },
          "amount_cents": {
            "type": "integer",
            "format": "int64"
          },
          "price_id": {
            "type": "string"
          },
          "max_topups_per_month": {
            "type": "integer"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UpdateAutoTopUpRequest": {
        "type": "object",
        "required": [
          "enabled",
          "threshold_microcents",
          "max_topups_per_month"
        ],
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "threshold_microcents": {
            "type": "integer",
            "format": "int64"
          },
          "amount_cents": {
            "type": "integer",
            "format": "int64"
          },
          "price_id": {
            "type": "string"
          },
          "max_topups_per_month": {
            "type": "integer"
          }
        }
      },
      "PortalContentMessage": {
        "type": "object",
        "required": [
          "enabled",
          "eyebrow",
          "title",
          "body",
          "cta_label",
          "cta_path"
        ],
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "eyebrow": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "cta_label": {
            "type": "string"
          },
          "cta_path": {
            "type": "string"
          }
        }
      },
      "PortalContentSettings": {
        "type": "object",
        "required": [
          "offer",
          "updates"
        ],
        "properties": {
          "offer": {
            "$ref": "#/components/schemas/PortalContentMessage"
          },
          "updates": {
            "$ref": "#/components/schemas/PortalContentMessage"
          },
          "updated_at": {
            "type": "string"
          }
        }
      },
      "PortalContentResponse": {
        "type": "object",
        "required": [
          "settings"
        ],
        "properties": {
          "settings": {
            "$ref": "#/components/schemas/PortalContentSettings"
          }
        }
      },
      "IPResponse": {
        "type": "object",
        "required": [
          "ip_address",
          "server_id",
          "assignment_type",
          "assigned_at"
        ],
        "properties": {
          "ip_address": {
            "type": "string"
          },
          "outbound_ip": {
            "type": "string"
          },
          "server_id": {
            "type": "integer"
          },
          "server_hostname": {
            "type": "string"
          },
          "region": {
            "type": "string"
          },
          "datacenter": {
            "type": "string"
          },
          "country_code": {
            "type": "string"
          },
          "proxy_type": {
            "type": "string"
          },
          "endpoint_kind": {
            "type": "string"
          },
          "assignment_type": {
            "type": "string"
          },
          "assigned_at": {
            "type": "string",
            "format": "date-time"
          },
          "http_port": {
            "type": "integer"
          },
          "socks_port": {
            "type": "integer",
            "nullable": true
          },
          "http_endpoint": {
            "type": "string"
          },
          "socks_endpoint": {
            "type": "string"
          },
          "session_sid": {
            "type": "integer",
            "nullable": true
          },
          "endpoint_auth_modes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "IPListResponse": {
        "type": "object",
        "required": [
          "ips",
          "count",
          "total_count",
          "limit",
          "offset"
        ],
        "properties": {
          "ips": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IPResponse"
            }
          },
          "count": {
            "type": "integer"
          },
          "total_count": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          }
        }
      },
      "ClientIPRequest": {
        "type": "object",
        "required": [
          "ip_address"
        ],
        "properties": {
          "ip_address": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        }
      },
      "ClientIPResponse": {
        "type": "object",
        "required": [
          "ip_address",
          "created_at"
        ],
        "properties": {
          "ip_address": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ClientIPListResponse": {
        "type": "object",
        "required": [
          "client_ips",
          "count",
          "max_allowed",
          "has_override",
          "default_max"
        ],
        "properties": {
          "client_ips": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ClientIPResponse"
            }
          },
          "count": {
            "type": "integer"
          },
          "max_allowed": {
            "type": "integer"
          },
          "override_limit": {},
          "has_override": {
            "type": "boolean"
          },
          "default_max": {
            "type": "integer"
          }
        }
      },
      "CredentialsResponse": {
        "type": "object",
        "required": [
          "api_key"
        ],
        "properties": {
          "api_key": {
            "type": "string"
          }
        }
      },
      "AffiliateResponse": {
        "type": "object",
        "required": [
          "enrolled"
        ],
        "properties": {
          "enrolled": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "clicks_30d": {
            "type": "integer",
            "format": "int64"
          },
          "conversions_total": {
            "type": "integer",
            "format": "int64"
          },
          "pending_commission_cents": {
            "type": "integer",
            "format": "int64"
          },
          "total_paid_cents": {
            "type": "integer",
            "format": "int64"
          },
          "paypal_email": {
            "type": "string",
            "format": "email"
          },
          "promotion_source": {
            "type": "string"
          },
          "affiliate_code": {
            "type": "string"
          },
          "referral_url": {
            "type": "string"
          },
          "affiliate_codes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "referral_urls": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "UpdateAffiliatePaypalRequest": {
        "type": "object",
        "required": [
          "paypal_email"
        ],
        "properties": {
          "paypal_email": {
            "type": "string",
            "format": "email"
          }
        }
      },
      "UpdateAffiliateProfileRequest": {
        "type": "object",
        "properties": {
          "promotion_source": {
            "type": "string"
          }
        }
      },
      "AddAffiliateCodeRequest": {
        "type": "object",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string"
          }
        }
      },
      "TopUpPreset": {
        "type": "object",
        "required": [
          "amount_cents",
          "label",
          "popular"
        ],
        "properties": {
          "amount_cents": {
            "type": "integer",
            "format": "int64"
          },
          "label": {
            "type": "string"
          },
          "popular": {
            "type": "boolean"
          }
        }
      },
      "TopUpPresetsResponse": {
        "type": "object",
        "required": [
          "presets"
        ],
        "properties": {
          "presets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TopUpPreset"
            }
          }
        }
      },
      "TopUpPrice": {
        "type": "object",
        "required": [
          "product_id",
          "price_id",
          "name",
          "description",
          "amount",
          "price",
          "currency",
          "topup_type"
        ],
        "properties": {
          "product_id": {
            "type": "string"
          },
          "price_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "amount": {
            "type": "integer",
            "format": "int64"
          },
          "price": {
            "type": "integer",
            "format": "int64"
          },
          "currency": {
            "type": "string"
          },
          "topup_type": {
            "type": "string"
          }
        }
      },
      "TopUpPricesResponse": {
        "type": "object",
        "required": [
          "prices"
        ],
        "properties": {
          "prices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TopUpPrice"
            }
          }
        }
      },
      "TopUpCheckoutRequest": {
        "type": "object",
        "required": [
          "success_url"
        ],
        "properties": {
          "topup_type": {
            "type": "string"
          },
          "price_id": {
            "type": "string"
          },
          "amount_cents": {
            "type": "integer",
            "format": "int64"
          },
          "quantity": {
            "type": "integer"
          },
          "amount": {
            "type": "integer",
            "format": "int64",
            "description": "Deprecated. Ignored by the current server."
          },
          "success_url": {
            "type": "string"
          }
        }
      },
      "TopUpCheckoutResponse": {
        "type": "object",
        "required": [
          "transaction_id",
          "checkout_url",
          "status"
        ],
        "properties": {
          "transaction_id": {
            "type": "string"
          },
          "checkout_url": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "SubscriptionPriceResponse": {
        "type": "object",
        "required": [
          "price_id",
          "quantity",
          "price_usd",
          "per_proxy"
        ],
        "properties": {
          "price_id": {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "price_usd": {
            "type": "integer",
            "format": "int64"
          },
          "per_proxy": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "SubscriptionProduct": {
        "type": "object",
        "required": [
          "product_id",
          "name",
          "description",
          "proxy_type",
          "prices"
        ],
        "properties": {
          "product_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "proxy_type": {
            "type": "string"
          },
          "prices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SubscriptionPriceResponse"
            }
          }
        }
      },
      "SubscriptionProductsResponse": {
        "type": "object",
        "required": [
          "products"
        ],
        "properties": {
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SubscriptionProduct"
            }
          }
        }
      },
      "SubscriptionCheckoutRequest": {
        "type": "object",
        "required": [
          "price_id"
        ],
        "properties": {
          "price_id": {
            "type": "string"
          },
          "success_url": {
            "type": "string"
          },
          "cancel_url": {
            "type": "string"
          }
        }
      },
      "SubscriptionCheckoutResponse": {
        "type": "object",
        "required": [
          "transaction_id",
          "checkout_url",
          "status"
        ],
        "properties": {
          "transaction_id": {
            "type": "string"
          },
          "checkout_url": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "SubscriptionsEnvelope": {
        "type": "object",
        "required": [
          "subscriptions",
          "count"
        ],
        "properties": {
          "subscriptions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ArbitraryObject"
            }
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "CancelSubscriptionRequest": {
        "type": "object",
        "properties": {
          "effective_from": {
            "type": "string",
            "enum": [
              "next_billing_period",
              "immediately"
            ]
          }
        }
      },
      "ChangeSubscriptionPriceRequest": {
        "type": "object",
        "required": [
          "price_id"
        ],
        "properties": {
          "price_id": {
            "type": "string"
          },
          "product_id": {
            "type": "string"
          },
          "effective_from": {
            "type": "string",
            "enum": [
              "next_billing_period",
              "immediately"
            ]
          }
        }
      },
      "UpsertSubscriptionItemRequest": {
        "type": "object",
        "required": [
          "price_id"
        ],
        "properties": {
          "price_id": {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "effective_from": {
            "type": "string",
            "enum": [
              "next_billing_period",
              "immediately"
            ]
          },
          "replace_base_plan": {
            "type": "boolean"
          }
        }
      },
      "RemoveSubscriptionItemRequest": {
        "type": "object",
        "required": [
          "product_id"
        ],
        "properties": {
          "product_id": {
            "type": "string"
          },
          "effective_from": {
            "type": "string",
            "enum": [
              "next_billing_period",
              "immediately"
            ]
          }
        }
      },
      "SubscriptionMutationResponse": {
        "type": "object",
        "required": [
          "status",
          "message"
        ],
        "properties": {
          "status": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "affiliate_code": {
            "type": "string"
          },
          "affiliate_codes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "referral_url": {
            "type": "string"
          },
          "referral_urls": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "promotion_source": {
            "type": "string"
          }
        }
      },
      "LegacyProxyResponse": {
        "type": "object",
        "required": [
          "ip",
          "username",
          "password",
          "address",
          "ip_country",
          "ip_region",
          "ip_city",
          "country"
        ],
        "properties": {
          "ip": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "ip_country": {
            "type": "string"
          },
          "ip_region": {
            "type": "string"
          },
          "ip_city": {
            "type": "string"
          },
          "country": {
            "type": "string"
          }
        }
      },
      "LegacyAuthIPResponse": {
        "type": "object",
        "required": [
          "ip"
        ],
        "properties": {
          "ip": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        }
      },
      "LegacyRemoveAuthIPResponse": {
        "type": "object",
        "required": [
          "status",
          "ip"
        ],
        "properties": {
          "status": {
            "type": "string"
          },
          "ip": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid authentication",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InternalError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/healthz": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Liveness probe",
        "operationId": "healthz",
        "responses": {
          "200": {
            "description": "Service is alive",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArbitraryObject"
                },
                "example": {
                  "status": "ok"
                }
              }
            }
          }
        }
      }
    },
    "/readyz": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Readiness probe",
        "operationId": "readyz",
        "responses": {
          "200": {
            "description": "Dependencies healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArbitraryObject"
                },
                "example": {
                  "status": "ok",
                  "checks": {
                    "db": "ok",
                    "redis": "ok"
                  }
                }
              }
            }
          },
          "503": {
            "description": "Dependency unhealthy"
          }
        }
      }
    },
    "/api/v1/myProxies": {
      "get": {
        "tags": [
          "Proxy"
        ],
        "summary": "List proxy inventory with legacy apiKey auth",
        "description": "Legacy compatibility route. Supply the customer apiKey as a query parameter. The current runtime always returns simplified proxy rows.",
        "operationId": "legacyGetMyProxies",
        "parameters": [
          {
            "name": "apiKey",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "simple",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Proxy rows",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/LegacyProxyResponse"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/getAuthIP": {
      "get": {
        "tags": [
          "Proxy"
        ],
        "summary": "List allowlisted client IPs with legacy apiKey auth",
        "operationId": "legacyGetAuthIP",
        "parameters": [
          {
            "name": "apiKey",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "labels",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Allowlisted IPs",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LegacyAuthIPResponse"
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/addAuthIP": {
      "get": {
        "tags": [
          "Proxy"
        ],
        "summary": "Add allowlisted client IP with legacy apiKey auth",
        "operationId": "legacyAddAuthIPGet",
        "parameters": [
          {
            "name": "apiKey",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ip",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Use current to resolve the caller IP."
          },
          {
            "name": "label",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Allowlisted IP added",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyAuthIPResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "tags": [
          "Proxy"
        ],
        "summary": "Add allowlisted client IP with legacy apiKey auth",
        "operationId": "legacyAddAuthIPPost",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "apiKey",
                  "ip"
                ],
                "properties": {
                  "apiKey": {
                    "type": "string"
                  },
                  "ip": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Allowlisted IP added",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyAuthIPResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/removeAuthIP": {
      "get": {
        "tags": [
          "Proxy"
        ],
        "summary": "Remove allowlisted client IP with legacy apiKey auth",
        "operationId": "legacyRemoveAuthIPGet",
        "parameters": [
          {
            "name": "apiKey",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ip",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Allowlisted IP removed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyRemoveAuthIPResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "tags": [
          "Proxy"
        ],
        "summary": "Remove allowlisted client IP with legacy apiKey auth",
        "operationId": "legacyRemoveAuthIPPost",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "apiKey",
                  "ip"
                ],
                "properties": {
                  "apiKey": {
                    "type": "string"
                  },
                  "ip": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Allowlisted IP removed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegacyRemoveAuthIPResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/auth/login": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Log in",
        "operationId": "login",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/auth/affiliate-signup": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Create an affiliate-only account",
        "operationId": "affiliateSignup",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AffiliateSignupRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Affiliate account created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AffiliateSignupResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "409": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/auth/forgot-password": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Request a password reset",
        "operationId": "forgotPassword",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ForgotPasswordRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reset flow accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusMessageResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v2/auth/reset-password": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Complete a password reset or setup",
        "operationId": "resetPassword",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResetPasswordRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusMessageResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/auth/validate-token": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Validate a password-reset token",
        "operationId": "validateResetToken",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateTokenResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v2/auth/password-requirements": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Get current password policy",
        "operationId": "getPasswordRequirements",
        "responses": {
          "200": {
            "description": "Password policy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PasswordRequirements"
                }
              }
            }
          }
        }
      }
    },
    "/v2/topup/presets": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "List public wallet top-up presets",
        "operationId": "getTopUpPresets",
        "responses": {
          "200": {
            "description": "Preset list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopUpPresetsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v2/topup/prices": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "List public top-up price options",
        "operationId": "getTopUpPrices",
        "responses": {
          "200": {
            "description": "Available price options",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopUpPricesResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/subscriptions/products": {
      "get": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "List public subscription products",
        "operationId": "getSubscriptionProducts",
        "responses": {
          "200": {
            "description": "Available subscription products",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionProductsResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/topup/anonymous-checkout": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Create a public wallet top-up checkout",
        "operationId": "createAnonymousTopUpCheckout",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TopUpCheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopUpCheckoutResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Get the authenticated account profile",
        "operationId": "getMe",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v2/me/usage": {
      "get": {
        "tags": [
          "Usage"
        ],
        "summary": "Get legacy daily usage totals",
        "operationId": "getUsage",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage totals",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/usage/summary": {
      "get": {
        "tags": [
          "Usage"
        ],
        "summary": "Get aggregated usage summary",
        "operationId": "getUsageSummary",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage summary",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageSummaryResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v2/me/usage/hourly": {
      "get": {
        "tags": [
          "Usage"
        ],
        "summary": "Get hourly usage buckets",
        "operationId": "getUsageHourly",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Hourly buckets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HourlyUsageResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v2/me/usage/daily": {
      "get": {
        "tags": [
          "Usage"
        ],
        "summary": "Get daily usage buckets",
        "operationId": "getUsageDaily",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Daily buckets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DailyUsageBucketsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v2/me/usage/live": {
      "get": {
        "tags": [
          "Usage"
        ],
        "summary": "Get live usage snapshot",
        "operationId": "getUsageLive",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Live usage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LiveUsageResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v2/me/plan": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Get active plan details",
        "operationId": "getPlan",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Plan details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/v2/me/billing": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Get current balance and month usage",
        "operationId": "getBilling",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Billing snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v2/me/transactions": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "List recent balance transactions",
        "operationId": "getTransactions",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transaction list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v2/me/auto-topup": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Get wallet auto-top-up settings",
        "operationId": "getAutoTopUp",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Auto-top-up settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoTopUpSettings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "put": {
        "tags": [
          "Billing"
        ],
        "summary": "Update wallet auto-top-up settings",
        "operationId": "updateAutoTopUp",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAutoTopUpRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Auto-top-up settings saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoTopUpSettings"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/portal-content": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Get portal content settings for the signed-in user",
        "operationId": "getPortalContent",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Portal content settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortalContentResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/ips": {
      "get": {
        "tags": [
          "Proxy"
        ],
        "summary": "List proxy inventory assigned to the authenticated account",
        "operationId": "getIPs",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "proxy_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "protocol",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Inventory rows",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IPListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/client-ips": {
      "get": {
        "tags": [
          "Proxy"
        ],
        "summary": "List allowlisted client IPs",
        "operationId": "getClientIPs",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Allowlisted IPs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientIPListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "tags": [
          "Proxy"
        ],
        "summary": "Add an allowlisted client IP",
        "operationId": "addClientIP",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientIPRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Client IP added",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientIPResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/client-ips/{ip}": {
      "delete": {
        "tags": [
          "Proxy"
        ],
        "summary": "Remove an allowlisted client IP",
        "operationId": "removeClientIP",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "ip",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Client IP removed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArbitraryObject"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/credentials": {
      "get": {
        "tags": [
          "Proxy"
        ],
        "summary": "Get the current customer apiKey",
        "operationId": "getCredentials",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CredentialsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "tags": [
          "Proxy"
        ],
        "summary": "Regenerate the customer apiKey",
        "operationId": "regenerateCredentials",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "New apiKey issued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CredentialsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/password": {
      "post": {
        "tags": [
          "Account"
        ],
        "summary": "Change the authenticated user's password",
        "operationId": "changePassword",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChangePasswordRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusMessageResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/onboarding-complete": {
      "post": {
        "tags": [
          "Account"
        ],
        "summary": "Mark onboarding complete",
        "operationId": "markOnboardingComplete",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "204": {
            "description": "Onboarding marked complete"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/affiliate": {
      "get": {
        "tags": [
          "Affiliate"
        ],
        "summary": "Get affiliate program state",
        "operationId": "getMyAffiliate",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Affiliate state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AffiliateResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/affiliate/enroll": {
      "post": {
        "tags": [
          "Affiliate"
        ],
        "summary": "Enroll the signed-in user in the affiliate program",
        "operationId": "enrollAffiliate",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Enrollment result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionMutationResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/affiliate/paypal": {
      "put": {
        "tags": [
          "Affiliate"
        ],
        "summary": "Update affiliate payout email",
        "operationId": "updateAffiliatePaypal",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAffiliatePaypalRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payout email updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArbitraryObject"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/affiliate/profile": {
      "put": {
        "tags": [
          "Affiliate"
        ],
        "summary": "Update affiliate profile metadata",
        "operationId": "updateAffiliateProfile",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAffiliateProfileRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profile updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/affiliate/codes": {
      "post": {
        "tags": [
          "Affiliate"
        ],
        "summary": "Add a custom affiliate referral code",
        "operationId": "addAffiliateCode",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddAffiliateCodeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Referral code state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/BadRequest"
          },
          "409": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/subscriptions": {
      "get": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "List subscriptions for the authenticated account",
        "operationId": "getMySubscriptions",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionsEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/subscriptions/{subscription_id}/cancel": {
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Schedule or perform subscription cancellation",
        "operationId": "cancelSubscription",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelSubscriptionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancellation accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/subscriptions/{subscription_id}/uncancel": {
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Remove a scheduled cancellation",
        "operationId": "uncancelSubscription",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription remains active",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/subscriptions/{subscription_id}/change": {
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Change a subscription price tier",
        "operationId": "changeSubscriptionPrice",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChangeSubscriptionPriceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/subscriptions/{subscription_id}/items/upsert": {
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Add or update a subscription item",
        "operationId": "upsertSubscriptionItem",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpsertSubscriptionItemRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/subscriptions/{subscription_id}/items/remove": {
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Remove a subscription item",
        "operationId": "removeSubscriptionItem",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RemoveSubscriptionItemRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/me/subscriptions/{subscription_id}/deferred-downgrade/cancel": {
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Cancel a deferred downgrade",
        "operationId": "cancelDeferredDowngrade",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "subscription_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deferred downgrade canceled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v2/topup/checkout": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Create an authenticated wallet top-up checkout",
        "operationId": "createTopUpCheckout",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TopUpCheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopUpCheckoutResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v2/subscriptions/checkout": {
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Create an authenticated subscription checkout",
        "operationId": "createSubscriptionCheckout",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionCheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionCheckoutResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  }
}