TrueProxies Customer API

components:
  parameters:
    CustomerId:
      description: Owned sub-customer UUID. Resellers only; reads require reseller:read
        and writes reseller:purchase in addition to the operation scope. X-Customer-Id
        header is an alternative. Not allowed for me, wallet, trial, API keys, or
        reseller-management routes.
      in: query
      name: customer_id
      schema:
        format: uuid
        type: string
    IdempotencyKey:
      description: 'Makes a retry safe. The first request carrying a given key is
        executed and its response recorded; repeating the same request with the same
        key replays that response, with Idempotency-Replayed: true, rather than buying
        or paying a second time. Reusing a key for a different request is refused
        with 409, as is a repeat that arrives while the first is still running. Keys
        are scoped to your account and to the endpoint. Successful and uncertain invoice
        commands are retained so that an old retry cannot create another invoice.
        Completed definite rejections are kept for at least 24 hours; after that,
        the same key may be evaluated again.'
      in: header
      name: Idempotency-Key
      required: false
      schema:
        maxLength: 200
        type: string
  responses:
    Error:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: error
  schemas:
    Analytics:
      properties:
        destinations:
          items:
            $ref: '#/components/schemas/Destination'
          type: array
        errors:
          items:
            $ref: '#/components/schemas/ErrorClass'
          type: array
        range:
          type: string
        series:
          items:
            $ref: '#/components/schemas/AnalyticsPoint'
          type: array
        success_rate:
          type: number
      required:
      - range
      - success_rate
      - series
      - destinations
      - errors
      type: object
    AnalyticsPoint:
      properties:
        avg_session_ms:
          description: Mean elapsed milliseconds of measured completed authenticated
            socket sessions; null when no samples exist.
          minimum: 0
          type:
          - number
          - 'null'
        avg_setup_ms:
          description: Mean gateway-to-destination setup milliseconds for measured
            successful initial TCP tunnels; null when no samples exist.
          minimum: 0
          type:
          - number
          - 'null'
        bytes_in:
          format: int64
          type: integer
        bytes_out:
          format: int64
          type: integer
        failures:
          format: int64
          type: integer
        requests:
          format: int64
          type: integer
        session_samples:
          description: Number of measured completed session samples in this bucket.
          minimum: 0
          type: integer
        setup_samples:
          description: Number of measured successful setup samples in this bucket.
          minimum: 0
          type: integer
        ts:
          format: date-time
          type: string
      required:
      - ts
      - requests
      - failures
      - bytes_in
      - bytes_out
      type: object
    Catalog:
      properties:
        cities:
          items:
            $ref: '#/components/schemas/City'
          type: array
        hosts:
          additionalProperties:
            type: string
          description: public proxy hostnames per product
          type: object
        offers:
          items:
            $ref: '#/components/schemas/Offer'
          type: array
        payment_providers:
          description: Available payment providers in the dashboard.
          items:
            type: string
          type: array
        trial_available:
          description: the operator trial switch; false means the trial offer is listed
            but cannot be claimed
          type: boolean
      required:
      - offers
      - cities
      - hosts
      type: object
    City:
      properties:
        available:
          description: mapped to a verified /36 with free /48s
          type: boolean
        code:
          type: string
        country_code:
          type: string
        name:
          type: string
      required:
      - code
      - country_code
      - name
      - available
      type: object
    CustomerBilling:
      description: The party an invoice is issued to. Empty strings mean not provided;
        a name or a company must be present when setting them. Saving requires a country
        and the address fields required for that country. Existing incomplete profiles
        remain readable until completed.
      properties:
        address_line1:
          maxLength: 400
          type: string
        address_line2:
          maxLength: 120
          type: string
        city:
          maxLength: 120
          type: string
        company:
          maxLength: 120
          type: string
        country:
          description: Two-letter ISO 3166-1 alpha-2 code.
          pattern: ^([A-Z]{2})?$
          type: string
        name:
          maxLength: 120
          type: string
        postal_code:
          maxLength: 32
          type: string
        state:
          maxLength: 120
          type: string
        vat_id:
          maxLength: 120
          type: string
      type: object
    Destination:
      properties:
        bytes:
          format: int64
          type: integer
        failures:
          format: int64
          type: integer
        host:
          type: string
        requests:
          format: int64
          type: integer
      required:
      - host
      - requests
      - failures
      - bytes
      type: object
    EndpointRequest:
      properties:
        asn:
          description: 1 to 10 digits, without AS prefix. Requires asn capability.
          maxLength: 10
          type: string
        city:
          description: Letters, digits and underscores; normalized to lowercase. Requires
            city capability.
          maxLength: 32
          type: string
        count:
          default: 1
          description: Number of connection strings. Omission, null and legacy zero
            values use one.
          maximum: 1000
          minimum: 1
          type: integer
        country:
          description: Two-letter country code; normalized to lowercase. Requires
            country capability.
          type: string
        format:
          default: host:port:user:pass
          enum:
          - host:port:user:pass
          - user:pass@host:port
          - user:pass
          - host:port
          - url
          - curl
          - custom
          type: string
        job_id:
          description: Owned active job beneath project_id. Only its validated opaque
            token is included in generated proxy usernames.
          format: uuid
          type: string
        lifetime:
          description: Sticky session lifetime in seconds, 60 to 86400, or 1 to 86400
            when the service has session_lifetime_seconds. Maximum is 1800 with session_lifetime_30m.
            Requires session=sticky and session_lifetime capability. Residential IPv4
            Unlimited requires whole minutes. Omitted or zero leaves the lifetime
            unset.
          type: integer
        project_id:
          description: Owned, active project access. Omit to use main access. Requires
            current project support.
          format: uuid
          type: string
        protocol:
          default: http
          enum:
          - http
          - socks5
          - https
          type: string
        region:
          description: Requires region capability. Services with region_code accept
            only an ISO 3166-2 subdivision code of 1 to 3 letters or digits without
            country prefix (for example CA). Other services accept letters, digits
            and underscores up to 32 characters. Normalized to lowercase in customer
            usernames.
          maxLength: 32
          type: string
        session:
          default: none
          enum:
          - none
          - sticky
          - rotate
          type: string
        template:
          description: Required only for format=custom. A single line of literal text,
            limited to 512 UTF-8 bytes, with at least one of {HOST}, {PORT}, {USER},
            {PASS} or {PROTOCOL}. Other braces and control characters are rejected.
            Placeholder values are substituted literally without escaping or recursive
            expansion. {PROTOCOL} is the connection URL scheme (http, https or socks5h).
          maxLength: 512
          minLength: 1
          type: string
      type: object
    EndpointResponse:
      properties:
        lines:
          items:
            type: string
          type: array
      required:
      - lines
      type: object
    Error:
      properties:
        code:
          enum:
          - BAD_REQUEST
          - UNAUTHENTICATED
          - FORBIDDEN
          - NOT_FOUND
          - CONFLICT
          - RATE_LIMITED
          - SERVICE_UNAVAILABLE
          - OFFER_UNAVAILABLE
          - CITY_UNAVAILABLE
          - CAPACITY_UNAVAILABLE
          - INVOICE_NOT_PAYABLE
          - PROVIDER_ERROR
          - PIPE_UNAVAILABLE
          - TRIAL_NOT_ELIGIBLE
          - EMAIL_UNVERIFIED
          - INTERNAL
          type: string
        details:
          additionalProperties: true
          description: What a client needs to act on the error (ids, flags), never
            display text.
          type: object
        message:
          type: string
      required:
      - code
      - message
      type: object
    ErrorClass:
      properties:
        count:
          format: int64
          type: integer
        err_class:
          type: string
      required:
      - err_class
      - count
      type: object
    Invoice:
      properties:
        activated_at:
          description: When this invoice's service activation, top-up, renewal, or
            charge-only processing committed. Payment receipt and an already-active
            service do not establish this outcome.
          format: date-time
          type: string
        activation_failed_at:
          description: Automatic fulfillment stopped and needs operator attention.
            Payment remains received; this does not mean a refund completed or previously
            purchased service was revoked.
          format: date-time
          type: string
        amount_cents:
          type: integer
        created_at:
          format: date-time
          type: string
        currency:
          type: string
        discount_bp:
          type: integer
        display_name:
          type: string
        due_at:
          format: date-time
          type: string
        id:
          description: Internal API identifier. Use reference for customer-facing
            display.
          format: uuid
          type: string
        kind:
          $ref: '#/components/schemas/InvoiceKind'
        list_amount_cents:
          type: integer
        offer_key:
          type: string
        options:
          $ref: '#/components/schemas/InvoiceOptions'
        paid_at:
          format: date-time
          type: string
        payments:
          items:
            $ref: '#/components/schemas/InvoicePayment'
          type: array
        promo_code:
          type: string
        promo_discount_cents:
          format: int64
          minimum: 0
          type: integer
        reference:
          description: Stable, unique customer-facing reference.
          example: INV-001001
          pattern: ^INV-[0-9]{6,}$
          type: string
        service_id:
          format: uuid
          type: string
        status:
          $ref: '#/components/schemas/InvoiceStatus'
      required:
      - id
      - reference
      - kind
      - offer_key
      - display_name
      - amount_cents
      - currency
      - status
      - due_at
      - created_at
      - payments
      type: object
    InvoiceCreate:
      properties:
        offer_key:
          type: string
        options:
          $ref: '#/components/schemas/InvoiceOptions'
        promo_code:
          maxLength: 40
          minLength: 3
          pattern: ^[A-Za-z0-9][A-Za-z0-9-]{2,39}$
          type: string
        request_id:
          description: Required when promo_code is present; keep stable only while
            retrying identical invoice content.
          format: uuid
          type: string
        service_id:
          description: required for renewal and topup
          format: uuid
          type: string
      required:
      - offer_key
      type: object
    InvoiceKind:
      enum:
      - wallet_topup
      - purchase
      - renewal
      - topup
      - custom
      - white_label
      type: string
    InvoiceOptions:
      properties:
        city:
          type: string
        gb:
          description: GB for top-ups; taken from the offer otherwise
          type: integer
      type: object
    InvoicePayment:
      properties:
        amount_received_cents:
          type: integer
        attempt:
          type: integer
        checkout_url:
          description: present only while the invoice is payable and the pending checkout
            has not reached its known expiry
          type: string
        created_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        provider:
          description: The payment rail, including staff-recorded manual settlements
            and compensation.
          oneOf:
          - $ref: '#/components/schemas/PaymentProvider'
          - enum:
            - manual
            type: string
        refund_amount_cents:
          minimum: 1
          type: integer
        refund_amount_unknown:
          description: A provider refund was reported without a trustworthy amount.
            Reconciliation is required before any additional refund.
          type: boolean
        refund_completed_at:
          format: date-time
          type: string
        refund_reason:
          type: string
        refund_reference:
          type: string
        refund_retryable:
          description: The recorded request can be retried unchanged within the provider
            idempotency window.
          type: boolean
        refund_status:
          enum:
          - processing
          - uncertain
          - manual_required
          - submitted
          - failed
          - refunded
          type: string
        refunded_at:
          description: Refund request recorded at; not proof of completion
          format: date-time
          type: string
        status:
          $ref: '#/components/schemas/PaymentStatus'
      required:
      - id
      - attempt
      - provider
      - status
      - created_at
      type: object
    InvoiceStatus:
      enum:
      - open
      - paid
      - cancelled
      type: string
    LiveMetrics:
      properties:
        completed_connections:
          description: Recorded proxy outcomes underlying success_rate. Selected by
            event timestamp, not literal completion time; delayed or long-running
            connections can appear later.
          minimum: 0
          type: integer
        connections_per_minute:
          description: Sum of recorded usage connection deltas in the minute ending
            at window_end.
          minimum: 0
          type: integer
        download_bps:
          description: Customer download bits per second in the last complete series
            bucket, from bytes_out. Zero is an absence of recorded bytes, not proof
            of healthy idle traffic.
          minimum: 0
          type: number
        interval_seconds:
          const: 10
          type: integer
        last_activity_at:
          description: Latest non-system usage event before sampled_at, scanned since
            the earlier of midnight UTC or window_start. Null means no observation
            in that bounded interval. Samples are emitted only for activity; silence
            cannot distinguish idle traffic from unavailable collection. Treat current
            rates as unavailable when this is null or older than 60 seconds.
          format: date-time
          type:
          - string
          - 'null'
        sampled_at:
          description: UTC query time; this does not prove collector health or data
            freshness.
          format: date-time
          type: string
        series:
          items:
            properties:
              download_bps:
                minimum: 0
                type: number
              ts:
                description: Inclusive UTC start of this ten-second bucket.
                format: date-time
                type: string
              upload_bps:
                minimum: 0
                type: number
            required:
            - ts
            - download_bps
            - upload_bps
            type: object
          maxItems: 60
          minItems: 60
          type: array
        success_rate:
          description: Successful recorded proxy outcomes divided by recorded outcomes
            whose event timestamps fall in the minute ending at window_end. These
            are proxy connection outcomes, not destination HTTP status. Null when
            no outcomes are recorded. Event timestamps may represent connection start
            rather than completion time.
          maximum: 1
          minimum: 0
          type:
          - number
          - 'null'
        traffic_today_bytes:
          description: Observed non-system upload plus download bytes from midnight
            UTC up to sampled_at; delayed arrivals may revise totals.
          minimum: 0
          type: integer
        upload_bps:
          description: Customer upload bits per second in the last complete series
            bucket, from bytes_in.
          minimum: 0
          type: number
        window_end:
          description: Exclusive UTC end, rounded down to ten seconds and delayed
            twenty seconds for collection and shipping. Later arrivals may revise
            observations.
          format: date-time
          type: string
        window_start:
          description: Inclusive UTC start of the ten-minute rate series.
          format: date-time
          type: string
      required:
      - sampled_at
      - last_activity_at
      - window_start
      - window_end
      - interval_seconds
      - download_bps
      - upload_bps
      - connections_per_minute
      - success_rate
      - completed_connections
      - traffic_today_bytes
      - series
      type: object
    Me:
      properties:
        affiliate_enabled:
          type: boolean
        billing:
          $ref: '#/components/schemas/CustomerBilling'
        created_at:
          format: date-time
          type: string
        email:
          type: string
        email_verified:
          type: boolean
        id:
          description: Internal API identifier. Use reference for customer-facing
            display.
          format: uuid
          type: string
        impersonated:
          description: read-only support session (spec §11)
          type: boolean
        reference:
          description: Stable, unique customer-facing reference.
          example: ACC-001001
          pattern: ^ACC-[0-9]{6,}$
          type: string
        reseller_enabled:
          description: Enables reseller customer management, wallet and reseller API
            operations.
          type: boolean
        role:
          description: Account role. Sub-customers cannot join the affiliate program.
          enum:
          - customer
          - reseller
          - sub
          type: string
        suspended:
          description: the account is suspended; proxies refuse its services and purchases
            are blocked
          type: boolean
        white_label_enabled:
          description: Enables white-label store access. Requires reseller_enabled.
          type: boolean
      required:
      - role
      - id
      - reference
      - email
      - email_verified
      - created_at
      type: object
    Offer:
      properties:
        allowance_bytes:
          format: int64
          type: integer
        capabilities:
          items:
            type: string
          type: array
        currency:
          enum:
          - USD
          type: string
        display_name:
          type: string
        enabled:
          type: boolean
        floor_price_cents:
          description: Always 0 here. The floor is the reseller wholesale limit, an
            internal pricing control that the public catalog does not disclose. Staff
            read the real value from the admin catalog.
          minimum: 0
          type: integer
        offer_key:
          type: string
        price_cents:
          type: integer
        product:
          $ref: '#/components/schemas/Product'
        speed_bps:
          description: 0 for paid residential_ipv4_gb means no additional TrueProxies
            speed cap. residential_ipv4_unlimited retains its positive plan speed.
            Upstream capacity and availability still apply. Trials and datacenter
            plans retain their speed limits.
          format: int64
          minimum: 0
          type: integer
        term:
          $ref: '#/components/schemas/Term'
      required:
      - offer_key
      - display_name
      - product
      - price_cents
      - currency
      - enabled
      - capabilities
      type: object
    PayRequest:
      properties:
        provider:
          $ref: '#/components/schemas/PaymentProvider'
      required:
      - provider
      type: object
    PayResponse:
      properties:
        checkout_url:
          type: string
        expires_at:
          format: date-time
          type: string
        payment_id:
          format: uuid
          type: string
      required:
      - payment_id
      - checkout_url
      - expires_at
      type: object
    PaymentProvider:
      description: Payment provider identifier (stripe or cryptomus).
      type: string
    PaymentStatus:
      enum:
      - pending
      - paid
      - expired
      - failed
      - paid_unapplied
      - paid_duplicate
      type: string
    Product:
      enum:
      - residential_ipv4_gb
      - residential_ipv4_unlimited
      - datacenter_ipv6
      - trial
      type: string
    Service:
      properties:
        billing_read_only:
          description: Existing access remains available, but this service cannot
            be topped up or renewed. New plan purchases are separate.
          type: boolean
        capabilities:
          items:
            type: string
          type: array
        city:
          type: string
        comparison_pass:
          description: Free private comparison with fixed speed and expiry; cannot
            be purchased, topped up or renewed.
          type: boolean
        connects_per_second:
          description: Effective limit for this service.
          minimum: 0
          type: integer
        created_at:
          format: date-time
          type: string
        depleted:
          type: boolean
        display_name:
          description: Unlimited service names reflect their actual speed and term;
            offer_key retains the original billing plan.
          type: string
        expires_at:
          format: date-time
          type: string
        grace_until:
          format: date-time
          type: string
        host:
          type: string
        id:
          description: Internal API identifier. Use reference for customer-facing
            display.
          format: uuid
          type: string
        max_connections:
          description: Effective limit for this service.
          minimum: 0
          type: integer
        offer_key:
          type: string
        ports:
          properties:
            http:
              type: integer
            https:
              type: integer
            socks5:
              type: integer
          required:
          - http
          - socks5
          - https
          type: object
        product:
          $ref: '#/components/schemas/Product'
        reference:
          description: Stable, unique customer-facing reference.
          example: SVC-001001
          pattern: ^SVC-[0-9]{6,}$
          type: string
        renewals_enabled:
          type: boolean
        speed_bps:
          description: 0 for paid residential_ipv4_gb means no additional TrueProxies
            speed cap. Private comparison passes have a fixed 50000000 bps cap. residential_ipv4_unlimited
            retains its positive plan speed. Upstream capacity and availability still
            apply. Trials and datacenter plans retain their speed limits.
          format: int64
          minimum: 0
          type: integer
        starts_at:
          format: date-time
          type: string
        status:
          $ref: '#/components/schemas/ServiceStatus'
        term:
          $ref: '#/components/schemas/Term'
        term_label:
          description: Actual fixed duration for a free Unlimited grant, such as 3
            hours. Overrides the recurring term label in customer views.
          type: string
        trial_started_at:
          description: First recorded trial traffic; absent until the first request
            starts the 30-minute window.
          format: date-time
          type: string
        usage_source:
          enum:
          - node
          type: string
        username_base:
          type: string
        whitelist_entries:
          type: integer
      required:
      - id
      - reference
      - product
      - offer_key
      - display_name
      - status
      - host
      - ports
      - username_base
      - max_connections
      - connects_per_second
      - created_at
      - capabilities
      - renewals_enabled
      - billing_read_only
      - usage_source
      type: object
    ServiceCheckResult:
      properties:
        checked_at:
          format: date-time
          type: string
        elapsed_ms:
          description: Duration of this single HTTPS check, including proxy connection
            setup.
          format: int64
          minimum: 0
          type: integer
        exit_ip:
          description: Public IPv4 or IPv6 exit address returned by ipify when the
            check succeeds.
          type: string
        message:
          description: Safe status message without proxy credentials or internal transport
            errors.
          type: string
        success:
          type: boolean
      required:
      - success
      - elapsed_ms
      - checked_at
      - message
      type: object
    ServiceSecret:
      properties:
        password:
          type: string
        rotated_at:
          format: date-time
          type: string
        username_base:
          type: string
      required:
      - username_base
      - password
      - rotated_at
      type: object
    ServiceStatus:
      enum:
      - pending
      - active
      - expired
      - closed
      - suspended
      - failed
      type: string
    SubCustomer:
      properties:
        active_services:
          type: integer
        closed_at:
          format: date-time
          type:
          - string
          - 'null'
        created_at:
          format: date-time
          type: string
        email:
          type: string
        id:
          format: uuid
          type: string
        label:
          type: string
        open_invoices:
          type: integer
        parent_id:
          format: uuid
          type:
          - string
          - 'null'
        reference:
          type: string
        role:
          enum:
          - sub
          type: string
        services:
          type: integer
        suspended_at:
          format: date-time
          type:
          - string
          - 'null'
      required:
      - id
      - reference
      - label
      - email
      - created_at
      - services
      - open_invoices
      type: object
    SubCustomerPatch:
      description: Only supplied fields change. An empty email removes the optional
        contact email.
      properties:
        email:
          maxLength: 254
          type: string
        label:
          maxLength: 64
          minLength: 1
          type: string
      type: object
    SubCustomerWrite:
      properties:
        email:
          maxLength: 254
          type: string
        label:
          maxLength: 64
          minLength: 1
          type: string
      required:
      - label
      type: object
    Term:
      enum:
      - hour
      - day
      - week
      - month
      type: string
    Usage:
      properties:
        allowance_bytes:
          format: int64
          type: integer
        bytes_in:
          description: Bytes the proxy read from the client, which is the customer's
            upload.
          format: int64
          type: integer
        bytes_out:
          description: Bytes the proxy wrote back to the client, which is the customer's
            download.
          format: int64
          type: integer
        current_period_used_bytes:
          description: Traffic counted against the current allowance period. Lifetime
            totals remain in bytes_in and bytes_out.
          format: int64
          type: integer
        gb_allocated:
          description: Informational provider balance in decimal GB; billing uses
            node byte counters.
          type: number
        gb_remaining:
          description: Informational provider balance in decimal GB; billing uses
            node byte counters.
          type: number
        gb_used:
          description: Informational provider balance in decimal GB; billing uses
            node byte counters.
          type: number
        last_updated_at:
          format: date-time
          type: string
        next_reset_at:
          description: Next scheduled allowance reset; a past timestamp means confirmation
            is pending.
          format: date-time
          type: string
        period_started_at:
          description: Start of the current confirmed allowance period, when applicable.
          format: date-time
          type: string
        provider_observed_at:
          format: date-time
          type: string
        provider_usage_informational:
          const: true
          type: boolean
        reconciliation:
          properties:
            drift_ratio:
              type: number
            observed_at:
              format: date-time
              type: string
            status:
              description: Compares the change in vendor balance with the change in
                node counters between two consecutive observations, hourly. `baseline`
                is the first observation for a service, which has no predecessor to
                compare with and therefore reports zero drift; it is not a statement
                that the two figures agree. Billing always uses the node counters.
              enum:
              - baseline
              - ok
              - drift
              - reset
              - stale
              type: string
            usage_drift_bytes:
              format: int64
              type: integer
          required:
          - status
          - usage_drift_bytes
          - drift_ratio
          - observed_at
          type: object
        remaining_bytes:
          description: Node allowance remaining, floored at zero.
          format: int64
          type: integer
        service_id:
          format: uuid
          type: string
        usage_source:
          description: Billing usage comes from durable, deduplicated node byte counters.
          enum:
          - node
          type: string
      required:
      - service_id
      - bytes_in
      - bytes_out
      - last_updated_at
      - usage_source
      - provider_usage_informational
      - allowance_bytes
      - remaining_bytes
      type: object
    Wallet:
      properties:
        balance_cents:
          format: int64
          type: integer
        currency:
          enum:
          - USD
          type: string
        daily_remaining_cents:
          format: 

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/trueproxies/refs/heads/main/openapi/trueproxies-openapi.yml