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: int64 type: integer frozen: type: boolean topup_daily_cap_cents: format: int64 type: integer topup_daily_used_cents: format: int64 type: integer topup_max_cents: format: int64 type: integer topup_min_cents: format: int64 type: integer wallet_frozen_at: format: date-time type: string required: - balance_cents - currency - topup_min_cents - topup_max_cents - daily_remaining_cents - topup_daily_cap_cents - topup_daily_used_cents type: object WalletEntry: properties: amount_cents: format: int64 type: integer created_at: format: date-time type: string id: format: uuid type: string kind: enum: - wallet_topup - wallet_debit - wallet_credit - wallet_adjustment type: string ref_id: type: string ref_type: type: string required: - id - kind - amount_cents - created_at type: object WhitelistCreate: properties: cidr: type: string label: maxLength: 64 type: string move: description: Take the range off the customer's other service that holds it. A range maps to one service (a passwordless connection has no other identity); a 409 with details.movable says which service has it now. type: boolean required: - cidr type: object WhitelistEntry: properties: cidr: description: IPv4/IPv6 address or CIDR allowed to connect without a password type: string created_at: format: date-time type: string id: format: uuid type: string label: type: string required: - id - cidr - created_at type: object securitySchemes: customerAPIKey: bearerFormat: API key description: 'Send Authorization: Bearer tp_api_… . Create a named, scoped key in the customer dashboard. Keys expire after 30, 90 or 365 days and can be revoked immediately.' scheme: bearer type: http info: description: 'Manage existing proxy services using scoped Bearer keys. Default budget: 300 requests per minute per account, shared across keys and control replicas. On HTTP 429, wait for Retry-After. Protected responses use Cache-Control: no-store and X-Request-ID. Timestamps are ISO-8601; monetary amounts are cents. Use the dashboard for API key management. Creating and paying invoices requires billing:write or reseller:purchase.' title: TrueProxies Customer API version: 1.0.0 openapi: 3.1.0 paths: /v1/analytics: get: description: Analytics across the services owned by this account. operationId: get_v1_analytics parameters: - $ref: '#/components/parameters/CustomerId' - in: query name: range schema: default: 24h enum: - 24h - 7d - 30d type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Analytics' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Get account analytics x-api-key-scope: services:read x-required-scope: services:read /v1/catalog: get: description: Public price list. No API key required. Check each service's capabilities before using targeting options. operationId: get_v1_catalog parameters: - $ref: '#/components/parameters/CustomerId' responses: '200': content: application/json: schema: $ref: '#/components/schemas/Catalog' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: [] summary: Browse offers and locations x-required-scope: '' /v1/catalog/priced: get: description: Authenticated offers priced for the invoice payer, including reseller terms when acting for an owned managed customer. Offers unavailable under current pricing terms are omitted. Invoice creation snapshots the final price. operationId: get_v1_catalog_priced parameters: - $ref: '#/components/parameters/CustomerId' responses: '200': content: application/json: schema: $ref: '#/components/schemas/Catalog' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' default: $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Browse your current prices x-api-key-scope: billing:read x-required-scope: billing:read /v1/invoices: get: description: Invoice amounts are integer cents in the specified currency. Supports cursor pagination and an optional service_id filter. Creating and paying invoices requires billing:write or reseller:purchase; billing:read alone cannot spend money. operationId: get_v1_invoices parameters: - $ref: '#/components/parameters/CustomerId' - in: query name: cursor schema: type: string - in: query name: limit schema: default: 25 maximum: 100 minimum: 1 type: integer - description: Only invoices linked to this service and owned by the signed-in customer in: query name: service_id schema: format: uuid type: string - description: Filter before pagination and counting in: query name: status schema: $ref: '#/components/schemas/InvoiceStatus' - description: Filter before pagination and counting in: query name: kind schema: $ref: '#/components/schemas/InvoiceKind' responses: '200': content: application/json: schema: properties: items: items: $ref: '#/components/schemas/Invoice' type: array limit: type: integer next_cursor: type: string total: type: integer required: - items - total - limit type: object description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: List invoices x-api-key-scope: billing:read x-required-scope: billing:read post: description: Requires billing:write; reseller:purchase also permits this operation. Add customer_id to buy for an owned managed customer, which additionally requires reseller:purchase. Prices and discount are snapshotted; a floor conflict returns 409. operationId: post_v1_invoices parameters: - $ref: '#/components/parameters/CustomerId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/InvoiceCreate' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/Invoice' description: created '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Create a purchase invoice x-api-key-scope: billing:write x-required-scope: billing:write /v1/invoices/{id}: get: description: Read invoice status, payment attempts and the associated service. No payment is initiated. operationId: get_v1_invoices_id parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Invoice' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Get an invoice x-api-key-scope: billing:read x-required-scope: billing:read /v1/invoices/{id}/pay: post: description: Requires billing:write; reseller:purchase also permits this operation. On-behalf payments additionally require reseller:purchase and provider wallet. Insufficient funds return 409 with balance_cents and needed_cents. Never automatically retry an uncertain payment; first read invoice status. operationId: post_v1_invoices_id_pay parameters: - $ref: '#/components/parameters/CustomerId' - $ref: '#/components/parameters/IdempotencyKey' - in: path name: id required: true schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PayRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PayResponse' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Pay an invoice x-api-key-scope: billing:write x-required-scope: billing:write /v1/invoices/{id}/pdf: get: description: Download a PDF containing the recorded invoice amounts, current payment status and refund records. Returns application/pdf as an attachment. Send customer_id when acting for a managed customer. No payment is initiated. operationId: get_v1_invoices_id_pdf parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string responses: '200': content: application/pdf: schema: format: binary type: string description: Invoice PDF headers: Content-Disposition: description: Attachment named TrueProxies-INV-NNNNNN.pdf. schema: type: string '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Download an invoice PDF x-api-key-scope: billing:read x-required-scope: billing:read /v1/me: get: description: Return the account associated with this key. operationId: get_v1_me responses: '200': content: application/json: schema: $ref: '#/components/schemas/Me' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Get your account x-api-key-scope: services:read x-required-scope: services:read /v1/services: get: description: Current services by default. Use view=history for closed services or view=all for all records. Supports cursor pagination; each view has its own total. operationId: get_v1_services parameters: - $ref: '#/components/parameters/CustomerId' - in: query name: cursor schema: type: string - in: query name: limit schema: default: 25 maximum: 100 minimum: 1 type: integer - description: Current includes every service that is not permanently closed, including activation failures and services needing renewal or support. History contains effectively closed services. All returns both groups for account-wide summaries and eligibility checks. in: query name: view schema: default: current enum: - current - history - all type: string responses: '200': content: application/json: schema: properties: items: items: $ref: '#/components/schemas/Service' type: array limit: type: integer next_cursor: type: string total: type: integer required: - items - total - limit type: object description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: List your services x-api-key-scope: services:read x-required-scope: services:read /v1/services/{id}: get: description: Connection hosts, available ports, capabilities, status, expiry and effective limits. Does not return the proxy password. operationId: get_v1_services_id parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Service' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Get a service x-api-key-scope: services:read x-required-scope: services:read /v1/services/{id}/analytics: get: description: Request success, traffic, destinations and errors for 24h, 7d or 30d. Analytics can lag recent traffic. operationId: get_v1_services_id_analytics parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string - in: query name: range schema: default: 24h enum: - 24h - 7d - 30d type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Analytics' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Get service analytics x-api-key-scope: services:read x-required-scope: services:read /v1/services/{id}/check: post: description: Runs one request through the service from our side and reports the outcome. Rate limited to a few checks a minute. Use it to tell a proxy problem apart from a target that is refusing you. operationId: post_v1_services_id_check parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/EndpointRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServiceCheckResult' description: Check result; success=false means the bounded proxy request did not complete successfully. '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Check a service end to end x-api-key-scope: proxy:read x-required-scope: proxy:read /v1/services/{id}/endpoints: post: description: Builds connection strings without changing the service. Only use targeting and session options present in the service capabilities. Copy the returned line into your proxy client; credentials in the output are secret. operationId: post_v1_services_id_endpoints parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/EndpointRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/EndpointResponse' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Generate connection strings x-api-key-scope: proxy:read x-required-scope: proxy:read /v1/services/{id}/live-metrics: get: description: Ten-second observed traffic rates in bits per second, UTC daily bytes and recorded proxy outcomes. Read last_activity_at for freshness; silence does not establish healthy idle traffic. Unavailable telemetry returns 503. operationId: get_v1_services_id_live_metrics parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/LiveMetrics' description: Observed metrics; sample freshness is independent of query freshness. '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' default: $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Get live service metrics x-api-key-scope: services:read x-required-scope: services:read /v1/services/{id}/rotate-password: post: description: Returns the new password. The previous password remains valid for a two-minute overlap. Update every client promptly. For an uncertain response, retry with the same Idempotency-Key within 23 hours; do not create a new key for that retry. A replay does not change the password again or restart the overlap. Without a retry key, retrieve the current password with proxy:read before deciding whether another password change is needed. operationId: post_v1_services_id_rotate_password parameters: - description: Optional retry key, formatted as creation time in Unix milliseconds followed by a dot and a UUID. Reuse for retries within 23 hours. Older keys are rejected. in: header name: Idempotency-Key schema: maxLength: 200 type: string - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServiceSecret' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Change the proxy password x-api-key-scope: proxy:write x-required-scope: proxy:write /v1/services/{id}/secret: get: description: Returns the current proxy username and password. Keep the response secret. Management API keys are separate from proxy credentials. operationId: get_v1_services_id_secret parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ServiceSecret' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Get proxy username and password x-api-key-scope: proxy:read x-required-scope: proxy:read /v1/services/{id}/usage: get: description: Traffic counters are bytes; GB balances are decimal gigabytes (1 GB = 1,000,000,000 bytes). Read last_updated_at and provider_observed_at for freshness. Provider balances are present for GB services. operationId: get_v1_services_id_usage parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Usage' description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Get service usage x-api-key-scope: services:read x-required-scope: services:read /v1/services/{id}/whitelist: get: description: Addresses allowed to connect to this service without a proxy password. operationId: get_v1_services_id_whitelist parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string responses: '200': content: application/json: schema: properties: items: items: $ref: '#/components/schemas/WhitelistEntry' type: array required: - items type: object description: ok '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: List trusted IPs x-api-key-scope: proxy:read x-required-scope: proxy:read post: description: Allow a public address or supported CIDR, up to 50 entries per service. An address already assigned to another service returns CONFLICT. After an uncertain response, list entries before retrying. operationId: post_v1_services_id_whitelist parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/WhitelistCreate' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/WhitelistEntry' description: created '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Add a trusted IP x-api-key-scope: proxy:write x-required-scope: proxy:write /v1/services/{id}/whitelist/{entryId}: delete: description: Remove one entry owned by this service. A successful deletion returns no response body. A subsequent read confirms removal. operationId: delete_v1_services_id_whitelist_entryId parameters: - $ref: '#/components/parameters/CustomerId' - in: path name: id required: true schema: format: uuid type: string - in: path name: entryId required: true schema: format: uuid type: string responses: '204': description: deleted '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' '500': $ref: '#/components/responses/Error' '503': $ref: '#/components/responses/Error' security: - customerAPIKey: [] summary: Remove a trusted IP x-api-key-scope: proxy:write x-required-scope: proxy:write servers: - url: https://api.trueproxies.com