openapi: 3.1.0
info:
  title: XProxy Box API
  version: v21.3.2
  summary: HTTP API of the XProxy box controller (the panel on your box).
  description: "Every XProxy box serves this API on its panel address (port 80 by default). Public v1 routes are stable; panel routes are what the box dashboard itself uses and may change between versions. Responses are JSON with `status` (boolean) and `msg` unless noted; most refusals still answer HTTP 200 with `status: false`, so always check `status`."
  contact:
    name: XProxy support
    url: https://xproxy.io/contact
  x-verified-at: 2026-11-17
servers:
  - url: "{scheme}://{host}"
    description: Your box — its LAN address, public domain or VPS-forwarded address.
    variables:
      scheme:
        default: http
        enum:
          - http
          - https
      host:
        default: 192.0.2.10
        description: Box address and optional port, e.g. 192.0.2.10 or box.example.com:8080.
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Dashboard username and password. Required only when the box enforces API auth; see the Authentication guide.
    sellingToken:
      type: apiKey
      in: query
      name: token
      description: Per-shared-proxy API token of the selling platform, given to your end customer.
    vpnToken:
      type: apiKey
      in: query
      name: token
      description: VPN rotation token shown on the box's VPN page.
  schemas:
    StatusMsg:
      type: object
      description: Common result of a Box action. `status` tells success; `msg` carries the outcome code or a short message.
      required:
        - status
        - msg
      properties:
        status:
          type: boolean
          description: True when the box accepted the request.
        msg:
          type: string
          description: Outcome code or message (see the operation's error table).
    ModemStatus:
      type: object
      description: State of one slot. `status` is true only for `MODEM_READY` and `COLLISION_IP`; the IP fields are present only in those two cases.
      required:
        - status
        - msg
      properties:
        status:
          type: boolean
        msg:
          type: string
          enum:
            - MODEM_READY
            - MODEM_RESETTING
            - MODEM_DISCONNECTED
            - MODEM_NOT_FOUND
            - COLLISION_IP
          description: "`MODEM_READY` — online with a public IP. `COLLISION_IP` — online, but the new IP equals the previous one (only when duplicate-IP detection is on). `MODEM_RESETTING` — rotation in progress. `MODEM_DISCONNECTED` — slot exists but has no public IP (also for an empty slot). `MODEM_NOT_FOUND` — no slot with that port or position."
        public_ip:
          type: string
          description: Current public IPv4. While a single IP check fails but the modem is still connected, this is the last known IP.
        public_ip_v6:
          type:
            - string
            - "null"
          description: Current public IPv6, empty or null when the slot has none.
        last_public_ip:
          type:
            - string
            - "null"
          description: Public IPv4 before the latest rotation, null when unknown.
        ipv4:
          type:
            - string
            - "null"
          description: Only for IPv6-multiple slots when IP status reporting is on.
        ipv6:
          type:
            - string
            - "null"
          description: Only for IPv6-multiple slots when IP status reporting is on.
    InfoListItem:
      type: object
      description: One connected modem (only slots with an active data connection are listed).
      properties:
        position:
          type: integer
          description: Slot number.
        host:
          type: string
          description: Box address used in proxy strings.
        proxy_port:
          type: integer
          description: HTTP proxy port (IPv4).
        proxy_port_v6:
          type:
            - integer
            - "null"
          description: HTTP proxy port (IPv6).
        socks5_port:
          type: integer
          description: SOCKS5 port (IPv4).
        socks5_port_ipv6:
          type:
            - integer
            - "null"
          description: SOCKS5 port (IPv6).
        vless_port:
          type:
            - integer
            - "null"
          description: VLESS port when the license and box have it.
        vless_port_v6:
          type:
            - integer
            - "null"
        ss_port:
          type:
            - integer
            - "null"
          description: Shadowsocks port when the license and box have it.
        ss_port_v6:
          type:
            - integer
            - "null"
        public_ip:
          type:
            - string
            - "null"
          description: Current public IPv4.
        public_ip_ipv6:
          type:
            - string
            - "null"
          description: Current public IPv6.
        last_rotation:
          type:
            - number
            - "null"
          description: Unix time (seconds) of the latest rotation.
        last_updated_ip:
          type:
            - number
            - "null"
          description: Unix time (seconds) of the latest public-IP check.
        device_manufacture:
          type:
            - string
            - "null"
          description: Modem type as detected by the box, e.g. HW-Hilink, Android, XLE.
        device_imei:
          type:
            - string
            - "null"
        device_number:
          type:
            - string
            - "null"
          description: SIM phone number when the modem reports it.
        device_ip:
          type:
            - string
            - "null"
          description: Modem address on the box side.
        device_rebooting:
          type:
            - boolean
            - "null"
        device_resetting:
          type:
            - boolean
            - "null"
          description: True while a rotation runs.
        device_extra_info:
          type:
            - object
            - "null"
          description: Modem-specific details (signal, provider, ...). Keys differ per modem type.
          additionalProperties: true
    UnauthorizedForce:
      type: object
      description: Returned when "Basic auth for all API" (`api_auth_check`) is on and the caller is not trusted and sent no valid credentials.
      properties:
        message:
          type: string
          const: Unauthorized
        status:
          type: boolean
          const: false
    UnauthorizedIp:
      type: object
      description: Returned for a route that always needs a login when `api_auth_check` is off and the caller is not trusted.
      properties:
        message:
          type: string
          description: '"Unauthorized. Your IP: " followed by the caller address.'
    TokenUnauthorized:
      type: object
      description: Refusal of a per-port token link.
      properties:
        message:
          type: string
          enum:
            - Not support!
            - Unauthorized!
            - Wrong port!
            - reset_too_much
    HttpError:
      type: object
      description: Generic error body of the box for unhandled errors and malformed requests.
      properties:
        error:
          type: string
          description: Error name, e.g. internal_server_error or bad_request.
        message:
          type: string
    DevicesSerialsBody:
      type: object
      description: Phones to act on. Send `serials`, or `serial` for one phone.
      properties:
        serials:
          type: array
          items:
            type: string
          description: ADB serials of the phones.
        serial:
          type: string
          description: One ADB serial (older clients).
    DevicesBulkResult:
      type: object
      properties:
        status:
          type: boolean
          description: True when at least one phone succeeded.
        success_count:
          type: integer
        failed_count:
          type: integer
        msg:
          type: string
    ModemsPositionBody:
      type: object
      required:
        - position
      properties:
        position:
          type: integer
          minimum: 1
          description: Slot number (position) on the box, starting at 1. A missing or non-integer value makes the box answer HTTP 500.
    ModemsPositionsBody:
      type: object
      required:
        - positions
      properties:
        positions:
          type: array
          items:
            type: integer
            minimum: 1
          description: Slot numbers (positions) to change.
    ModemsDataResult:
      type: object
      description: Result of a Hilink band or signal call. `data` is the modem's answer, the text `Dongle do not support!` for a modem that is not a Huawei Hilink, null for AT/QMI modems, or an empty string when the call failed.
      required:
        - status
        - data
      properties:
        status:
          type: boolean
          description: False when the body was missing, the slot is empty, or the modem call raised an error.
        data:
          description: Modem answer.
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
            - type: "null"
    ModemsCountResult:
      type: object
      properties:
        status:
          type: boolean
        msg:
          type: string
        result:
          type: object
          properties:
            success:
              type: array
              items:
                type: integer
            failed:
              type: array
              items:
                type: integer
    ModemsApnConfig:
      type: object
      description: APN settings. Stored per modem label and applied to the modem.
      required:
        - apn_name
      properties:
        auto_apn:
          type: integer
          enum:
            - 0
            - 1
          description: 1 lets the box detect the APN from the SIM; 0 uses the values below.
        apn_name:
          type: string
          description: APN name given by the carrier.
        ip_type:
          type: integer
          enum:
            - 0
            - 1
            - 2
          description: 0 dual stack, 1 IPv4 only, 2 IPv6 only.
        auth_type:
          type: string
          enum:
            - NONE
            - PAP
            - CHAP
        auth_user:
          type: string
        auth_pass:
          type: string
        persist_config:
          type: integer
          enum:
            - 0
            - 1
          description: 1 re-applies the APN every time the modem connects.
    ModemsStopEvent:
      type: object
      properties:
        id:
          type: integer
        modem_id:
          type: string
          description: Internal device id of the modem.
        position:
          type: integer
        action:
          type: string
          enum:
            - stopped
            - resumed
        stopped_by:
          type:
            - string
            - "null"
          description: Who stopped or resumed it, for example web, ip_guard.
        reason:
          type:
            - string
            - "null"
        created_at:
          description: Time of the event as stored by the box.
    ModemsTcpOsProfile:
      type: object
      properties:
        profile_id:
          type: string
          description: Value to send as `profile`.
        profile_name:
          type: string
        profile_sig:
          type: string
          description: TCP/IP fingerprint signature.
        type:
          type: string
          description: "`system` for built-in profiles."
        ordering:
          type: integer
        queue:
          type: integer
          description: Display order number, starting at 1000.
    ModemsCheck:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          enum:
            - passed
            - warning
            - error
        value:
          type: string
        badge_text:
          type: string
        badge_type:
          type: string
        action_type:
          type:
            - string
            - "null"
        action_label:
          type:
            - string
            - "null"
        detail:
          type: string
      additionalProperties: true
    NetworkDdnsProvider:
      type: object
      description: Saved settings of one DDNS provider plus its run state. `config` holds the provider's credentials (secrets).
      properties:
        id:
          type: string
          description: Same as `type`.
        type:
          type: string
          enum:
            - cloudflare
            - noip
            - duckdns
            - dnsomatic
            - dynu
        enabled:
          type: boolean
        interval_seconds:
          type: integer
          description: Seconds between updates (300 when unset).
        ip_source:
          type: string
          description: Where the IP to publish comes from.
        manual_ip:
          type: string
          description: IP to publish when ip_source is manual.
        config:
          type: object
          description: "Provider credentials. cloudflare: api_token, zone_id, record_name, proxied, ttl. noip: hostname, username, password. duckdns: domain, token. dnsomatic: username, password, hostname. dynu: hostname, username, password_or_key."
          additionalProperties: true
        last_ip:
          type:
            - string
            - "null"
        last_status:
          type:
            - string
            - "null"
          description: Result of the latest update, e.g. updated.
        last_run_at:
          type:
            - integer
            - "null"
        next_run_at:
          type:
            - integer
            - "null"
        error_count:
          type:
            - integer
            - "null"
        health:
          type: string
          enum:
            - inactive
            - ok
            - warn
            - error
            - unknown
          description: Computed by the box. A provider whose next run is overdue is reported as warn or error with last_status "Service not running - check DDNS service".
      additionalProperties: true
    OverviewProxyRow:
      type: object
      description: One slot as the panel proxy list shows it. The controller keeps more internal keys than listed here; treat unknown keys as informational. Users, whitelists and the IMEI are removed from the row.
      additionalProperties: true
      properties:
        position:
          type: integer
          description: Slot number, starting at 1.
        proxy_port:
          type:
            - integer
            - "null"
        socks5_port:
          type:
            - integer
            - "null"
        vless_port:
          type:
            - integer
            - "null"
        ss_port:
          type:
            - integer
            - "null"
        vless_uuid:
          type: string
          description: VLESS client id of the slot (secret). Present only when the slot has a VLESS port.
        ss_password:
          type:
            - string
            - "null"
          description: Shadowsocks password of the slot (secret); null when Shadowsocks is off or not licensed.
        public_ip:
          type:
            - string
            - "null"
          description: Current public IPv4; null when offline or stopped.
        public_ip_v6:
          type:
            - string
            - "null"
        manu:
          type:
            - string
            - "null"
          description: Modem type, for example HW-Hilink, QMI, XH22 or Android.
        ip_status:
          type: string
          enum:
            - empty
            - stopped
            - rotating
            - disconnected
            - duplicate
            - connected
          description: Computed connection state of the slot.
        rebooting:
          type: boolean
        extra_info:
          type: object
          additionalProperties: true
          description: Modem details; `apn` is reduced to the APN name and Wi-Fi/IMEI data is removed.
        rotation_jobs:
          type: integer
          description: Number of scheduled rotation jobs on the slot.
        rotation_next_run:
          type:
            - number
            - "null"
          description: Epoch seconds of the next scheduled rotation.
        ip_score:
          type: integer
          description: Smart IP Guard score of the current IP (0-100). Present when the guard exists.
        repeats:
          type: integer
        freshness:
          type: string
        stopped:
          type: boolean
          description: True when the slot was auto-stopped or stopped by the user.
        stopped_by:
          type:
            - string
            - "null"
        stopped_at:
          type:
            - number
            - "null"
        disconnect:
          type: boolean
    ProxySettingsGroup:
      type: object
      description: "One proxy group: a single shared port (`primary_port`) that spreads clients over the listed slots."
      required:
        - primary_port
        - position_list
      properties:
        primary_port:
          type: integer
          description: Port of the group proxy. Identifies the group.
        position_list:
          type: array
          description: Slots (positions) that serve the group.
          items:
            type: integer
        proxy_type:
          type: string
          enum:
            - "0"
            - "1"
            - "2"
            - "3"
          description: "`0` HTTP over IPv4, `1` SOCKS5 over IPv4, `2` HTTP over IPv6, `3` SOCKS5 over IPv6."
        user_group:
          type: string
          description: Proxy username of the group (empty for none).
        pass_group:
          type: string
          description: Proxy password of the group (empty for none).
        ip_group:
          type: string
          description: Client IPs allowed without a password, comma separated.
        randomize_ip_group:
          type: boolean
          description: When true, each new connection picks a random slot instead of the next one.
      additionalProperties: true
    RotationSettings:
      type: object
      description: Global rotation settings as the Rotation settings page reads and writes them.
      additionalProperties: true
      properties:
        rotation_delay_before_process:
          type: number
          description: Seconds to wait before a rotation starts.
        prevent_time_each_port:
          type: integer
          description: Minimum seconds between two rotations of the same slot.
        delay_rotation_time:
          type: number
        delay_rotation_android_time:
          type: number
        reconnect_isp_failure_time:
          type: integer
        reconnect_isp_failure_max_retry:
          type: integer
        reconnect_ipv6_failure:
          type: boolean
        detect_collision_ip:
          type: boolean
        never_change_ip_automatically:
          type: boolean
          description: When true the box never rotates a slot on its own (no automatic recovery rotations).
        duplicate_ip_rotate_individual_enabled:
          type: boolean
        duplicate_ip_rotate_individual_wait_seconds:
          type: integer
        duplicate_ip_rotate_individual_max_attempts:
          type: integer
        duplicate_ip_rotate_all_modems_enabled:
          type: boolean
        duplicate_ip_rotate_all_modems_wait_seconds:
          type: integer
        duplicate_ip_rotate_all_modems_max_attempts:
          type: integer
        ip_history_guard_enabled:
          type: boolean
          description: Smart IP Guard on or off.
        ip_history_guard_time_window_hours:
          type: integer
        ip_history_guard_max_retries:
          type: integer
        ip_history_guard_backoff_delay:
          type: integer
        ip_history_guard_score_threshold:
          type: integer
        ip_history_guard_fresh_score:
          type: integer
        ip_history_guard_auto_stop_enabled:
          type: boolean
        ip_history_guard_auto_resume_seconds:
          type: integer
        ip_rotation_log_retention_days:
          type: integer
          description: Days of rotation history kept (default 60).
        imei_tc_list:
          type: array
          description: Phone models available for IMEI generation (TAC code as key).
          items:
            type: object
            properties:
              key:
                type: integer
              label:
                type: string
        imei_changer_phone_models:
          type: array
          items: {}
        imei_changer_based_imei:
          type: string
          description: Base IMEIs used by the IMEI changer (one per line).
        imei_changer_option:
          type: integer
        mac_changer_based_addresses:
          type: string
          description: Base MAC addresses (one per line).
        mac_changer_option:
          type: integer
    RotationHistoryRow:
      type: object
      additionalProperties: true
      properties:
        pos:
          type: integer
        current_ip4:
          type: string
        current_ip6:
          type:
            - string
            - "null"
        last_ip4:
          type:
            - string
            - "null"
        last_ip6:
          type:
            - string
            - "null"
        rotation_time:
          type:
            - number
            - "null"
          description: Seconds the rotation took.
        rotation_by:
          type:
            - string
            - "null"
          description: What started the rotation (for example api, schedule, ip_checker).
        stamp_rotation:
          type: integer
          description: Epoch milliseconds of the rotation.
        status:
          type: string
          enum:
            - success
            - failed
            - duplicated
        ip_score:
          type: integer
          description: Present when Smart IP Guard is on.
        freshness:
          type: string
          description: Present when Smart IP Guard is on.
    ScheduleRotationJob:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        position:
          type: integer
        interval:
          type: integer
        unit:
          type: string
          enum:
            - seconds
            - minutes
            - hours
        specific_time:
          type:
            - string
            - integer
            - "null"
          description: Time of day (hh:mm) the job is aligned to.
        start_time:
          type:
            - string
            - "null"
          description: Start of the daily window (hh:mm:ss); null runs all day.
        end_time:
          type:
            - string
            - "null"
        enabled:
          type:
            - integer
            - boolean
        stamp_created:
          type:
            - string
            - integer
        type:
          type: string
          enum:
            - system
            - selling
          description: system jobs come from this API; selling jobs come from a selling port interval rotation.
        next_run:
          type:
            - number
            - "null"
          description: Epoch seconds of the next run.
    SellingLicenseGate:
      type: object
      description: Answer of every `/selling/*` route when the license does not include the Selling Platform.
      properties:
        status:
          type: boolean
          const: false
        msg:
          type: string
    SellingRefusal:
      type: object
      description: Refusal of an end-customer route. Depending on the route and branch the text is in `message` or in `data`.
      properties:
        status:
          type: boolean
          const: false
        message:
          type: string
        data:
          type: string
    SellingIds:
      type: object
      required:
        - ids
      properties:
        ids:
          type: array
          description: Sold-proxy ids (`id` in `/selling/shared_proxies`).
          items:
            type: integer
    SellingProxy:
      type: object
      description: One sold proxy as the panel shows it. Dates are box local time. Contains the customer's credentials (`auth_user_list`), `api_token`, and for Xray ports `vless_uuid`/`ss_password`/`share_link`.
      properties:
        id:
          type: integer
        position:
          type: integer
          description: Slot of a single-destination proxy; 0 for a group proxy.
        group_positions:
          description: Slots of a group proxy.
        gen_method:
          type: integer
          description: 1 single destination, 2 group proxy.
        shared_port:
          type: integer
        port_type:
          type: string
          enum:
            - PROXY
            - HTTP
            - SocksV5
            - VLESS
            - SS
        ip_type:
          type: string
          enum:
            - IPv4
            - IPv6
            - IPv46
            - IPv64
            - N/A
        auth_ip_list:
          type: string
        auth_user_list:
          type: string
          description: user:pass entries.
        web_whitelist:
          type: string
        web_blacklist:
          type: string
        expired_at:
          type: string
          description: Expiry as dd/mm/YYYY HH:MM.
        expired_at_unix:
          type: integer
          description: Expiry in epoch milliseconds.
        remaining:
          type: number
          description: Days left (negative once expired).
        remaining_str:
          type: string
        is_expired:
          type: boolean
        enabled:
          type: boolean
        locked:
          type: boolean
          description: Quota reached; the port is blocked until the counter resets.
        counter_all_limit:
          type: string
          enum:
            - unlimited
            - limited
        counter_all_limit_by:
          type:
            - string
            - "null"
        counter_all_limit_quota:
          type: integer
          description: Quota in MB.
        counter_all_used_mb:
          type: number
        counter_dl_limit:
          type: string
          enum:
            - unlimited
            - limited
        counter_ul_limit:
          type: string
          enum:
            - unlimited
            - limited
        next_reset_time:
          type:
            - string
            - "null"
        bw_limit_enabled:
          type: boolean
        bw_limit_rate:
          type: integer
          description: Mbps.
        connection_limit:
          type: integer
        connection_limit_period:
          type: integer
        idle_timeout:
          type: integer
        interval_rotation:
          type: integer
          description: Seconds; 0 means off.
        allow_api_rotate:
          type: boolean
        min_second_rotate:
          type: integer
        allow_api_change_rotation:
          type: boolean
        min_interval_rotation:
          type: integer
        last_rotation_status:
          type: boolean
        tcp_os:
          type:
            - string
            - "null"
        memo:
          type:
            - string
            - "null"
        tags:
          description: Tag list.
        api_token:
          type: string
        created_at:
          type: string
        renew_date:
          type:
            - integer
            - "null"
        share_link:
          type: string
          description: vless:// or ss:// link; Xray ports only.
      additionalProperties: true
    SellingProxyList:
      type: object
      properties:
        status:
          type: boolean
        data:
          type: array
          items:
            $ref: "#/components/schemas/SellingProxy"
        total:
          type: integer
        stats:
          type: object
          additionalProperties: true
        xraySellingAllowed:
          type: boolean
          description: Whether the license allows VLESS and Shadowsocks selling ports.
    SellingProxyEdit:
      type: object
      description: Fields shared by generate and bulk edit. Counter `*LimitBy` values are 1 daily, 2 weekly, 3 monthly, 4 at end of quota.
      properties:
        portType:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
          description: 0 HTTP and SOCKS5, 1 HTTP, 2 SOCKS5, 3 VLESS (Xray), 4 Shadowsocks (Xray). 3 and 4 need a Premium or Business license.
        ipType:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: 1 IPv4, 2 IPv6, 3 IPv6 then IPv4, 4 IPv4 then IPv6.
        expiredDate:
          type: integer
          description: Expiry in epoch milliseconds.
        ipAuthenticationEntry:
          type: string
          description: Comma-separated IPs allowed without a password.
        userAuthenticationEntry:
          type: string
          description: user:pass entries.
        isAutoGenAuthentication:
          type: boolean
          description: Generate random user:pass instead of userAuthenticationEntry.
        whitelistLimitAccessEntry:
          type: string
          description: Only these domains are reachable.
        blacklistLimitAccessEntry:
          type: string
          description: These domains are blocked.
        bwLimitEnabled:
          type: integer
          enum:
            - 0
            - 1
        bwLimitRate:
          type: integer
          description: Mbps.
        customDNS:
          type: string
        maxConnection:
          type: integer
        maxConnectionPeriod:
          type: integer
        idleTimeout:
          type: integer
          minimum: 1
          maximum: 86400
        counterAllLimit:
          type: integer
          enum:
            - 0
            - 1
        counterAllLimitBy:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
        counterAllQuotaInMB:
          type: integer
        counterDownloadLimit:
          type: integer
          enum:
            - 0
            - 1
        counterDownloadLimitBy:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
        counterDownloadQuotaInMB:
          type: integer
        counterUploadLimit:
          type: integer
          enum:
            - 0
            - 1
        counterUploadLimitBy:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
        counterUploadQuotaInMB:
          type: integer
        forceServerResolveDns:
          type: boolean
        allowApiRotate:
          type: boolean
          description: Let the customer rotate with /selling/rotate.
        minSecondRotate:
          type: integer
          description: Minimum seconds between customer rotations.
        allowApiChangeRotation:
          type: boolean
          description: Let the customer set the auto-rotation interval.
        intervalRotation:
          type: integer
          description: Auto-rotation interval in seconds; 0 off.
        minIntervalRotation:
          type: integer
        sharedEnabled:
          type: boolean
        tcpOS:
          type: string
          description: TCP OS fingerprint profile id (see /selling/tcp_os_profiles).
        memo:
          type: string
        tags:
          type: array
          items:
            type: string
    SellingQuotaInfo:
      type: object
      properties:
        proxy_id:
          type: integer
        shared_port:
          type: integer
        renew_date:
          type:
            - integer
            - "null"
          description: Epoch milliseconds.
        quotas:
          type: object
          description: One entry per limited counter (DL, UL, ALL).
          additionalProperties:
            type: object
            properties:
              limit_by:
                type: string
              quota_mb:
                type: integer
              used_bytes:
                type: integer
              used_mb:
                type: number
              used_dl_mb:
                type: number
              used_ul_mb:
                type: number
              remaining_mb:
                type: number
              last_reset:
                type:
                  - integer
                  - "null"
              next_reset:
                type:
                  - integer
                  - "null"
              seconds_until_reset:
                type: integer
        last_resets:
          type: object
          additionalProperties: true
    SmsUssdMessage:
      type: object
      description: One SMS. Keys vary a little by modem type; content, phone and date are always present.
      additionalProperties: true
      properties:
        content:
          type: string
          description: Message text.
        phone:
          type: string
          description: Sender number.
        date:
          type: string
          description: Receive time as the modem reports it.
        index:
          type: integer
          description: Message index (some modem types).
        id:
          type:
            - integer
            - string
          description: Message id (some modem types).
    CpeLabel:
      type: object
      description: One CPE/LAN device label. A label creates a virtual interface named vcpe plus the label number.
      additionalProperties: true
      properties:
        label:
          type:
            - integer
            - string
        manu:
          type: string
          description: Device type of the CPE.
        address:
          type: string
          description: LAN address of the CPE.
        vlan:
          type:
            - boolean
            - integer
    VpnSlotConfig:
      type: object
      description: VPN server settings of one slot.
      properties:
        vpn_enable:
          type: integer
          enum:
            - 0
            - 1
        number_client:
          type: integer
          description: Number of client profiles.
        enable_vpn_vps:
          type: integer
          enum:
            - 0
            - 1
          description: 1 when the VPN is also published through the VPS relay.
        vpn_mtu:
          type: string
        vpn_type:
          type: string
          enum:
            - wg
            - opvn
          description: "`wg` WireGuard, `opvn` OpenVPN."
        vpn_user:
          type: string
        vpn_pass:
          type: string
          description: OpenVPN login password (secret).
        vpn_expire_at:
          type:
            - string
            - "null"
        vpn_quota_gb:
          type:
            - number
            - "null"
        vpn_quota_used_bytes:
          type: integer
        vpn_rotation_token:
          type:
            - string
            - "null"
          description: Token for the VPN rotation link (secret).
    VpsForwardingRules:
      type: object
      description: Forwarding rules. Offsets are added to the box's local port to get the public VPS port. Keys left out keep their saved value.
      properties:
        vps_relay_adjust_proxy_port:
          type: integer
          description: Offset for proxy ports (also VLESS/Shadowsocks).
        vps_relay_adjust_web_port:
          type: integer
          description: Offset for the dashboard port.
        vps_relay_adjust_selling_port:
          type: integer
          minimum: -65000
          maximum: 65000
        vps_relay_adjust_group_port:
          type: integer
          minimum: -65000
          maximum: 65000
        vps_relay_adjust_vpn_port:
          type: integer
        vps_relay_adjust_ssh_port:
          type: integer
        vps_relay_enable_proxy:
          type: boolean
        vps_relay_enable_selling:
          type: boolean
        vps_relay_enable_group:
          type: boolean
        vps_relay_enable_vpn:
          type: boolean
        vps_relay_enable_web:
          type: boolean
        vps_relay_enable_ssh:
          type: boolean
        vps_net_isolate_enable:
          type: boolean
          description: Network isolation; needs the xrelay engine.
        vps_proc_isolate_enable:
          type: boolean
        vps_socks5_udp_enable:
          type: boolean
        vps_relay_selling_access_log:
          type: boolean
        vps_starting_relay_port:
          type: integer
          minimum: 100
          maximum: 65532
          description: First of the 4 relay tunnel ports on the VPS.
        vps_relay_tunnels:
          type: integer
          minimum: 1
          maximum: 16
          description: Parallel tunnels per port.
        vps_tunnel_stack:
          type: string
          enum:
            - xrelay
            - wireguard
    VpsForwardingPreflight:
      type: object
      description: Security checklist. `blocking` is true when an item has level error; forwarding cannot go live then.
      required:
        - blocking
        - items
      properties:
        client_ip:
          type: string
        license_ok:
          type: boolean
        services:
          type: object
          properties:
            web:
              type: boolean
            proxy:
              type: boolean
        dashboard:
          type: object
          properties:
            password_set:
              type: boolean
            user:
              type: string
        proxy:
          type: object
          properties:
            password_set:
              type: boolean
            user:
              type: string
        blocking:
          type: boolean
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                enum:
                  - license
                  - dash_password
                  - dash_not_exposed
                  - proxy_password
                  - proxy_not_exposed
              scope:
                type: string
                enum:
                  - global
                  - dashboard
                  - proxy
              level:
                type: string
                enum:
                  - ok
                  - info
                  - error
              fix:
                type:
                  - string
                  - "null"
                description: secure_setup when the panel can fix it.
              title:
                type: string
              msg:
                type: string
    VpsForwardingServiceRow:
      type: object
      description: One forwarding service (tunnel or forward) as tracked by the box.
      additionalProperties: true
      properties:
        service_name:
          type: string
          description: Unit name, e.g. xlocal@4001 or xwg@20000.
        svc_type:
          type: string
        modem_position:
          type:
            - integer
            - "null"
        vps_address:
          type:
            - string
            - "null"
        relay_port:
          type:
            - integer
            - "null"
        local_port:
          type:
            - integer
            - "null"
        vps_port:
          type:
            - integer
            - "null"
        status:
          type:
            - string
            - "null"
          description: e.g. running, starting, relay_down.
        service_live:
          type:
            - boolean
            - string
            - "null"
        memory_use:
          type:
            - number
            - string
            - "null"
        last_check:
          type:
            - number
            - "null"
        engine:
          type: string
        network:
          type: string
        conns:
          type:
            - integer
            - "null"
        up_mbps:
          type:
            - number
            - "null"
        down_mbps:
          type:
            - number
            - "null"
    VpsForwardingReach:
      type: object
      description: Public reachability of the proxy ports. `open` is null (unknown) until the probe server answered for that port.
      properties:
        public_ip:
          type: string
        lan_ip:
          type: string
          description: Address the router must forward to.
        checked_at:
          type:
            - string
            - "null"
          description: ISO time (UTC) of the last probe.
        ports:
          type: array
          items:
            type: object
            properties:
              port:
                type: integer
              kind:
                type: string
                enum:
                  - http
                  - socks
                  - http6
                  - socks6
                  - dual
                  - vless
                  - vless6
                  - ss
                  - ss6
              position:
                type:
                  - integer
                  - "null"
              open:
                type:
                  - boolean
                  - "null"
        unavailable:
          type: boolean
          description: True when the probe server could not be reached.
        open_count:
          type: integer
          description: Slots whose ports are all open.
        total:
          type: integer
          description: Slots with listening proxy ports.
        wan:
          type:
            - object
            - "null"
          description: Result of the latest WAN speed test, null if none ran.
          additionalProperties: true
  parameters:
    proxyPath:
      name: proxy
      in: path
      required: true
      description: Proxy address as `HOST:PORT`. Only the port is used to find the slot; the host part is ignored (any non-empty text without a colon works). Use the HTTP or SOCKS5 port shown in the panel or in `/api/v1/info_list`.
      schema:
        type: string
        pattern: ^[^:]+:\d+$
      example: 192.0.2.10:4001
    positionPath:
      name: position
      in: path
      required: true
      description: Slot number (position) on the box, starting at 1. A value that is not an integer makes the box answer HTTP 500.
      schema:
        type: integer
        minimum: 1
      example: 1
    proxyQuery:
      name: proxy
      in: query
      required: true
      description: Proxy address as `HOST:PORT`, for example `192.0.2.10:4001`. Only the port selects the slot.
      schema:
        type: string
        pattern: ^[^:]+:\d+$
      example: 192.0.2.10:4001
    SellingToken:
      name: token
      in: query
      required: true
      x-secret: true
      description: API token of one sold proxy (`api_token` in `/selling/shared_proxies`). Give it only to the customer who rents that proxy; anyone with the link can use it.
      schema:
        type: string
      example: YOUR_SELLING_TOKEN
    SellingLastHours:
      name: last_hours
      in: query
      required: false
      description: Look back this many hours from now. Overrides `start_date` and `end_date`. The range cannot exceed 7 days (168 hours).
      schema:
        type: integer
        minimum: 1
      example: 168
    SellingStartDate:
      name: start_date
      in: query
      required: false
      description: Range start as a Unix timestamp in seconds. Used only together with `end_date` and without `last_hours`.
      schema:
        type: integer
      example: 1763251200
    SellingEndDate:
      name: end_date
      in: query
      required: false
      description: Range end as a Unix timestamp in seconds. Used only together with `start_date` and without `last_hours`.
      schema:
        type: integer
      example: 1763337600
  responses:
    Unauthorized:
      description: The caller is not trusted (not loopback, LAN, whitelisted or allowed Tailscale) and sent no valid Basic credentials. The body depends on whether "Basic auth for all API" is on. Routes that also use the panel login can answer a plain-text 401 "Unauthorized Access" instead.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/UnauthorizedForce"
              - $ref: "#/components/schemas/UnauthorizedIp"
          examples:
            apiAuthOn:
              summary: api_auth_check on
              value:
                message: Unauthorized
                status: false
            apiAuthOff:
              summary: api_auth_check off (login-only route)
              value:
                message: "Unauthorized. Your IP: 203.0.113.25"
    TokenUnauthorized:
      description: Per-port authentication is off, the token is wrong, the port has no modem, or the slot was rotated too recently.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/TokenUnauthorized"
          examples:
            notSupported:
              summary: Per-port authentication off
              value:
                message: Not support!
            badToken:
              summary: Wrong token
              value:
                message: Unauthorized!
    InternalError:
      description: Unhandled error, for example a non-integer position or a missing required parameter.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/HttpError"
          example:
            error: internal_server_error
tags:
  - name: Proxies
    description: List proxies and read the status of one proxy or slot.
  - name: Rotation
    description: Get a new public IP for a proxy, a slot, a group or the whole box.
  - name: Modem reboot
    description: Reboot one modem by proxy or slot.
  - name: Token links
    description: Per-port token links for end users (per-port authentication must be on).
  - name: Min API
    description: Compact API used by some reseller panels.
  - name: VPN rotation
    description: Rotation link for the box VPN.
  - name: Health
    description: Liveness and readiness probes.
  - name: Overview
    description: Box resources, system information and slot lists.
  - name: Modems
    description: Modem actions and settings (connect, label, APN, IMEI, bands, diagnostics).
  - name: Devices
    description: USB adapters and Android NextGen phones.
  - name: Rotation settings
    description: Auto-rotation settings, schedules and history.
  - name: System settings
    description: Box-wide settings, restart and reboot.
  - name: Software
    description: Version, updates and logs.
  - name: Stats & logs
    description: Uptime, rotation analysis and proxy access logs.
  - name: SMS & USSD
    description: Read and send SMS, run USSD codes.
  - name: Selling platform
    description: Shared proxies for your own customers and their self-service links.
  - name: Proxy settings
    description: Proxy users, groups, ports, TCP fingerprint and IP pools.
  - name: Network
    description: DNS, IP checker, DDNS, WAN and IPv6.
  - name: VPN
    description: Box VPN configuration.
  - name: VPS forwarding
    description: Publish proxies through your own VPS.
x-tagGroups:
  - name: Public API
    tags:
      - Proxies
      - Rotation
      - Modem reboot
      - Token links
      - Min API
      - VPN rotation
      - Health
  - name: Panel API
    tags:
      - Overview
      - Modems
      - Devices
      - Rotation settings
      - System settings
      - Software
      - Stats & logs
      - SMS & USSD
      - Selling platform
      - Proxy settings
      - Network
      - VPN
      - VPS forwarding
paths:
  /androidng/list_device_info:
    get:
      operationId: listAndroidDevices
      tags:
        - Devices
      summary: List the NextGen Android phones used as modems and their state
      description: Use this to see which Android phones are attached, authorized and on the right app version. Rows are sorted by position and paged; `total` counts all rows. Each row is the phone's live record (fields vary by app version) plus `auto_install`, `processing_disabled`, `target_swver` and `swver_mismatch`. In Remote VPS mode rows also carry `problem_reason` and `hw_serial`, and enrolled phones that are offline get a row without position. Returns an empty list when NextGen Android support is off.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      parameters:
        - name: page
          in: query
          description: Page number, starting at 1.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Rows per page.
          schema:
            type: integer
            minimum: 1
            default: 10
        - name: showType
          in: query
          description: "`authorized` lists only phones that accepted ADB authorization; anything else lists all."
          schema:
            type: string
            enum:
              - all
              - authorized
            default: all
      responses:
        "200":
          description: Phones.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - total
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                      properties:
                        serial:
                          type: string
                        position:
                          type:
                            - integer
                            - "null"
                        is_authorized:
                          type: boolean
                        swver:
                          type: string
                        target_swver:
                          type: string
                        swver_mismatch:
                          type: boolean
                        auto_install:
                          type: boolean
                        processing_disabled:
                          type: boolean
                        connection_mode:
                          type: string
                        problem_reason:
                          type:
                            - string
                            - "null"
                        hw_serial:
                          type:
                            - string
                            - "null"
                  total:
                    type: integer
              examples:
                phones:
                  summary: One phone
                  value:
                    data:
                      - serial: EXAMPLE_SERIAL_1
                        position: 1
                        is_authorized: true
                        swver: "25"
                        target_swver: "25"
                        swver_mismatch: false
                        auto_install: true
                        processing_disabled: false
                        ppp: rndis0
                    total: 1
                off:
                  summary: NextGen Android support off
                  value:
                    data: []
                    total: 0
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.9.48
  /androidng/reboot_phone:
    post:
      operationId: rebootAndroidPhones
      tags:
        - Devices
      summary: Reboot one or more Android phones used as modems
      description: Use this when a phone stops serving its proxy and restarting the app did not help. Sends a reboot to each phone over ADB and counts successes and failures. `status` is true when at least one phone rebooted.
      x-xproxy-safety: action
      x-stability: panel
      x-hub: routine
      x-agent-note: The proxies of these phones are down for one to three minutes. Ask the user before rebooting many phones. Verify with GET /androidng/list_device_info.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DevicesSerialsBody"
            example:
              serials:
                - EXAMPLE_SERIAL_1
                - EXAMPLE_SERIAL_2
      responses:
        "200":
          description: Counts or a refusal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DevicesBulkResult"
              examples:
                ok:
                  summary: Rebooted
                  value:
                    status: true
                    success_count: 2
                    failed_count: 0
                failed:
                  summary: All failed
                  value:
                    status: false
                    msg: An error when reboot
                    failed_count: 2
                missing:
                  summary: No serial
                  value:
                    status: false
                    msg: Missing parameters
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Missing parameters
          meaning: Neither serials nor serial was sent.
          remedy: Send serials from GET /androidng/list_device_info.
        - msg: An error when reboot
          meaning: No phone accepted the reboot.
          remedy: Check ADB authorization and the USB connection.
        - msg: (exception text)
          meaning: An unexpected error; msg is the error text.
          remedy: Retry; check the box logs if it repeats.
      x-since: v20.9.48
  /androidng/restart_app:
    post:
      operationId: restartAndroidApp
      tags:
        - Devices
      summary: Restart the XProxy app on one or more Android phones
      description: Use this first when an Android phone's proxy stops working; it is faster than a reboot. Restarts the XProxy app on each phone over ADB and counts successes and failures. `status` is true when at least one phone restarted.
      x-xproxy-safety: action
      x-stability: panel
      x-hub: routine
      x-agent-note: The proxies of these phones drop for about 30 s. Ask the user before restarting many phones. Verify with GET /androidng/list_device_info.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DevicesSerialsBody"
            example:
              serials:
                - EXAMPLE_SERIAL_1
      responses:
        "200":
          description: Counts or a refusal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DevicesBulkResult"
              examples:
                ok:
                  summary: Restarted
                  value:
                    status: true
                    success_count: 1
                    failed_count: 0
                failed:
                  summary: All failed
                  value:
                    status: false
                    msg: An error when restart app
                    failed_count: 1
                missing:
                  summary: No serial
                  value:
                    status: false
                    msg: Missing parameters
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Missing parameters
          meaning: Neither serials nor serial was sent.
          remedy: Send serials from GET /androidng/list_device_info.
        - msg: An error when restart app
          meaning: No phone restarted the app.
          remedy: Check ADB authorization; try POST /androidng/reboot_phone.
        - msg: (exception text)
          meaning: An unexpected error; msg is the error text.
          remedy: Retry; check the box logs if it repeats.
      x-since: v20.9.48
  /get_adapter_list:
    get:
      operationId: getAdapterList
      tags:
        - Devices
      summary: List the XLE network adapters and which of their modems answer
      description: "Use this to check XLE multi-modem adapters attached over the network. Each entry has the stored adapter config (`info`) and its state: `main_st` tells whether the adapter answers, `ok` and `err` list its modem labels. `data` is null when no adapter is configured."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Adapters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  data:
                    oneOf:
                      - type: array
                        items:
                          type: object
                          properties:
                            info:
                              type: object
                              additionalProperties: true
                              properties:
                                ip:
                                  type: string
                                manu:
                                  type: string
                                start_label:
                                  type: integer
                                num_modems:
                                  type: integer
                            status:
                              type: object
                              properties:
                                main_st:
                                  type: boolean
                                ok:
                                  type: array
                                  items:
                                    type: integer
                                err:
                                  type: array
                                  items:
                                    type: integer
                      - type: "null"
              examples:
                adapters:
                  summary: One adapter
                  value:
                    status: true
                    data:
                      - info:
                          ip: 192.0.2.60
                          manu: XLE
                          start_label: 1
                          num_modems: 4
                        status:
                          main_st: true
                          ok:
                            - 1
                            - 2
                            - 3
                            - 4
                          err: []
                none:
                  summary: No adapter
                  value:
                    status: true
                    data: null
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /action_adapter:
    post:
      operationId: actionAdapter
      tags:
        - Devices
      summary: Restart or reboot an XLE network adapter
      description: Use this when an XLE adapter's modems stop answering. `reset` restarts the adapter service after 2 s; `reboot` reboots the adapter; `delete` does nothing here (use the panel to remove an adapter). Refused in slave mode. Always answers success otherwise, without checking the adapter.
      x-xproxy-safety: action
      x-stability: panel
      x-hub: approval
      x-agent-note: Every modem behind the adapter goes offline for a minute or more. Ask the user first. Verify with GET /get_adapter_list (main_st true).
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ip
                - action
              properties:
                ip:
                  type: string
                  description: Adapter IP from GET /get_adapter_list.
                action:
                  type: string
                  enum:
                    - reset
                    - reboot
                    - delete
            example:
              ip: 192.0.2.60
              action: reboot
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Sent
                  value:
                    status: true
                    msg: Configuration successfully!
                slave:
                  summary: Slave mode
                  value:
                    status: false
                    msg: Please Turn off Slave mode first!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Please Turn off Slave mode first!
          meaning: The box runs in slave mode and does not manage adapters.
          remedy: Run it on the master box or turn slave mode off.
      x-since: v20.8.0
  /health/live:
    get:
      operationId: healthLive
      tags:
        - Health
      summary: Check that the box web server is running
      description: "Use this as a liveness probe: any answer means the panel process is up. It does not check modems or the proxy engine."
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Always public; no login or token is ever checked.
      security: []
      responses:
        "200":
          description: The web server is running.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: ok
              example:
                status: ok
      x-since: v20.8.0
  /health/ready:
    get:
      operationId: healthReady
      tags:
        - Health
      summary: Check that the box finished starting and can serve proxies
      description: "Use this as a readiness probe after a restart or update. `core_ready` turns true once the controller core finished starting; until then `status` is `degraded`. HTTP 500 with `status: error` means the check itself failed."
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Always public; no login or token is ever checked.
      security: []
      responses:
        "200":
          description: Readiness state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - ok
                      - degraded
                  core_ready:
                    type: boolean
              examples:
                ready:
                  summary: Ready (lab capture)
                  value:
                    status: ok
                    core_ready: true
                starting:
                  summary: Still starting
                  value:
                    status: degraded
                    core_ready: false
        "500":
          description: The readiness check raised an error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    const: error
                  error:
                    type: string
              example:
                status: error
                error: core not initialised
      x-since: v20.8.0
  /status:
    get:
      operationId: getLegacyStatus
      tags:
        - Proxies
      summary: Check whether a proxy is online (legacy query-string form)
      description: Use this only for existing integrations; new code should use `/api/v1/status/proxy/{proxy}`, which answers the same. When the host part of `proxy` is a registered external XProxy server, the box forwards the call to that server unless `internal` is present. A missing or malformed `proxy` answers `invalid_format_proxy`.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: 'Open by default: with "Basic auth for all API" (`api_auth_check`) off, anyone who can reach the box can call it. When it is on, the caller must be trusted (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or send dashboard Basic credentials, which are checked only when dashboard authentication (`dashboard_disable_auth` off) is enabled.'
      security:
        - basicAuth: []
        - {}
      parameters:
        - $ref: "#/components/parameters/proxyQuery"
        - name: internal
          in: query
          description: Any value. Answer from this box even if the host is a registered external server.
          schema:
            type: string
      responses:
        "200":
          description: Slot state, `invalid_format_proxy`, or `external_server_error` when forwarding failed.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ModemStatus"
                  - $ref: "#/components/schemas/StatusMsg"
              examples:
                ready:
                  summary: Online
                  value:
                    status: true
                    msg: MODEM_READY
                    public_ip: 203.0.113.45
                    public_ip_v6: null
                    last_public_ip: 203.0.113.44
                badFormat:
                  summary: Missing or malformed proxy (lab capture)
                  value:
                    status: false
                    msg: invalid_format_proxy
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: MODEM_RESETTING
          meaning: A rotation is running on this slot.
          remedy: Poll again every few seconds.
        - msg: MODEM_DISCONNECTED
          meaning: The slot has no public IP.
          remedy: Check the modem in the panel.
        - msg: MODEM_NOT_FOUND
          meaning: No slot uses this port.
          remedy: Use a port from /api/v1/info_list.
        - msg: invalid_format_proxy
          meaning: proxy is missing or not HOST:PORT.
          remedy: Send proxy=HOST:PORT.
        - msg: external_server_error
          meaning: The external server this host belongs to did not answer within 3 seconds.
          remedy: Check that server or add internal=1.
      x-since: v20.8.0
  /status_by_port:
    get:
      operationId: getLegacyStatusByPort
      tags:
        - Proxies
      summary: Check whether a proxy is online by its port number
      description: Use this when you only know the port. Same answer as the status operations; a missing or non-integer `port` answers HTTP 400 `invalid_port`.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Always needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
        - {}
      parameters:
        - name: port
          in: query
          required: true
          description: HTTP or SOCKS5 port of the proxy.
          schema:
            type: integer
          example: 4001
      responses:
        "200":
          description: Slot state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModemStatus"
              example:
                status: true
                msg: MODEM_READY
                public_ip: 203.0.113.45
                public_ip_v6: null
                last_public_ip: 203.0.113.44
        "400":
          description: port missing or not an integer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              example:
                status: false
                msg: invalid_port
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: MODEM_RESETTING
          meaning: A rotation is running on this slot.
          remedy: Poll again every few seconds.
        - msg: MODEM_DISCONNECTED
          meaning: The slot has no public IP.
          remedy: Check the modem in the panel.
        - msg: MODEM_NOT_FOUND
          meaning: No slot uses this port.
          remedy: Use a port from /api/v1/info_list.
        - msg: COLLISION_IP
          meaning: Online, but the public IP equals the previous one (duplicate-IP detection is on); status is true.
          remedy: Rotate again if a fresh IP is required.
        - msg: invalid_port
          meaning: port is missing or not an integer (HTTP 400).
          remedy: Send port as an integer such as 4001.
      x-since: v20.8.0
  /proxy_list:
    get:
      operationId: getLegacyProxyList
      tags:
        - Proxies
      summary: Get the full internal state of every slot (legacy)
      description: Use this only when you need raw modem fields that `/api/v1/info_list` does not return. Lists every slot, including empty ones, with the box's internal modem record. The field set is the box's internal format and changes between versions.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Always needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
        - {}
      responses:
        "200":
          description: One internal record per slot.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
                  properties:
                    position:
                      type:
                        - integer
                        - string
                    system:
                      type: string
                      description: Box address.
                    proxy_port:
                      type: integer
                    sock_port:
                      type: integer
                    public_ip:
                      type:
                        - string
                        - "null"
                    manu:
                      type:
                        - string
                        - "null"
                      description: Modem type; null for an empty slot.
                    resetting:
                      type: boolean
                    rebooting:
                      type: boolean
              example:
                - position: 1
                  system: 192.0.2.10
                  proxy_port: 4001
                  sock_port: 5001
                  public_ip: 203.0.113.45
                  public_ip_v6: null
                  manu: HW-Hilink
                  imei: "490154203237518"
                  resetting: false
                  rebooting: false
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /reset:
    get:
      operationId: rotateIpLegacy
      tags:
        - Rotation
      summary: Get a new public IP for one proxy (legacy query-string form)
      description: Use this only for existing integrations; new code should use `/api/v1/rotate_ip/proxy/{proxy}`. When a rotation delay is configured the box answers `command_sent` at once and rotates after the delay. A host that is a registered external XProxy server is forwarded unless `internal` is present.
      x-xproxy-safety: action
      x-agent-note: "Changes the public IP and drops connections on the proxy for 10-60 seconds. Do not loop; check `status`, not the HTTP code. This is a GET: never put it where a browser could prefetch it."
      x-stability: public
      x-hub: approval
      x-auth-note: 'Open by default: with "Basic auth for all API" (`api_auth_check`) off, anyone who can reach the box can call it. When it is on, the caller must be trusted (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or send dashboard Basic credentials, which are checked only when dashboard authentication (`dashboard_disable_auth` off) is enabled.'
      security:
        - basicAuth: []
        - {}
      parameters:
        - $ref: "#/components/parameters/proxyQuery"
        - name: internal
          in: query
          description: Any value. Answer from this box even if the host is a registered external server.
          schema:
            type: string
      responses:
        "200":
          description: Rotation accepted or refused.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                sent:
                  summary: Rotation started
                  value:
                    status: true
                    msg: command_sent
                missing:
                  summary: proxy missing
                  value:
                    status: false
                    msg: missing_proxy_parameter
                tooSoon:
                  summary: Too soon after the last rotation
                  value:
                    status: false
                    msg: reset_too_much
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: missing_proxy_parameter
          meaning: proxy is missing.
          remedy: Send proxy=HOST:PORT.
        - msg: invalid_format_proxy
          meaning: proxy is not HOST:PORT.
          remedy: Send proxy=HOST:PORT.
        - msg: command_sent
          meaning: With status true, the rotation started. With status false, the modem did not accept the command.
          remedy: On status false check the slot status before retrying.
        - msg: modem_resetting
          meaning: A rotation is already running.
          remedy: Wait for MODEM_READY.
        - msg: reset_too_much
          meaning: Less than the minimum interval (5 seconds by default) since the last rotation.
          remedy: Wait and retry.
        - msg: modem_disconnected
          meaning: The modem type cannot rotate.
          remedy: Check the modem in the panel.
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license.
        - msg: slot_not_found
          meaning: No slot uses this port.
          remedy: Use a port from /api/v1/info_list.
        - msg: external_server_error
          meaning: The external server did not answer.
          remedy: Check that server or add internal=1.
      x-since: v20.8.0
  /reset_by_port:
    post:
      operationId: rotateIpByPort
      tags:
        - Rotation
      summary: Get a new public IP for a proxy given its port number
      description: Use this when you only know the port. Same result codes as the other rotation operations. A missing or non-integer `port` answers HTTP 500.
      x-xproxy-safety: action
      x-agent-note: Changes the public IP and drops connections on the proxy for 10-60 seconds. Do not loop; check `status`.
      x-stability: public
      x-hub: approval
      x-auth-note: Always needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
        - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - port
              properties:
                port:
                  type: integer
                  description: HTTP or SOCKS5 port of the proxy.
            example:
              port: 4001
      responses:
        "200":
          description: Rotation accepted or refused.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                sent:
                  summary: Rotation started
                  value:
                    status: true
                    msg: command_sent
                notFound:
                  summary: Unknown port
                  value:
                    status: false
                    msg: slot_not_found
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: missing_proxy_parameter
          meaning: proxy is missing.
          remedy: Send proxy=HOST:PORT.
        - msg: invalid_format_proxy
          meaning: proxy is not HOST:PORT.
          remedy: Send proxy=HOST:PORT.
        - msg: command_sent
          meaning: With status true, the rotation started. With status false, the modem did not accept the command.
          remedy: On status false check the slot status before retrying.
        - msg: modem_resetting
          meaning: A rotation is already running.
          remedy: Wait for MODEM_READY.
        - msg: reset_too_much
          meaning: Less than the minimum interval (5 seconds by default) since the last rotation.
          remedy: Wait and retry.
        - msg: modem_disconnected
          meaning: The modem type cannot rotate.
          remedy: Check the modem in the panel.
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license.
        - msg: slot_not_found
          meaning: No slot uses this port.
          remedy: Use a port from /api/v1/info_list.
        - msg: external_server_error
          meaning: The external server did not answer.
          remedy: Check that server or add internal=1.
      x-since: v20.8.0
  /reset_group:
    get:
      operationId: rotateIpGroup
      tags:
        - Rotation
      summary: Get new public IPs for several proxies at once
      description: "Use this to rotate a list of ports in one call: `proxy=HOST:4001,4002,4003`. Every slot with a SIM whose HTTP, SOCKS5 or other proxy port is in the list is rotated in parallel. The answer is always `status: true` once the requests are sent; check each proxy's status for the outcome. A missing `proxy` answers HTTP 500."
      x-xproxy-safety: action
      x-agent-note: Rotates every listed proxy at once and drops their connections. The answer does not say which rotations succeeded; poll each proxy's status afterwards.
      x-stability: public
      x-hub: approval
      x-auth-note: Always needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
        - {}
      parameters:
        - name: proxy
          in: query
          required: true
          description: HOST followed by a colon and a comma-separated list of ports.
          schema:
            type: string
          example: 192.0.2.10:4001,4002,4003
      responses:
        "200":
          description: Requests sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
              example:
                status: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.8.0
  /reset_all:
    get:
      operationId: rotateIpAllLegacy
      tags:
        - Rotation
      summary: Get new public IPs for every proxy on the box
      description: "Use this to rotate every slot that has a SIM in one call. Rotations run in parallel; the answer is `status: true` once all requests are sent and does not report per-slot results. Without the IP rotation feature in the license the answer is `msg: need upgrade` (with a space) and no `status` field."
      x-xproxy-safety: destructive
      x-agent-note: Rotates every proxy on the box and drops every open connection at once. Never call it for a single proxy; confirm with the owner first.
      x-stability: public
      x-hub: approval
      x-auth-note: Always needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
        - {}
      responses:
        "200":
          description: Requests sent, or the license lacks IP rotation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
              examples:
                sent:
                  summary: Requests sent
                  value:
                    status: true
                noLicense:
                  summary: License without IP rotation
                  value:
                    msg: need upgrade
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /reboot_usb:
    get:
      operationId: rebootDongleLegacy
      tags:
        - Modem reboot
      summary: Reboot the modem behind one proxy (legacy query-string form)
      description: Use this only for existing integrations; new code should use `/api/v1/reboot/proxy/{proxy}`. Needs the IP rotation feature in the license (`need_upgrade` otherwise). A non-answering router-type modem gets a USB reset instead.
      x-xproxy-safety: action
      x-agent-note: Takes the proxy offline for up to a few minutes. Use only when status shows the modem offline or broken.
      x-stability: public
      x-hub: approval
      x-auth-note: 'Open by default: with "Basic auth for all API" (`api_auth_check`) off, anyone who can reach the box can call it. When it is on, the caller must be trusted (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or send dashboard Basic credentials, which are checked only when dashboard authentication (`dashboard_disable_auth` off) is enabled.'
      security:
        - basicAuth: []
        - {}
      parameters:
        - $ref: "#/components/parameters/proxyQuery"
      responses:
        "200":
          description: Reboot result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                done:
                  summary: Reboot sent
                  value:
                    status: true
                    msg: Reboot modem done!
                notFound:
                  summary: Unknown port
                  value:
                    status: false
                    msg: Not found!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license.
        - msg: invalid_format_proxy
          meaning: proxy is missing or not HOST:PORT.
          remedy: Send proxy=HOST:PORT.
        - msg: Not found!
          meaning: No slot uses this port.
          remedy: Use a port from /api/v1/info_list.
        - msg: "Reboot failed: modem did not answer"
          meaning: The modem ignored the reboot and no USB reset was possible.
          remedy: Check the modem on site.
        - msg: Modem disconnected!
          meaning: The slot has no modem the box can reboot.
          remedy: Check the modem in the panel.
      x-since: v20.8.0
  /reboot_usb_by_port:
    post:
      operationId: rebootDongleByPort
      tags:
        - Modem reboot
      summary: Reboot the modem behind a proxy given its port number
      description: Use this when you only know the port. Unknown port answers `proxy_not_found`; a missing or non-integer `port` answers HTTP 500. No license check.
      x-xproxy-safety: action
      x-agent-note: Takes the proxy offline for up to a few minutes. Use only when the modem is offline or broken.
      x-stability: public
      x-hub: approval
      x-auth-note: Always needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
        - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - port
              properties:
                port:
                  type: integer
            example:
              port: 4001
      responses:
        "200":
          description: Reboot result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                done:
                  summary: Reboot sent
                  value:
                    status: true
                    msg: Reboot modem done!
                notFound:
                  summary: Unknown port
                  value:
                    status: false
                    msg: proxy_not_found
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.8.0
  /api/min/get-list-position:
    get:
      operationId: minGetListPosition
      tags:
        - Min API
      summary: List every slot with its ports, public IP and access settings
      description: Use this from a reseller panel to see all slots, including empty ones. `status` is `connected` when the slot has a public IPv4 or IPv6, `disconnected` when a modem is present without IP, and `unplugged` when no modem is detected.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Always needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled. "Basic auth for all API" does not change this route.
      security:
        - basicAuth: []
        - {}
      responses:
        "200":
          description: One entry per slot.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    system:
                      type: string
                      description: Box address.
                    position:
                      type: integer
                    proxy_port:
                      type: integer
                    proxy_port_ipv6:
                      type:
                        - integer
                        - "null"
                    sock_port:
                      type: integer
                    sock_port_ipv6:
                      type:
                        - integer
                        - "null"
                    vless_port:
                      type:
                        - integer
                        - "null"
                    ss_port:
                      type:
                        - integer
                        - "null"
                    public_ip:
                      type:
                        - string
                        - "null"
                    public_ip_ipv6:
                      type:
                        - string
                        - "null"
                    status:
                      type: string
                      enum:
                        - connected
                        - disconnected
                        - unplugged
                    authentication_users:
                      type: array
                      description: Proxy users of the slot.
                      items: {}
                    authorization_ips:
                      type:
                        - string
                        - "null"
                      description: Whitelisted client IPs of the slot.
              example:
                - system: 192.0.2.10
                  position: 1
                  proxy_port: 4001
                  proxy_port_ipv6: 6001
                  sock_port: 4001
                  sock_port_ipv6: 6001
                  vless_port: 10001
                  ss_port: 12001
                  public_ip: 203.0.113.45
                  public_ip_ipv6: null
                  status: connected
                  authentication_users: []
                  authorization_ips: null
                - system: 192.0.2.10
                  position: 2
                  proxy_port: 4002
                  proxy_port_ipv6: 6002
                  sock_port: 4002
                  sock_port_ipv6: 6002
                  vless_port: 10002
                  ss_port: 12002
                  public_ip: null
                  public_ip_ipv6: null
                  status: unplugged
                  authentication_users: []
                  authorization_ips: null
        "401":
          description: Caller not trusted and no valid credentials (plain-text body from the login check).
          content:
            text/html:
              schema:
                type: string
              example: Unauthorized Access
      x-since: v20.8.0
  /api/min/get-current-proxy:
    get:
      operationId: minGetCurrentProxy
      tags:
        - Min API
      summary: Read a slot's proxy and set its users and whitelist in one call
      description: Use this from a reseller panel to hand a slot to a customer. Returns the slot's ports and public IP. If `authentication_users` or `authorization_ips` differ from the slot's current values, the box first replaces the slot's proxy users and IP whitelist with the given ones (an omitted parameter counts as empty and clears it). `code` is 1 on success, 2 when `check_proxy=1` and the live proxy test failed, 0 when the slot has no public IP or the update failed.
      x-xproxy-safety: destructive
      x-agent-note: "Not a pure read: calling it without the same users and whitelist the slot already has replaces them and can lock the current customer out. Always pass both parameters with the intended values."
      x-stability: public
      x-hub: approval
      x-auth-note: Always needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled. "Basic auth for all API" does not change this route.
      security:
        - basicAuth: []
        - {}
      parameters:
        - name: position
          in: query
          required: true
          description: Slot number.
          schema:
            type: integer
            minimum: 1
          example: 1
        - name: authentication_users
          in: query
          description: Proxy users for the slot as user:password pairs in the box's user-list format. Omitted means none.
          schema:
            type: string
          example: user1:YOUR_PROXY_PASSWORD
        - name: authorization_ips
          in: query
          description: Client IPs allowed without a password, comma separated. Omitted means none.
          schema:
            type: string
          example: 198.51.100.7
        - name: check_proxy
          in: query
          description: 1 to test the proxy through the box's IP checker before answering.
          schema:
            type: integer
            enum:
              - 0
              - 1
        - name: check_proxy_timedout
          in: query
          description: Timeout of the proxy test in seconds.
          schema:
            type: integer
            default: 3
      responses:
        "200":
          description: Slot details and result code.
          content:
            application/json:
              schema:
                type: object
                properties:
                  proxy_port:
                    type: integer
                  proxy_port_ipv6:
                    type:
                      - integer
                      - "null"
                  sock_port:
                    type: integer
                  sock_port_ipv6:
                    type:
                      - integer
                      - "null"
                  vless_port:
                    type:
                      - integer
                      - "null"
                  ss_port:
                    type:
                      - integer
                      - "null"
                  public_ip:
                    type:
                      - string
                      - "null"
                  public_ip_ipv6:
                    type:
                      - string
                      - "null"
                  status:
                    type: string
                    description: "Got IP successfully., Got IP failed. or Error: followed by the test result."
                  code:
                    type: integer
                    enum:
                      - 0
                      - 1
                      - 2
                  authentication_users:
                    type:
                      - string
                      - "null"
                  authorization_ips:
                    type:
                      - string
                      - "null"
              example:
                proxy_port: 4001
                proxy_port_ipv6: 6001
                sock_port: 4001
                sock_port_ipv6: 6001
                vless_port: 10001
                ss_port: 12001
                public_ip: 203.0.113.45
                public_ip_ipv6: null
                status: Got IP successfully.
                code: 1
                authentication_users: user1:YOUR_PROXY_PASSWORD
                authorization_ips: 198.51.100.7
        "400":
          description: position missing or not an integer, or no such slot.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    enum:
                      - Missing arguments
                      - Not found position
              examples:
                missing:
                  summary: position missing
                  value:
                    message: Missing arguments
                notFound:
                  summary: No such slot
                  value:
                    message: Not found position
        "401":
          description: Caller not trusted and no valid credentials.
          content:
            text/html:
              schema:
                type: string
              example: Unauthorized Access
      x-since: v20.8.0
  /api/min/get-new-proxy:
    get:
      operationId: minGetNewProxy
      tags:
        - Min API
      summary: Set a slot's users and whitelist, then rotate its IP
      description: Intended for reseller panels to rotate a slot. It first replaces the slot's proxy users and IP whitelist with the given values (omitted means empty), then asks for a rotation. In the code at the verified commit the rotation call is missing a required argument, so after the users and whitelist are replaced the box answers HTTP 500 and no rotation happens; use `/api/v1/rotate_ip/position/{position}` to rotate.
      x-xproxy-safety: action
      x-agent-note: Replaces the slot's users and whitelist on every call, and at the verified version fails with HTTP 500 before rotating. Prefer /api/v1/rotate_ip/position/{position}.
      x-stability: public
      x-hub: approval
      x-auth-note: Always needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled. "Basic auth for all API" does not change this route.
      security:
        - basicAuth: []
        - {}
      parameters:
        - name: position
          in: query
          required: true
          description: Slot number.
          schema:
            type: integer
            minimum: 1
          example: 1
        - name: authentication_users
          in: query
          description: Proxy users for the slot as user:password pairs in the box's user-list format. Omitted means none.
          schema:
            type: string
          example: user1:YOUR_PROXY_PASSWORD
        - name: authorization_ips
          in: query
          description: Client IPs allowed without a password, comma separated. Omitted means none.
          schema:
            type: string
          example: 198.51.100.7
      responses:
        "200":
          description: Rotation result (as designed; see the description).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    enum:
                      - 0
                      - 1
                  status:
                    type: string
              examples:
                ok:
                  summary: Rotation started
                  value:
                    code: 1
                    status: Changed IP successfully.
                failed:
                  summary: Rotation refused
                  value:
                    code: 0
                    status: "Changed IP failed. Err: reset_too_much"
        "400":
          description: position missing or not an integer, or no such slot.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    enum:
                      - Missing arguments
                      - Not found position
              example:
                message: Not found position
        "401":
          description: Caller not trusted and no valid credentials.
          content:
            text/html:
              schema:
                type: string
              example: Unauthorized Access
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.8.0
  /v2/rotate_ip:
    post:
      operationId: rotateIpByPosition
      tags:
        - Modems
      summary: Give one modem a new public IP from the panel
      description: Use this to rotate the IP of one slot by its position. Starts the rotation and returns at once; the new IP arrives later. When "rotation delay before process" is set the rotation is scheduled and `msg` is empty. Refused when the modem was stopped, when the license has no IP rotation (except in slave mode), while the modem is already resetting, or when the slot rotated too often.
      x-xproxy-safety: action
      x-stability: panel
      x-hub: routine
      x-agent-note: The proxy on this slot drops connections while the modem reconnects (about 10-60 s). Ask the user before rotating many slots. Verify by polling GET /api/v1/status/position/{position} until it reports MODEM_READY with a new IP.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModemsPositionBody"
            example:
              position: 1
      responses:
        "200":
          description: Rotation started, or a refusal with `status` false.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                sent:
                  summary: Started
                  value:
                    status: true
                    msg: command_sent
                stopped:
                  summary: Modem stopped
                  value:
                    status: false
                    msg: MODEM_STOPPED
                notFound:
                  summary: Empty slot
                  value:
                    status: false
                    msg: slot_not_found
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: MODEM_STOPPED
          meaning: The modem was stopped (by the user or Smart IP Guard).
          remedy: Connect it with POST /v2/connect_dongle first.
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license plan.
        - msg: slot_not_found
          meaning: No modem at this position.
          remedy: Use a position from GET /v2/dongle_device_list.
        - msg: modem_disconnected
          meaning: The modem has no connection to rotate.
          remedy: Reboot the modem and try again.
        - msg: modem_resetting
          meaning: A rotation is already running on this slot.
          remedy: Wait until it finishes.
        - msg: reset_too_much
          meaning: The slot rotated too recently (per-port rotation limit).
          remedy: Wait for the minimum rotation interval and try again.
      x-since: v20.8.0
  /v2/rotate_ip_all:
    post:
      operationId: rotateIpAll
      tags:
        - Modems
      summary: Rotate the IP of every modem on the box at once
      description: Use this to give all modems new IPs in one call. Starts a rotation on every slot (up to 20 in parallel) and returns the outcome per position in `results`, keyed by position. Each entry has the same `msg` codes as POST /v2/rotate_ip. Refused with `need_upgrade` when the license has no IP rotation.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: routine
      x-agent-note: Every proxy on the box drops its connections at the same time. Always ask the user before calling it. Verify with GET /api/v1/info_list after a minute; rows whose result has status false were not rotated.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: No fields are read.
            example: {}
      responses:
        "200":
          description: Per-position outcome, or `need_upgrade`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required:
                      - status
                      - results
                    properties:
                      status:
                        type: boolean
                      results:
                        type: object
                        additionalProperties:
                          $ref: "#/components/schemas/StatusMsg"
                  - $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Rotation started
                  value:
                    status: true
                    results:
                      "1":
                        status: true
                        msg: command_sent
                      "2":
                        status: false
                        msg: MODEM_STOPPED
                noLicense:
                  summary: License without rotation
                  value:
                    status: false
                    msg: need_upgrade
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license plan.
        - msg: error
          meaning: The rotation of that position raised an error (per-position result).
          remedy: Retry that position with POST /v2/rotate_ip.
      x-since: v20.8.0
  /v2/reboot_dongle:
    post:
      operationId: rebootDongle
      tags:
        - Modems
      summary: Reboot one modem when its connection is stuck
      description: Use this when a modem stops passing traffic. AT-command sticks are power-cycled over USB; router-type modems (Hilink, XH20/XH22, CPE) get a reboot command, and when they do not answer the box resets their USB port instead. Needs the IP-rotation license feature.
      x-xproxy-safety: action
      x-stability: panel
      x-hub: routine
      x-agent-note: The proxy on this slot is down for about a minute. Ask the user before rebooting many modems. Verify with GET /api/v1/status/position/{position} until MODEM_READY.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModemsPositionBody"
            example:
              position: 1
      responses:
        "200":
          description: Reboot result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                done:
                  summary: Rebooted
                  value:
                    status: true
                    msg: Reboot modem done!
                usbReset:
                  summary: No answer, USB reset done
                  value:
                    status: true
                    msg: Modem did not answer, USB reset done!
                failed:
                  summary: Failed
                  value:
                    status: false
                    msg: "Reboot failed: modem did not answer"
                notFound:
                  summary: Empty slot
                  value:
                    status: false
                    msg: modem_not_found
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license plan.
        - msg: modem_not_found
          meaning: No modem at this position.
          remedy: Use a position from GET /v2/dongle_device_list.
        - msg: "Reboot failed: modem did not answer"
          meaning: The modem ignored the reboot and the USB reset did not work.
          remedy: Try POST /v2/reset_bus_dongle or replug the modem.
        - msg: Modem disconnected!
          meaning: The modem type cannot be rebooted from the box.
          remedy: Replug the modem.
      x-since: v20.8.0
  /v2/reset_bus_dongle:
    post:
      operationId: resetBusDongle
      tags:
        - Modems
      summary: Reset the USB port of a modem that a normal reboot cannot recover
      description: Use this when POST /v2/reboot_dongle does not bring a modem back. Runs a USB reset of the modem's port. For NextGen Android phones it restarts the XProxy app instead; for XLE adapters it resets the adapter's bus. Needs the IP-rotation license feature. `msg` is empty on success and failure.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: routine
      x-agent-note: The modem disappears from USB and re-enumerates; the slot is down for up to a minute. Ask the user first, never loop it. Verify with GET /api/v1/status/position/{position}.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModemsPositionBody"
            example:
              position: 1
      responses:
        "200":
          description: Reset result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                done:
                  summary: Reset done
                  value:
                    status: true
                    msg: ""
                notFound:
                  summary: Empty slot
                  value:
                    status: false
                    msg: modem_not_found
                xle:
                  summary: XLE adapter not found
                  value:
                    status: false
                    msg: xle_instance_not_found
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license plan.
        - msg: modem_not_found
          meaning: No modem at this position.
          remedy: Use a position from GET /v2/dongle_device_list.
        - msg: xle_instance_not_found
          meaning: The XLE adapter of this slot is not connected.
          remedy: Check the adapter with GET /get_adapter_list.
        - msg: ""
          meaning: "With status false: the USB reset command failed."
          remedy: Replug the modem.
      x-since: v20.8.0
  /v2/connect_dongle:
    post:
      operationId: connectDongle
      tags:
        - Modems
      summary: Start a stopped modem so its proxy works again
      description: Use this to bring a modem back after it was stopped by the user or by Smart IP Guard. Clears the stopped state, logs a `resumed` event and connects the modem. Always answers `status` true unless the license lacks IP rotation.
      x-xproxy-safety: action
      x-stability: panel
      x-hub: routine
      x-agent-note: The proxy starts serving traffic again. Confirm with the user if they stopped it on purpose. Verify with GET /api/v1/status/position/{position}.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModemsPositionBody"
            example:
              position: 1
      responses:
        "200":
          description: Connect requested, or `need_upgrade`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
              examples:
                ok:
                  summary: Requested
                  value:
                    status: true
                noLicense:
                  summary: License without rotation
                  value:
                    status: false
                    msg: need_upgrade
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license plan.
      x-since: v20.8.0
  /v2/disconnect_dongle:
    post:
      operationId: disconnectDongle
      tags:
        - Modems
      summary: Stop a modem and take its proxy offline
      description: Use this to stop a modem on purpose, for example to save data. Marks the slot as stopped by `web`, logs a `stopped` event and disconnects the modem; the stop survives a restart and rotations are refused until POST /v2/connect_dongle. Needs the IP-rotation license feature.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: routine
      x-agent-note: Customers on this proxy lose service until someone reconnects it. Ask the user first. Verify with GET /v2/modem_stop_history or GET /api/v1/status/position/{position} (MODEM_DISCONNECTED).
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModemsPositionBody"
            example:
              position: 1
      responses:
        "200":
          description: Stop requested, or `need_upgrade`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
              examples:
                ok:
                  summary: Stopped
                  value:
                    status: true
                noLicense:
                  summary: License without rotation
                  value:
                    status: false
                    msg: need_upgrade
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license plan.
      x-since: v20.8.0
  /v2/clear_auto_stop:
    post:
      operationId: clearAutoStop
      tags:
        - Modems
      summary: Clear the stopped state of a modem so it can run again
      description: Use this to undo a stop made by Smart IP Guard or the user. Same effect as POST /v2/connect_dongle (clears the stop, logs `resumed`, connects the modem) but without the license check. Always answers `status` true.
      x-xproxy-safety: action
      x-stability: panel
      x-hub: routine
      x-agent-note: The proxy starts serving traffic again. Confirm with the user if they stopped it on purpose. Verify with GET /api/v1/status/position/{position}.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModemsPositionBody"
            example:
              position: 1
      responses:
        "200":
          description: Done.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
              example:
                status: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.9.86
  /v2/modem_stop_history:
    get:
      operationId: getModemStopHistory
      tags:
        - Modems
      summary: See when and why a modem was stopped or resumed
      description: Use this to explain why a slot is offline. Returns up to 50 latest stop and resume events of the modem now at this position, newest first. `status` false with an empty list when no modem is at the position.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      parameters:
        - name: position
          in: query
          required: true
          description: Slot number. A non-integer value makes the box answer HTTP 500.
          schema:
            type: integer
            minimum: 1
          example: 1
      responses:
        "200":
          description: Events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ModemsStopEvent"
              examples:
                events:
                  summary: History
                  value:
                    status: true
                    data:
                      - id: 12
                        modem_id: EXAMPLE_DEVICE_ID
                        position: 1
                        action: resumed
                        stopped_by: web
                        reason: null
                        created_at: 1763370060
                      - id: 11
                        modem_id: EXAMPLE_DEVICE_ID
                        position: 1
                        action: stopped
                        stopped_by: ip_guard
                        reason: null
                        created_at: 1763369000
                empty:
                  summary: No modem at the position
                  value:
                    status: false
                    data: []
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.9.86
  /v2/diagnose_slot:
    post:
      operationId: diagnoseSlot
      tags:
        - Modems
      summary: Run a full health check of one slot to find why its proxy fails
      description: Use this when a proxy does not work and you need the cause. Checks hardware bus, SIM and radio, interface and IP, data plan egress, DNS, proxy services, rotation readiness and upstream network, and returns each check plus a summary with the most important problem first. Takes several seconds. Only reads state but runs network probes through the modem. `tech_diagnostics` includes the caller IP and raw logs.
      x-xproxy-safety: action
      x-stability: panel
      x-hub: routine
      x-agent-note: Runs probes that use a little mobile data; no state is changed. Run it for one slot at a time. Read summary.status and summary.description for the answer.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModemsPositionBody"
            example:
              position: 1
      responses:
        "200":
          description: Diagnosis.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  position:
                    type: integer
                  device_name:
                    type: string
                  interface:
                    type: string
                  proxy_port:
                    type:
                      - integer
                      - "null"
                  sock_port:
                    type:
                      - integer
                      - "null"
                  vless_port:
                    type:
                      - integer
                      - "null"
                  ss_port:
                    type:
                      - integer
                      - "null"
                  overall_status:
                    type: string
                    enum:
                      - passed
                      - warning
                      - error
                  summary:
                    type: object
                    additionalProperties: true
                  checks:
                    type: array
                    items:
                      $ref: "#/components/schemas/ModemsCheck"
                  tech_diagnostics:
                    type: object
                    additionalProperties: true
              example:
                status: true
                position: 1
                device_name: HW-Hilink E3372 (Slot 1)
                interface: eth1
                proxy_port: 4001
                sock_port: 5001
                vless_port: null
                ss_port: null
                overall_status: passed
                summary:
                  status: passed
                  title: All Systems Operational
                  description: Modem hardware, SIM link, interface, data egress, and proxy listeners verified healthy.
                  is_customer_solvable: false
                  action_required: null
                  primary_check_id: null
                  customer_title: All Systems Operational
                  customer_text: Your proxy is working.
                checks:
                  - id: usb_bus
                    name: Hardware Bus
                    status: passed
                    value: Connected & Responding
                    badge_text: Passed
                    badge_type: success
                    action_type: null
                    action_label: null
                    detail: Hardware detected and operational on bus.
                tech_diagnostics:
                  slot_position: 1
                  client_ip: 192.0.2.50
                  execution_time_seconds: 4.2
                  raw_logs: []
        "400":
          description: "`position` missing."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              example:
                status: false
                msg: Missing slot position
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          description: The diagnosis raised an error; `msg` is the error text.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              example:
                status: false
                msg: "invalid literal for int() with base 10: 'a'"
      x-errors:
        - msg: Missing slot position
          meaning: The body has no position.
          remedy: Send position as an integer.
      x-since: v21.1.59
  /v2/speedtest_proxy:
    post:
      operationId: speedtestProxy
      tags:
        - Modems
      summary: Queue a speed test through the proxies of some modems
      description: Use this to measure download speed of slots. Only queues the test (a slot already queued less than a minute ago is skipped); results appear later in the slot data of the panel. One unknown position fails the whole call with the generic error.
      x-xproxy-safety: action
      x-stability: panel
      x-hub: routine
      x-agent-note: Each test downloads data over the mobile connection and can cost the user data allowance. Ask before testing many slots. Verify later in GET /v2/dongle_device_list (speedtest fields).
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModemsPositionsBody"
            example:
              positions:
                - 1
                - 2
      responses:
        "200":
          description: Queued, or the generic error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Queued
                  value:
                    status: true
                    msg: Successfully enqueued speedtest!
                error:
                  summary: Bad body or unknown position
                  value:
                    status: false
                    msg: Have an error during request! Contact administrator!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Have an error during request! Contact administrator!
          meaning: positions missing or one position has no modem.
          remedy: Send only positions that hold a modem.
      x-since: v20.8.0
  /signal_info:
    get:
      operationId: getSignalInfo
      tags:
        - Modems
      summary: Read radio signal values (RSRP, SINR, band, cell) of one Huawei Hilink modem
      description: Use this to check reception of a Huawei Hilink modem. Works only for `HW-Hilink` modems; other router-type modems return the text `Dongle do not support!` and AT/QMI modems return null data. The position is read from a JSON request body even though the method is GET; a query parameter is ignored and the call then answers `status` false.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        description: Must be sent as a JSON body with Content-Type application/json.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModemsPositionBody"
            example:
              position: 1
      responses:
        "200":
          description: Signal values or a refusal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModemsDataResult"
              examples:
                hilink:
                  summary: Huawei Hilink
                  value:
                    status: true
                    data:
                      pci: "123"
                      cell_id: "25601"
                      rsrq: -8.0dB
                      rsrp: -95dBm
                      rssi: -67dBm
                      sinr: 12dB
                      mode: "7"
                      band: "3"
                      dlbandwidth: 20MHz
                      ulbandwidth: 20MHz
                      eNB: "100"
                      Cell: "1"
                unsupported:
                  summary: Other modem type
                  value:
                    status: true
                    data: Dongle do not support!
                failed:
                  summary: No body or empty slot
                  value:
                    status: false
                    data: ""
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Dongle do not support!
          meaning: (in data) The modem is not a Huawei Hilink.
          remedy: Use the panel tools of that modem type.
        - msg: ""
          meaning: (data empty, status false) No JSON body, empty slot, or the modem did not answer.
          remedy: Send position in a JSON body and check the modem is online.
      x-since: v20.8.0
  /band_list:
    get:
      operationId: getBandList
      tags:
        - Modems
      summary: List the network modes and bands a Huawei Hilink modem supports
      description: Use this before POST /set_band to see valid values. Works only for `HW-Hilink` modems; others return `Dongle do not support!` or null data. The position is read from a JSON request body even though the method is GET.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        description: Must be sent as a JSON body with Content-Type application/json.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModemsPositionBody"
            example:
              position: 1
      responses:
        "200":
          description: Supported modes and bands or a refusal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModemsDataResult"
              examples:
                hilink:
                  summary: Huawei Hilink
                  value:
                    status: true
                    data:
                      AccessList:
                        Access:
                          - "00"
                          - "03"
                          - "02"
                      BandList:
                        Band:
                          - Name: GSM900/GSM1800
                            Value: "80300"
                      LTEBandList:
                        Band:
                          - Name: LTE BC1/LTE BC3
                            Value: "5"
                unsupported:
                  summary: Other modem type
                  value:
                    status: true
                    data: Dongle do not support!
                failed:
                  summary: No body or empty slot
                  value:
                    status: false
                    data: ""
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Dongle do not support!
          meaning: (in data) The modem is not a Huawei Hilink.
          remedy: Use the panel tools of that modem type.
        - msg: ""
          meaning: (data empty, status false) No JSON body, empty slot, or the modem did not answer.
          remedy: Send position in a JSON body and check the modem is online.
      x-since: v20.8.0
  /current_band:
    get:
      operationId: getCurrentBand
      tags:
        - Modems
      summary: Read the network mode and band lock a Huawei Hilink modem uses now
      description: Use this to check the current band lock. Works only for `HW-Hilink` modems; others return `Dongle do not support!` or null data. The position is read from a JSON request body even though the method is GET.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        description: Must be sent as a JSON body with Content-Type application/json.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModemsPositionBody"
            example:
              position: 1
      responses:
        "200":
          description: Current mode or a refusal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModemsDataResult"
              examples:
                hilink:
                  summary: Huawei Hilink
                  value:
                    status: true
                    data:
                      NetworkMode: "00"
                      NetworkBand: 3FFFFFFF
                      LTEBand: 7FFFFFFFFFFFFFFF
                unsupported:
                  summary: Other modem type
                  value:
                    status: true
                    data: Dongle do not support!
                failed:
                  summary: No body or empty slot
                  value:
                    status: false
                    data: ""
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Dongle do not support!
          meaning: (in data) The modem is not a Huawei Hilink.
          remedy: Use the panel tools of that modem type.
        - msg: ""
          meaning: (data empty, status false) No JSON body, empty slot, or the modem did not answer.
          remedy: Send position in a JSON body and check the modem is online.
      x-since: v20.8.0
  /set_band:
    post:
      operationId: setBand
      tags:
        - Modems
      summary: Lock a Huawei Hilink modem to some bands or a network mode
      description: Use this to force a modem onto a band or 4G only. Works only for `HW-Hilink` modems. Values are hexadecimal masks as returned by GET /band_list; a missing field resets to all (`NetworkMode` 00 auto, `NetworkBand` 3FFFFFFF, `LTEBand` 7FFFFFFFFFFFFFFF). The modem re-registers on the network.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: A wrong band lock can leave the modem without signal until it is reset. Ask the user and keep the old values from GET /current_band to restore them. Verify with GET /current_band and GET /signal_info.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - position
              properties:
                position:
                  type: integer
                  minimum: 1
                NetworkMode:
                  type: string
                  description: Network mode code, for example 00 auto, 03 4G only, 02 3G only.
                NetworkBand:
                  type: string
                  description: 2G/3G band mask (hex).
                LTEBand:
                  type: string
                  description: LTE band mask (hex).
            example:
              position: 1
              NetworkMode: "03"
              NetworkBand: 3FFFFFFF
              LTEBand: "5"
      responses:
        "200":
          description: Modem answer or a refusal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModemsDataResult"
              examples:
                ok:
                  summary: Applied
                  value:
                    status: true
                    data: OK
                unsupported:
                  summary: Other modem type
                  value:
                    status: true
                    data: Dongle do not support!
                failed:
                  summary: Rejected or empty slot
                  value:
                    status: false
                    data: ""
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Dongle do not support!
          meaning: (in data) The modem is not a Huawei Hilink.
          remedy: Use the panel tools of that modem type.
        - msg: ""
          meaning: (data empty, status false) No JSON body, empty slot, or the modem did not answer.
          remedy: Send position in a JSON body and check the modem is online.
      x-since: v20.8.0
  /v2/change_apn:
    post:
      operationId: changeApn
      tags:
        - Modems
      summary: Set the APN of one or more modems
      description: Use this when a SIM needs a specific APN to get data. Saves the APN for each modem's label and applies it to the modem; `result` lists which positions succeeded and failed. `status` is true even when some positions failed. The modem reconnects with the new APN. The request contains the APN password.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: A wrong APN cuts mobile data on those modems. Ask the user for the carrier's APN values before calling. Verify with result.failed being empty and GET /api/v1/status/position/{position}.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - positions
                - apn
              properties:
                positions:
                  type: array
                  items:
                    type: integer
                    minimum: 1
                apn:
                  $ref: "#/components/schemas/ModemsApnConfig"
            example:
              positions:
                - 1
                - 2
              apn:
                auto_apn: 0
                apn_name: internet
                ip_type: 0
                auth_type: NONE
                auth_user: ""
                auth_pass: YOUR_APN_PASSWORD
                persist_config: 1
      responses:
        "200":
          description: Outcome per position, or the generic error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModemsCountResult"
              examples:
                ok:
                  summary: All changed
                  value:
                    status: true
                    msg: APN changed successfully for 2 devices!
                    result:
                      success:
                        - 1
                        - 2
                      failed: []
                partial:
                  summary: Some failed
                  value:
                    status: true
                    msg: APN changed for 1 devices. 1 failed.
                    result:
                      success:
                        - 1
                      failed:
                        - 2
                error:
                  summary: Bad body
                  value:
                    status: false
                    msg: Sent change APN failed. Please try again later!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Sent change APN failed. Please try again later!
          meaning: positions or apn missing.
          remedy: Send both fields.
        - msg: APN changed for N devices. M failed.
          meaning: Some positions are empty or the modem rejected the APN.
          remedy: Check result.failed and the modem type.
      x-since: v20.8.0
  /v2/change_label:
    post:
      operationId: changeLabel
      tags:
        - Modems
      summary: Change the label number of a modem
      description: Use this to give a modem a fixed label number (used for sorting and per-label settings such as APN). Hilink, ZTE, XProxy (XH20/XH22) and Alcatel modems store it on the device; other modems with a serial number store it in the box database. On success the modem reboots to apply it.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: routine
      x-agent-note: The modem reboots and its proxy is down for about a minute; per-label settings follow the new label. Ask the user first. Verify with GET /v2/dongle_device_list.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - position
                - label
              properties:
                position:
                  type: integer
                  minimum: 1
                label:
                  type: integer
                  description: New label number.
            example:
              position: 1
              label: 101
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Changed
                  value:
                    status: true
                    msg: Changed Label Done! Please waiting for auto reboot to take effect!
                notFound:
                  summary: Empty slot
                  value:
                    status: false
                    msg: modem_not_found
                unsupported:
                  summary: Not supported
                  value:
                    status: false
                    msg: Modem is not support for changing Label!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: modem_not_found
          meaning: No modem at this position.
          remedy: Use a position from GET /v2/dongle_device_list.
        - msg: An error when changing Label
          meaning: The modem rejected the label.
          remedy: Reboot the modem and try again.
        - msg: Modem is not support for changing Label!
          meaning: The modem has no serial number and no label support.
          remedy: None; this modem type cannot be labelled.
        - msg: Sent change IMEI failed. Please try again later!
          meaning: position or label missing or not an integer (the box reuses the IMEI text here).
          remedy: Send both as integers.
      x-since: v20.8.0
  /v2/change_device_note:
    post:
      operationId: changeDeviceNote
      tags:
        - Modems
      summary: Add or change the free-text note of a modem
      description: Use this to attach a note (owner, SIM plan, location) to a modem. Stored in the box database by device id, so it follows the modem if it moves to another slot. No reboot.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: routine
      x-agent-note: Overwrites the existing note. Read the current note from GET /v2/dongle_device_list first if it should be kept. Verify there afterwards.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - position
                - note
              properties:
                position:
                  type: integer
                  minimum: 1
                note:
                  type: string
            example:
              position: 1
              note: SIM prepaid 30 GB
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                    msg: Change device note of device successfully!
                failed:
                  summary: Empty slot or bad body
                  value:
                    status: false
                    msg: Sent change device note failed. Please try again later!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Sent change device note failed. Please try again later!
          meaning: No modem at the position or a field is missing.
          remedy: Use a position that holds a modem and send note.
      x-since: v20.8.0
  /v2/change_position:
    post:
      operationId: changePosition
      tags:
        - Modems
      summary: Swap two slots so a modem moves to another slot number
      description: Use this to reorder modems. Swaps the device data of the two positions; ports, VLESS/Shadowsocks credentials and other slot-bound settings stay with the slot number. Both slots' proxies are taken down and brought up again. Both positions must exist within the licensed modem count.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Customers using these two ports get the other modem's IP and both proxies restart. Ask the user first. Verify with GET /v2/dongle_device_list.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - from_position
                - to_position
              properties:
                from_position:
                  type: integer
                  minimum: 1
                to_position:
                  type: integer
                  minimum: 1
            example:
              from_position: 1
              to_position: 3
      responses:
        "200":
          description: Result; `msg` is empty on success.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Swapped
                  value:
                    status: true
                    msg: ""
                invalid:
                  summary: Out of range
                  value:
                    status: false
                    msg: Invalid position
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Invalid position
          meaning: A position is below 1 or above the licensed modem count.
          remedy: Use positions within the license.
        - msg: Positions are the same
          meaning: from_position equals to_position.
          remedy: Pick two different slots.
        - msg: Position info not found
          meaning: A slot has no record yet.
          remedy: Use slots shown in the panel.
      x-since: v20.9.99
  /get_dongle_settings:
    post:
      operationId: getDongleSettings
      tags:
        - Modems
      summary: Read the MTU, TTL and active SIM slot of one modem
      description: Use this before POST /update_dongle_settings. Returns the stored MTU (default 1500), TTL (0 means not changed) and the active SIM slot (1 when the modem cannot report it). On an internal error the defaults are returned with `status` true.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pos
              properties:
                pos:
                  type: integer
                  minimum: 1
                  description: Slot number.
            example:
              pos: 1
      responses:
        "200":
          description: Settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  data:
                    type: object
                    properties:
                      mtu:
                        type:
                          - string
                          - integer
                      ttl:
                        type: integer
                      simSlot:
                        type:
                          - string
                          - integer
                    additionalProperties: true
              example:
                status: true
                data:
                  mtu: "1500"
                  simSlot: "1"
                  ttl: 0
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.8.0
  /update_dongle_settings:
    post:
      operationId: updateDongleSettings
      tags:
        - Modems
      summary: Change the MTU, TTL or active SIM slot of one modem
      description: "Use this to tune one modem. `type` picks the setting: `mtu` saves and applies `data.mtu` to the interface, `ttl` saves and applies `data.ttl` (0 turns TTL rewriting off), `sim` switches the modem to `data.simSlot` (dual-SIM modems only; the modem reconnects on the other SIM)."
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: A bad MTU or a SIM switch can break the proxy of this slot. Ask the user first and note the old values from POST /get_dongle_settings. Verify there afterwards.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pos
                - type
                - data
              properties:
                pos:
                  type: integer
                  minimum: 1
                  description: Slot number.
                type:
                  type: string
                  enum:
                    - mtu
                    - ttl
                    - sim
                data:
                  type: object
                  properties:
                    mtu:
                      type:
                        - string
                        - integer
                      description: MTU, typically 1280-1500. Used with type mtu.
                    ttl:
                      type: integer
                      description: Outgoing TTL; 0 disables. Used with type ttl.
                    simSlot:
                      type:
                        - string
                        - integer
                      description: SIM slot to use. Used with type sim.
            examples:
              mtu:
                summary: Set MTU
                value:
                  pos: 1
                  type: mtu
                  data:
                    mtu: "1400"
              ttl:
                summary: Set TTL
                value:
                  pos: 1
                  type: ttl
                  data:
                    ttl: 65
              sim:
                summary: Switch SIM
                value:
                  pos: 1
                  type: sim
                  data:
                    simSlot: "2"
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
              examples:
                mtu:
                  summary: MTU saved
                  value:
                    status: true
                ttl:
                  summary: TTL saved
                  value:
                    status: true
                    msg: TTL configured successfully!
                sim:
                  summary: SIM switched
                  value:
                    status: true
                    msg: Configuration successfully!
                unsupported:
                  summary: Unknown type or no dual SIM
                  value:
                    status: false
                    msg: Dongle not supported!
                failed:
                  summary: Bad body
                  value:
                    status: false
                    msg: Configuration failed!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Dongle not supported!
          meaning: Unknown type, or the modem cannot switch SIM slots.
          remedy: Use type mtu, ttl or sim; SIM switch needs a dual-SIM modem.
        - msg: Configuration failed!
          meaning: A field is missing or the value is invalid.
          remedy: Send pos, type and data with the matching key.
      x-since: v20.8.0
  /v2/change_mac_address:
    post:
      operationId: changeMacAddress
      tags:
        - Modems
      summary: Change the MAC address of one or more modems
      description: Use this to give modems new MAC addresses. Supported on XProxy XH20/XH22 modems; others are skipped silently. Mode 1 generates a random address based on `mac.mac`; mode 2 sets `mac.mac` as given. Each changed modem reboots. The answer is success even when some modems were skipped.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Modems reboot and get new LAN identities; the proxies are down for about a minute. Ask the user first. Verify after 15 s in GET /v2/dongle_device_list.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - positions
                - mac
              properties:
                positions:
                  type: array
                  items:
                    type: integer
                    minimum: 1
                mac:
                  type: object
                  required:
                    - mode
                    - mac
                  properties:
                    mode:
                      type: integer
                      enum:
                        - 1
                        - 2
                      description: 1 random based on mac; 2 exact mac.
                    mac:
                      type: string
                      description: MAC address with colons or dashes.
            example:
              positions:
                - 1
              mac:
                mode: 2
                mac: 02:00:00:00:00:01
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Sent
                  value:
                    status: true
                    msg: Sent change MAC successfully! Please wait up to 15s to effect!
                failed:
                  summary: Bad body
                  value:
                    status: false
                    msg: Sent change MAC failed. Please try again later!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Sent change MAC failed. Please try again later!
          meaning: positions or mac missing or malformed.
          remedy: Send positions and mac with mode and mac.
      x-since: v20.8.0
  /v2/imei_change_in_bulk:
    post:
      operationId: changeImei
      tags:
        - Modems
      summary: Change the IMEI of one or more modems
      description: Use this only when the user asks to change modem IMEIs. Option 1 uses IMEIs from `imei_list` (one per position in order when the counts match, otherwise random picks); option 2 generates an IMEI from a random TAC in `phone_models`; option 3 generates one from the first 8 digits of `based_imei`. Each changed modem reboots. Stops at the first modem that rejects the change. Positions without a modem are skipped and still reported as success, and errors inside the loop (for example option 1 without `imei_list`) are swallowed, so a success answer does not prove any IMEI changed.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: "Risky: the carrier may block the SIM, and changing IMEI may be illegal in the user's country. Always get explicit approval for each batch. Verify the new IMEI in GET /v2/dongle_device_list after the reboot."
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - positions
                - imei_changer_option
              properties:
                positions:
                  type: array
                  items:
                    type: integer
                    minimum: 1
                imei_changer_option:
                  type: integer
                  enum:
                    - 1
                    - 2
                    - 3
                imei_list:
                  type: string
                  description: "Option 1: text containing 15-digit IMEIs (any separator)."
                phone_models:
                  type: array
                  items:
                    type: string
                  description: "Option 2: TAC codes of phone models."
                based_imei:
                  type: string
                  description: "Option 3: an IMEI or its first 8 digits."
            examples:
              list:
                summary: Option 1
                value:
                  positions:
                    - 1
                  imei_changer_option: 1
                  imei_list: "490154203237518"
              model:
                summary: Option 2
                value:
                  positions:
                    - 1
                    - 2
                  imei_changer_option: 2
                  phone_models:
                    - "35332510"
              based:
                summary: Option 3
                value:
                  positions:
                    - 1
                  imei_changer_option: 3
                  based_imei: "49015420"
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Sent
                  value:
                    status: true
                    msg: Sent change IMEI successfully. Waiting for dongles reboot!
                failed:
                  summary: Modem rejected
                  value:
                    status: false
                    msg: Sent change IMEI failed. Try again!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Please choice at least a brand/model!
          meaning: Option 2 with an empty phone_models list.
          remedy: Send at least one TAC.
        - msg: Please fill valid IMEI!
          meaning: Option 3 with fewer than 8 digits in based_imei.
          remedy: Send at least the first 8 digits.
        - msg: Sent change IMEI failed. Try again!
          meaning: A modem rejected the change; later positions were not processed.
          remedy: Check the modem type supports IMEI change and retry the remaining positions.
      x-since: v20.8.0
  /v2/wifi_change_in_bulk:
    post:
      operationId: changeWifi
      tags:
        - Modems
      summary: Turn the Wi-Fi of one or more modems on or off
      description: Use this to switch modem Wi-Fi hotspots. XProxy XH20/XH22 modems set Wi-Fi to `state`; NextGen Android phones toggle it; other modems are skipped. The answer is success even when modems were skipped.
      x-xproxy-safety: action
      x-stability: panel
      x-hub: approval
      x-agent-note: Devices connected to the modem Wi-Fi lose access when it is turned off. Ask the user first. There is no read-back route; check the modem itself.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - positions
                - state
              properties:
                positions:
                  type: array
                  items:
                    type: integer
                    minimum: 1
                state:
                  type: boolean
                  description: true turns Wi-Fi on, false turns it off.
            example:
              positions:
                - 1
                - 2
              state: false
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Sent
                  value:
                    status: true
                    msg: Sent change Wi-Fi successfully!
                failed:
                  summary: Bad body
                  value:
                    status: false
                    msg: Sent change Wi-Fi failed. Please try again later!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Sent change Wi-Fi failed. Please try again later!
          meaning: positions or state missing.
          remedy: Send both fields.
      x-since: v20.8.0
  /v2/get_dongle_info:
    post:
      operationId: getDongleInfo
      tags:
        - Modems
      summary: Read the phone number of a modem's SIM
      description: Use this to find the SIM's phone number. Asks the modem for its own number (AT+CNUM or the modem API) and returns the request body with `phone_number` filled in. Many SIMs do not store their number, which gives the failure message. `phone_number` must be present and truthy in the request; without it the box answers HTTP 500.
      x-xproxy-safety: action
      x-stability: panel
      x-hub: approval
      x-agent-note: Only reads from the modem but sends a command to it; avoid calling it for many modems in a row. The result is in data.phone_number.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - position
                - phone_number
              properties:
                position:
                  type: integer
                  minimum: 1
                phone_number:
                  type: boolean
                  description: Must be true.
            example:
              position: 1
              phone_number: true
      responses:
        "200":
          description: Number found or not.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: object
                    properties:
                      position:
                        type: integer
                      phone_number:
                        type: string
              examples:
                ok:
                  summary: Found
                  value:
                    status: true
                    data:
                      position: 1
                      phone_number: "+15550100"
                failed:
                  summary: Not available
                  value:
                    status: false
                    msg: Read dongle information Failed try again
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Read dongle information Failed try again
          meaning: The SIM does not store its number or the modem did not answer.
          remedy: Get the number by USSD or from the carrier.
      x-since: v20.8.0
  /v2/slot_config/tcp_os_get:
    get:
      operationId: getSlotTcpOs
      tags:
        - Modems
      summary: Read which TCP/OS fingerprint profile a slot uses
      description: Use this to see the OS fingerprint a proxy presents. `profile` is a profile id from GET /v2/tcp_os_profiles, or null when none was set.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      parameters:
        - name: position
          in: query
          required: true
          description: Slot number within the licensed modem count.
          schema:
            type: integer
            minimum: 1
          example: 1
      responses:
        "200":
          description: Profile or a refusal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: object
                    properties:
                      position:
                        type: integer
                      profile:
                        type:
                          - string
                          - "null"
              examples:
                ok:
                  summary: Profile
                  value:
                    status: true
                    data:
                      position: 1
                      profile: windows
                invalid:
                  summary: Bad position
                  value:
                    status: false
                    msg: Invalid position!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Invalid position!
          meaning: position missing, not an integer, or outside the licensed count.
          remedy: Send a valid slot number.
      x-since: v20.8.0
  /v2/slot_config/tcp_os_set:
    post:
      operationId: setSlotTcpOs
      tags:
        - Modems
      summary: Set the TCP/OS fingerprint profile of one or more slots
      description: Use this to make proxies look like another OS (Windows, macOS, iOS, Android). Saves the profile per slot and applies it without restarting the proxy; empty slots keep the setting for their next modem. Needs the TCP/OS license feature and cgroup (WebRTC) support enabled on the box.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Changes the fingerprint customers see on these ports. Ask the user first. Verify with GET /v2/slot_config/tcp_os_get.
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - positions
                - profile
              properties:
                positions:
                  description: Slot numbers; a single number is accepted too.
                  oneOf:
                    - type: array
                      items:
                        type: integer
                        minimum: 1
                    - type: integer
                profile:
                  type: string
                  description: profile_id from GET /v2/tcp_os_profiles.
            example:
              positions:
                - 1
                - 2
              profile: windows
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                    msg: Configuration successfully!
                invalidProfile:
                  summary: Unknown profile
                  value:
                    status: false
                    msg: Invalid profile!
                noLicense:
                  summary: License without TCP/OS
                  value:
                    status: false
                    msg: This function supported for higher plan. Please upgrade to use!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: This function supported for higher plan. Please upgrade to use!
          meaning: The license does not include TCP/OS spoofing.
          remedy: Upgrade the license plan.
        - msg: webrtc_required
          meaning: cgroup support is off on the box.
          remedy: Enable it in system settings first.
        - msg: Invalid position!
          meaning: A position is missing, not an integer, or outside the licensed count.
          remedy: Send valid slot numbers.
        - msg: Invalid profile!
          meaning: profile is not a known profile id.
          remedy: Pick one from GET /v2/tcp_os_profiles.
      x-since: v20.8.0
  /v2/tcp_os_profiles:
    get:
      operationId: getTcpOsProfiles
      tags:
        - Modems
      summary: List the TCP/OS fingerprint profiles available on the box
      description: Use this to get valid `profile` values for POST /v2/slot_config/tcp_os_set. Lists built-in (`system`) and custom profiles in display order. `data` is null when the profile table cannot be read.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs dashboard Basic credentials when dashboard authentication is enabled; trusted callers (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) pass without them.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Profiles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  data:
                    oneOf:
                      - type: array
                        items:
                          $ref: "#/components/schemas/ModemsTcpOsProfile"
                      - type: "null"
              example:
                status: true
                data:
                  - profile_id: linux
                    profile_name: Linux
                    profile_sig: EXAMPLE_SIGNATURE
                    type: system
                    ordering: 0
                    queue: 1000
                  - profile_id: windows
                    profile_name: Windows 10/11
                    profile_sig: EXAMPLE_SIGNATURE
                    type: system
                    ordering: 1
                    queue: 1001
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /update_dns_config:
    get:
      operationId: getDnsConfig
      tags:
        - Network
      summary: Read the DNS servers used by the box and by the proxies
      description: Returns the system DNS list, the DNS list the proxies resolve with, whether proxies use the modem's DNS, and whether VPN clients get the modem DNS.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: DNS settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      dns_system_list:
                        type:
                          - string
                          - "null"
                        description: System resolvers, comma separated.
                      dns_proxy_list:
                        type:
                          - string
                          - "null"
                        description: Resolvers the proxies use, comma separated.
                      using_modem_dns:
                        type: boolean
                      vpn_force_reload_dns_server:
                        type: boolean
              example:
                status: true
                data:
                  dns_system_list: 1.1.1.1,8.8.8.8
                  dns_proxy_list: 1.1.1.1,8.8.8.8
                  using_modem_dns: false
                  vpn_force_reload_dns_server: false
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
    post:
      operationId: updateDnsConfig
      tags:
        - Network
      summary: Change the DNS servers of the box and the proxies
      description: Saves the proxy DNS list and modem-DNS options, writes the system resolver configuration and reloads every proxy. All four fields are required.
      x-xproxy-safety: destructive
      x-agent-note: "Ask the user first: a wrong resolver breaks name resolution for the box and every proxy, and all proxies reload. Verify with GET /update_dns_config and a test request through a proxy."
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - using_modem_dns
                - dns_proxy_list
                - vpn_force_reload_dns_server
                - dns_system_list
              properties:
                using_modem_dns:
                  type: boolean
                dns_proxy_list:
                  type: string
                  description: Resolver IPs separated by commas, spaces or new lines.
                vpn_force_reload_dns_server:
                  type: boolean
                dns_system_list:
                  type: string
                  description: Resolver IPs separated by commas, spaces or new lines.
            example:
              using_modem_dns: false
              dns_proxy_list: 1.1.1.1,8.8.8.8
              vpn_force_reload_dns_server: false
              dns_system_list: 1.1.1.1,8.8.8.8
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                    msg: Configuration successfully!
                failed:
                  summary: Missing field or error
                  value:
                    status: false
                    msg: An error when configuration!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: An error when configuration!
          meaning: A field is missing or writing the resolver settings failed.
          remedy: Send all four fields and retry.
      x-since: v20.8.0
  /xproxy_config_public_ipchecker:
    get:
      operationId: getPublicIpCheckerConfig
      tags:
        - Network
      summary: Read how the box detects each modem's public IP
      description: Returns the IP-check servers (IPv4 and IPv6), the check method, the check period and timeout in seconds, and the HTTP-status-only and native async check switches.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: IP checker settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      ip_server:
                        type:
                          - string
                          - "null"
                      ipv6_server:
                        type:
                          - string
                          - "null"
                      method:
                        type:
                          - string
                          - "null"
                      only_http_status_check:
                        type: boolean
                      pubip_period:
                        type: integer
                      pubip_timedout:
                        type: integer
                      native_async_http_check_enabled:
                        type: boolean
              example:
                status: true
                data:
                  ip_server: https://ip.example.com
                  ipv6_server: https://ip6.example.com
                  method: curl
                  only_http_status_check: false
                  pubip_period: 30
                  pubip_timedout: 5
                  native_async_http_check_enabled: true
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
    post:
      operationId: setPublicIpCheckerConfig
      tags:
        - Network
      summary: Change how the box detects each modem's public IP
      description: Saves the IP-check servers, method, period and timeout. `pubip_period` and `pubip_timedout` must be integers from 2 to 99999. A wrong IP server makes every modem look disconnected.
      x-xproxy-safety: destructive
      x-agent-note: Ask the user first; a bad server or method marks all modems as having no public IP. Verify with GET /xproxy_config_public_ipchecker and /status of one proxy.
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - method
                - ip_server
                - ipv6_server
                - pubip_period
                - pubip_timedout
                - only_http_status_check
              properties:
                method:
                  type: string
                ip_server:
                  type: string
                ipv6_server:
                  type: string
                pubip_period:
                  type: integer
                  minimum: 2
                  maximum: 99999
                pubip_timedout:
                  type: integer
                  minimum: 2
                  maximum: 99999
                only_http_status_check:
                  type: boolean
                native_async_http_check_enabled:
                  type: boolean
            example:
              method: curl
              ip_server: https://ip.example.com
              ipv6_server: https://ip6.example.com
              pubip_period: 30
              pubip_timedout: 5
              only_http_status_check: false
              native_async_http_check_enabled: true
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                    msg: Configuration successfully!
                period:
                  summary: Bad period
                  value:
                    status: false
                    msg: The period option must greater than 1
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: The period option must greater than 1
          meaning: pubip_period is below 2 or above 99999.
          remedy: Send 2–99999.
        - msg: The timed out option must greater than 1
          meaning: pubip_timedout is below 2 or above 99999.
          remedy: Send 2–99999.
        - msg: Please input valid value
          meaning: A field is missing or not a number.
          remedy: Send every required field with valid values.
      x-since: v20.8.0
  /v2/ddns/providers:
    get:
      operationId: getDdnsProviders
      tags:
        - Network
      summary: List the DDNS providers and whether their updates are healthy
      description: "Returns every saved DDNS provider with its settings, last result and a computed `health`. This response returns secrets: each provider's `config` holds its API token or password."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Providers, or a load failure.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NetworkDdnsProvider"
              examples:
                ok:
                  summary: One provider
                  value:
                    status: true
                    data:
                      - id: duckdns
                        type: duckdns
                        enabled: true
                        interval_seconds: 300
                        ip_source: auto
                        config:
                          domain: mybox
                          token: YOUR_DUCKDNS_TOKEN
                        last_ip: 203.0.113.10
                        last_status: updated
                        last_run_at: 1763366400
                        next_run_at: 1763366700
                        error_count: 0
                        health: ok
                error:
                  summary: Load failed
                  value:
                    status: false
                    msg: failed_to_load
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: failed_to_load
          meaning: The saved provider settings could not be read.
          remedy: Retry; save the provider again if it persists.
      x-since: v20.8.0
    post:
      operationId: saveDdnsProvider
      tags:
        - Network
      summary: Create or change one DDNS provider
      description: Updates the provider named by `type`; only the fields present (enabled, interval_seconds, ip_source, manual_ip, config) change. Starts or stops the DDNS service to match whether any provider is enabled, and, when the provider is enabled, sends an update right away (a failed update is only logged).
      x-xproxy-safety: destructive
      x-agent-note: Ask the user before saving; it changes a public DNS record. `config` replaces the whole credential object, so send every credential field. Verify with GET /v2/ddns/providers (health, last_status).
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - cloudflare
                    - noip
                    - duckdns
                    - dnsomatic
                    - dynu
                enabled:
                  type: boolean
                interval_seconds:
                  type: integer
                ip_source:
                  type: string
                manual_ip:
                  type: string
                config:
                  type: object
                  additionalProperties: true
            example:
              type: cloudflare
              enabled: true
              interval_seconds: 300
              config:
                api_token: YOUR_CLOUDFLARE_API_TOKEN
                zone_id: YOUR_ZONE_ID
                record_name: box.example.com
                proxied: false
                ttl: 120
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                badType:
                  summary: Unknown provider
                  value:
                    status: false
                    msg: invalid_provider_type
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: invalid_payload
          meaning: The body is not a JSON object.
          remedy: Send a JSON object.
        - msg: invalid_provider_type
          meaning: type is missing or not cloudflare, noip, duckdns, dnsomatic or dynu.
          remedy: Send a supported type.
        - msg: failed_to_save
          meaning: Saving failed.
          remedy: Retry; check the controller log.
      x-since: v20.8.0
  /v2/ddns/trigger_all:
    post:
      operationId: triggerAllDdnsUpdates
      tags:
        - Network
      summary: Push the current IP to every enabled DDNS provider now
      description: Forces one update of every enabled provider. On boxes with the xddns helper the answer includes per-provider `results`; older boxes run the update without returning results.
      x-xproxy-safety: action
      x-agent-note: Safe to run once; avoid loops (providers rate-limit updates). Verify with GET /v2/ddns/providers.
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                        id:
                          type: string
                        action:
                          type: string
                        ok:
                          type: boolean
                        msg:
                          type: string
                      additionalProperties: true
              examples:
                ok:
                  summary: Updated
                  value:
                    status: true
                    results:
                      - type: duckdns
                        id: duckdns
                        action: updated
                        ok: true
                        msg: OK
                failed:
                  summary: Failed
                  value:
                    status: false
                    msg: trigger_failed
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: trigger_failed
          meaning: The DDNS helper could not run or read the providers.
          remedy: Check the providers with GET /v2/ddns/providers and retry.
      x-since: v20.8.0
  /get_wan_config:
    get:
      operationId: getWanConfig
      tags:
        - Network
      summary: Read the WAN (PPPoE) setup and its connection log
      description: "Returns whether the box's own WAN service is on, the interface and method, the saved PPPoE settings (`config`), the box's interfaces and, for PPPoE, the tail of the connection log. This response can return secrets: `config.password` is the PPPoE password."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: WAN settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      enable:
                        type: boolean
                      interface:
                        type:
                          - string
                          - "null"
                      method:
                        type:
                          - string
                          - "null"
                        description: e.g. pppoe.
                      config:
                        type: object
                        description: PPPoE settings (username, password, vlan, mtu, mac); empty for other methods.
                        additionalProperties: true
                      interface_list:
                        type: array
                        items:
                          type: object
                          properties:
                            value:
                              type: string
                            label:
                              type: string
                      wan_log:
                        type: string
              example:
                status: true
                data:
                  enable: true
                  interface: eth1
                  method: pppoe
                  config:
                    username: user1
                    password: YOUR_PPPOE_PASSWORD
                    vlan: FF
                    mtu: "1492"
                    mac: 02:00:00:00:00:01
                  interface_list:
                    - value: eth0
                      label: eth0
                    - value: eth1
                      label: eth1
                  wan_log: PPP session established
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.8.0
  /get_dhcp_fix_log:
    get:
      operationId: getDhcpFixLog
      tags:
        - Network
      summary: Read the tail of the dongle DHCP-fix recovery log
      description: Returns the last lines of the DHCP fix log written by the box's dongle recovery. `lines` outside 1–2000 falls back to 200.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      parameters:
        - name: lines
          in: query
          description: Number of lines (1–2000).
          schema:
            type: integer
            default: 200
          example: 200
      responses:
        "200":
          description: Log text.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: string
              examples:
                ok:
                  summary: Log
                  value:
                    status: true
                    data: |-
                      2026-11-17 08:00:01 eth3 no lease, renewing
                      2026-11-17 08:00:04 eth3 lease ok
                failed:
                  summary: Read failed
                  value:
                    status: false
                    msg: Failed to read DHCP fix log
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Failed to read DHCP fix log
          meaning: Reading the log failed.
          remedy: Retry; check the controller log.
      x-since: v21.1.32
  /v2/ipv6_multiple_list:
    get:
      operationId: getIpv6MultipleList
      tags:
        - Network
      summary: Page through the IPv6 Multiple proxies (server IPv6 sub-proxies)
      description: "Lists the proxies created by IPv6 Multiple, sorted by slot, with paging. Missing or invalid `page`/`limit` fall back to page 1 and 10 rows. This response returns secrets: each entry contains the proxy's `auth_pass`."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      parameters:
        - name: page
          in: query
          description: Page number from 1.
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Rows per page.
          schema:
            type: integer
            default: 10
      responses:
        "200":
          description: One page (no `status` field in this answer).
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                      properties:
                        slot:
                          type: integer
                        slot_id:
                          type: integer
                        system:
                          type: string
                        isp:
                          type: string
                        source_interface:
                          type: string
                        mode:
                          type: string
                          enum:
                            - single
                            - group
                        port_type:
                          type: string
                          enum:
                            - both
                            - http
                            - socks5
                        group_id:
                          type:
                            - string
                            - "null"
                        ipv6:
                          type: string
                        proxy_port:
                          type: integer
                        socks_port:
                          type:
                            - integer
                            - "null"
                        tcp_os_profile:
                          type:
                            - string
                            - "null"
                        auth_user:
                          type:
                            - string
                            - "null"
                        auth_pass:
                          type:
                            - string
                            - "null"
                        ip_whitelist:
                          type:
                            - string
                            - "null"
                        dns_servers:
                          type:
                            - string
                            - "null"
                        conn_rate_limit:
                          type:
                            - integer
                            - "null"
                        conn_rate_period:
                          type:
                            - integer
                            - "null"
                        last_reset:
                          type:
                            - number
                            - "null"
                        status:
                          type: string
                          description: e.g. starting, online, Interface Down, Regenerating IP..., Proxy Down, unknown.
                        has_auth:
                          type: boolean
                        has_ipv6:
                          type: boolean
              example:
                total: 1
                data:
                  - slot: 1
                    slot_id: 1
                    system: 192.0.2.10
                    isp: Server IPv6
                    source_interface: eth0
                    mode: single
                    port_type: both
                    group_id: null
                    ipv6: 2001:db8::10
                    proxy_port: 9000
                    socks_port: 10000
                    tcp_os_profile: null
                    auth_user: user1
                    auth_pass: YOUR_PROXY_PASSWORD
                    ip_whitelist: ""
                    dns_servers: ""
                    conn_rate_limit: null
                    conn_rate_period: null
                    last_reset: null
                    status: online
                    has_auth: true
                    has_ipv6: true
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /linux_resource:
    get:
      operationId: getLinuxResource
      tags:
        - Overview
      summary: Read CPU, memory, uptime, version and plan of the box
      description: Use this for a quick health and licence overview. `memory` and `cpu` are percentages, `time` is hours since the operating system booted. At most every 15 minutes the call also asks the update server whether a newer version exists and refreshes `update_info`. Plan fields are present only once the licence module is loaded. Returns the buyer email (personal data).
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      responses:
        "200":
          description: Resource and plan summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: object
                    additionalProperties: true
                    properties:
                      memory:
                        type: number
                        description: Memory use in percent.
                      cpu:
                        type: number
                        description: CPU use in percent.
                      time:
                        type: integer
                        description: Hours since boot.
                      version:
                        type: string
                      is_updating:
                        type: boolean
                      update_info:
                        type:
                          - object
                          - "null"
                        properties:
                          latest_version:
                            type: string
                          heading:
                            type: string
                          note:
                            type: string
                          need_update:
                            type: boolean
                          is_prod:
                            type:
                              - boolean
                              - string
                      ended_support:
                        type: boolean
                      plan_name:
                        type: string
                      max_modem:
                        type: integer
                      activated:
                        type: boolean
                      plan_starting_date:
                        type:
                          - string
                          - "null"
                      plan_ending_date:
                        type:
                          - string
                          - "null"
                      plan_remaining_day:
                        type:
                          - integer
                          - "null"
                      is_connected_service:
                        type: boolean
                      server_name:
                        type: string
                      buyer_email:
                        type: string
              example:
                status: true
                data:
                  memory: 41.2
                  cpu: 12.5
                  time: 73
                  version: v21.3.4
                  is_updating: false
                  update_info:
                    latest_version: v21.3.5
                    heading: Bug fixes
                    note: Stability fixes.
                    need_update: true
                    is_prod: true
                  ended_support: false
                  plan_name: Pro
                  max_modem: 20
                  activated: true
                  plan_starting_date: 2026-01-01
                  plan_ending_date: 2027-01-01
                  plan_remaining_day: 45
                  is_connected_service: true
                  server_name: my-box
                  buyer_email: owner@example.com
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          description: Reading the resources failed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: false
                  error:
                    type: string
              example:
                status: false
                error: psutil error
      x-since: v20.8.0
  /system_information:
    get:
      operationId: getSystemInformation
      tags:
        - Overview
      summary: Read licence, plan, enabled features and software version of the box
      description: "Use this to check which licence features are on (IPv6, VLESS, selling, SMS/USSD, VPS forwarding and so on) before calling a feature route, and to read the installed version and build. Returns secrets and personal data: the licence key, the subscription secret key and the buyer email. Only trusted tools should call it; never log or display the response. If reading the licence fails, the box answers `status: false` with an empty `data`."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      responses:
        "200":
          description: System information, or `status false` with empty data on failure.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  data:
                    type: object
                    additionalProperties: true
                    properties:
                      license_key:
                        type: string
                        description: Licence key of the box (secret).
                      country_code:
                        type:
                          - string
                          - "null"
                      max_modem:
                        type: integer
                      ipv6:
                        type: boolean
                      phone:
                        type: boolean
                      rotation_ip:
                        type: boolean
                      vpn_support:
                        type: boolean
                      tcpos:
                        type: boolean
                      ip_authen:
                        type: boolean
                      blacklist_control:
                        type: boolean
                      selling:
                        type: boolean
                      sms_ussd:
                        type: boolean
                      vpn_proxy:
                        type: boolean
                      vps_forwarding_port:
                        type: boolean
                      proxy_group:
                        type: boolean
                      vless:
                        type: boolean
                      wan_proxy:
                        type: boolean
                      server_name:
                        type: string
                      buyer_email:
                        type: string
                      plan_name:
                        type: string
                      sub_type:
                        type:
                          - string
                          - "null"
                      plan_starting_date:
                        type:
                          - string
                          - "null"
                      plan_ending_date:
                        type:
                          - string
                          - "null"
                      plan_remaining_day:
                        type:
                          - integer
                          - "null"
                      sub_secret_key:
                        type:
                          - string
                          - "null"
                        description: Subscription secret (secret).
                      activated:
                        type: boolean
                      activated_date:
                        type:
                          - string
                          - "null"
                      warranty:
                        type:
                          - string
                          - "null"
                      ended_support:
                        type: boolean
                      ended_support_date:
                        type:
                          - string
                          - "null"
                      your_version:
                        type: string
                      build_version:
                        type: string
                      git_commit:
                        type: string
                      install_branch:
                        type: string
                      update_info:
                        type:
                          - object
                          - "null"
                      is_connected_service:
                        type: boolean
                      history_versions:
                        type: array
                        items:
                          type: object
                          additionalProperties: true
              examples:
                ok:
                  summary: Licensed box (hand-written)
                  value:
                    status: true
                    data:
                      license_key: YOUR_LICENSE_KEY
                      country_code: US
                      max_modem: 20
                      ipv6: true
                      phone: true
                      rotation_ip: true
                      vpn_support: true
                      tcpos: true
                      ip_authen: true
                      blacklist_control: true
                      selling: false
                      sms_ussd: true
                      vpn_proxy: false
                      vps_forwarding_port: true
                      proxy_group: true
                      vless: true
                      wan_proxy: false
                      server_name: my-box
                      buyer_email: owner@example.com
                      plan_name: Pro
                      sub_type: yearly
                      plan_starting_date: 2026-01-01
                      plan_ending_date: 2027-01-01
                      plan_remaining_day: 45
                      sub_secret_key: YOUR_SUB_SECRET_KEY
                      activated: true
                      activated_date: 2026-01-01
                      warranty: 2027-01-01
                      ended_support: false
                      ended_support_date: null
                      your_version: v21.3.4
                      build_version: 26.1101.1200
                      git_commit: 0123abcd
                      install_branch: prod
                      update_info: null
                      is_connected_service: true
                      history_versions: []
                failed:
                  summary: Licence data unavailable
                  value:
                    status: false
                    data: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /v2/proxy_list:
    get:
      operationId: getPanelProxyList
      tags:
        - Overview
      summary: List every slot with ports, IP state, schedules and Smart IP Guard data
      description: "Use this for the full panel view of all slots, including offline and stopped ones (unlike /api/v1/info_list, which lists only connected slots). Paging is 1-based; `limit` 0 returns every row. `search` filters rows by text match before paging; `total` counts the filtered rows. Returns secrets: each row carries the slot's VLESS id and Shadowsocks password."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs the panel login; the API policy additionally requires credentials or a trusted caller (loopback, LAN, whitelist, allowed Tailscale).
      security:
        - basicAuth: []
      parameters:
        - name: page
          in: query
          description: Page number starting at 1. A non-integer value fails with HTTP 500.
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Rows per page; 0 returns all rows.
          schema:
            type: integer
            default: 10
        - name: search
          in: query
          description: Free-text filter on the slot fields (port, IP, label, modem type).
          schema:
            type: string
      responses:
        "200":
          description: Slots on the requested page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/OverviewProxyRow"
                  total:
                    type: integer
                  ip_history_guard_enabled:
                    type: boolean
                  auto_resume_seconds:
                    type: integer
              example:
                data:
                  - position: 1
                    proxy_port: 4001
                    socks5_port: 5001
                    vless_port: 10001
                    ss_port: 12001
                    vless_uuid: YOUR_VLESS_UUID
                    ss_password: YOUR_SS_PASSWORD
                    public_ip: 203.0.113.45
                    public_ip_v6: 2001:db8::45
                    manu: HW-Hilink
                    ip_status: connected
                    rebooting: false
                    extra_info:
                      provider: Example Mobile
                      apn: internet
                    rotation_jobs: 1
                    rotation_next_run: 1763373600
                    ip_score: 98
                    repeats: 2
                    freshness: fresh
                    stopped: false
                    stopped_by: null
                    stopped_at: null
                total: 1
                ip_history_guard_enabled: true
                auto_resume_seconds: 0
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.8.0
  /v2/status_list:
    get:
      operationId: getPanelStatusList
      tags:
        - Overview
      summary: Read a one-word connection state for every slot
      description: "Use this for a light-weight status poll. `position` is the row index (1-based) in the modem table. States: data-updown (public IPv4 and IMEI known), module-noresponse (public IP but no IMEI), sim-unplug, sim-nodata (rotating or resetting), slot_empty, data-down."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs the panel login; the API policy additionally requires credentials or a trusted caller.
      security:
        - basicAuth: []
      responses:
        "200":
          description: One state per slot.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        position:
                          type: integer
                        status:
                          type: string
                          enum:
                            - data-updown
                            - module-noresponse
                            - sim-unplug
                            - sim-nodata
                            - slot_empty
                            - data-down
                  total:
                    type: integer
              example:
                data:
                  - position: 1
                    status: data-updown
                  - position: 2
                    status: slot_empty
                total: 2
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /v2/dongle_device_list:
    get:
      operationId: getDongleDeviceList
      tags:
        - Overview
      summary: List the USB modems (not Android phones) with their device details
      description: Use this for the modem hardware table. Lists slots with a detected USB modem, plus Sierra modems that are flashing firmware (shown as `Sierra (flashing firmware)` with `extra_info.upgrade_firmware_status`). Android phones and empty slots are left out. Paging is 1-based; `limit` 0 returns all rows. Rows include the IMEI, ICCID and phone number of each SIM (personal data).
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs the panel login; the API policy additionally requires credentials or a trusted caller.
      security:
        - basicAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Rows per page; 0 returns all rows.
          schema:
            type: integer
            default: 10
      responses:
        "200":
          description: Modems on the requested page.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  total:
                    type: integer
              example:
                data:
                  - position: 1
                    manu: HW-Hilink
                    device_name: E3372
                    imei: "490154203237518"
                    iccid: "89014103211118510720"
                    phone_number: "+15550100"
                    public_ip: 203.0.113.45
                    resetting: false
                    extra_info:
                      provider: Example Mobile
                total: 1
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /get_proxies_settings:
    get:
      operationId: getProxiesSettings
      tags:
        - Proxy settings
      summary: Read every global proxy setting shown on the panel's Proxy settings page
      description: 'Returns the global proxy configuration in one object: proxy login, IP whitelist, IPv6 options, per-port authentication, port layout, VLESS and Shadowsocks options, VPS relay summary, group health-check options, website white/blacklists, sticky IP, auto-reboot rules, WebRTC leak protection and the "proxy through WAN" listener. This response returns secrets (proxy password, VLESS public key, WAN VLESS UUID, WAN Shadowsocks password); do not log or share it. On an internal error the box answers `status: false` with the error text in `msg`.'
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Current settings, or `status false` with the error text.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                    description: Error text when status is false.
                  data:
                    type: object
                    description: Settings. Field names match the `data` keys accepted by `/update_proxies_settings`.
                    additionalProperties: true
                    properties:
                      enableProxyAuth:
                        type: boolean
                      disableProxyCache:
                        type: boolean
                      proxyUser:
                        type: string
                      proxyPass:
                        type: string
                        description: Global proxy password (secret).
                      enableLogging:
                        type: boolean
                      loggingMaxDay:
                        type: integer
                      ipRotationLogRetentionDays:
                        type: integer
                      uptimeLogRetentionDays:
                        type: integer
                      rotationConfig:
                        type: string
                        description: Scheduled rotation table, one rule per line.
                      enableIPAuth:
                        type: boolean
                      forceLocalAuthen:
                        type: boolean
                      allowTailscaleNoAuth:
                        type: boolean
                      ipList:
                        type: string
                        description: Whitelisted client IPs or subnets, one per line.
                      ipv6Config:
                        type: boolean
                      multipleIpv6Config:
                        type: boolean
                      enablePerPortAuth:
                        type: boolean
                      perPortAuthConfig:
                        type: string
                      proxyStartPort:
                        type: integer
                      proxyStartPortMax:
                        type: integer
                        description: Highest start port that still leaves room for every port band.
                      autoPort:
                        type: boolean
                      vlessEnabled:
                        type: boolean
                      vlessLicenseAllowed:
                        type: boolean
                      vlessPublicKey:
                        type: string
                        description: REALITY public key (secret-like; share only with your clients).
                      vlessSni:
                        type: string
                      vlessShortId:
                        type: string
                      vlessFlow:
                        type: string
                        const: xtls-rprx-vision
                      vlessServerIp:
                        type: string
                      ssEnabled:
                        type: boolean
                      ssMethod:
                        type: string
                        enum:
                          - aes-128-gcm
                          - aes-256-gcm
                          - chacha20-ietf-poly1305
                      ssLicenseAllowed:
                        type: boolean
                      ssStartPortOk:
                        type: boolean
                      vpsRelayEnabled:
                        type: boolean
                      vpsAddress:
                        type: string
                      vpsPortAdjust:
                        type: integer
                      ipv6Mode:
                        type: string
                        enum:
                          - "0"
                          - "46"
                          - "64"
                      proxyWatchdogInterval:
                        type: integer
                      group_hostname:
                        type: string
                      group_pingCount:
                        type: integer
                      group_pingSize:
                        type: integer
                      group_checkInterval:
                        type: integer
                      group_checkTimeout:
                        type: integer
                      enableWhiteList:
                        type: boolean
                      whitelistSetting:
                        type: string
                      enableBlackList:
                        type: boolean
                      blacklistSetting:
                        type: string
                      rotationDelayBeforeProcess:
                        type: number
                      globalWebsiteAuthorizationMode:
                        type:
                          - string
                          - "null"
                        enum:
                          - none
                          - whitelist
                          - blacklist
                          - null
                      globalWhitelistSetting:
                        type:
                          - string
                          - "null"
                      globalBlacklistSetting:
                        type:
                          - string
                          - "null"
                      stickyIPEnable:
                        type: boolean
                      stickyServer:
                        type:
                          - string
                          - "null"
                      s_interval:
                        type: number
                      s_timeout:
                        type: number
                      s_size:
                        type: integer
                      s_ttl:
                        type: integer
                      stickyIPMethod:
                        type: string
                      forceServerResolveDNS:
                        type: boolean
                      autoRebootIPUnchanged:
                        type: integer
                      autoRebootIPCheckFail:
                        type: integer
                      enable_webrtc_leak:
                        type: boolean
                      out_interfaces:
                        type: string
                      exportConfig:
                        type: string
                        description: JSON text of the proxy-list export options.
                      wanProxyEnabled:
                        type: boolean
                      wanProxyPort:
                        type: integer
                      wanProxyVlessEnabled:
                        type: boolean
                      wanProxyLicenseAllowed:
                        type: boolean
                      wanProxyVlessPort:
                        type: integer
                      wanProxyVlessUuid:
                        type: string
                        description: UUID of the WAN VLESS listener (secret).
                      wanProxySsEnabled:
                        type: boolean
                      wanProxySsPort:
                        type: integer
                      wanProxySsPassword:
                        type: string
                        description: Shared Shadowsocks password (secret).
                      wanProxyHost:
                        type: string
                      wanProxyPublicIp:
                        type: string
              examples:
                ok:
                  summary: Settings
                  value:
                    status: true
                    data:
                      enableProxyAuth: true
                      disableProxyCache: true
                      proxyUser: user1
                      proxyPass: YOUR_PROXY_PASSWORD
                      enableLogging: false
                      loggingMaxDay: 7
                      ipRotationLogRetentionDays: 30
                      uptimeLogRetentionDays: 30
                      rotationConfig: ""
                      enableIPAuth: true
                      forceLocalAuthen: false
                      allowTailscaleNoAuth: false
                      ipList: 198.51.100.7
                      ipv6Config: false
                      multipleIpv6Config: false
                      enablePerPortAuth: false
                      perPortAuthConfig: ""
                      proxyStartPort: 4001
                      proxyStartPortMax: 47407
                      autoPort: true
                      vlessEnabled: true
                      vlessLicenseAllowed: true
                      vlessPublicKey: YOUR_REALITY_PUBLIC_KEY
                      vlessSni: www.example.com
                      vlessShortId: YOUR_SHORT_ID
                      vlessFlow: xtls-rprx-vision
                      vlessServerIp: 203.0.113.10
                      ssEnabled: false
                      ssMethod: aes-256-gcm
                      ssLicenseAllowed: true
                      ssStartPortOk: true
                      vpsRelayEnabled: false
                      vpsAddress: ""
                      vpsPortAdjust: 0
                      ipv6Mode: "0"
                      proxyWatchdogInterval: 30
                      group_hostname: 1.1.1.1
                      group_pingCount: 3
                      group_pingSize: 32
                      group_checkInterval: 30
                      group_checkTimeout: 5
                      enableWhiteList: false
                      whitelistSetting: ""
                      enableBlackList: false
                      blacklistSetting: ""
                      rotationDelayBeforeProcess: 0
                      globalWebsiteAuthorizationMode: none
                      globalWhitelistSetting: null
                      globalBlacklistSetting: null
                      stickyIPEnable: false
                      stickyServer: 1.1.1.1
                      s_interval: 1
                      s_timeout: 1
                      s_size: 32
                      s_ttl: 64
                      stickyIPMethod: ping
                      forceServerResolveDNS: false
                      autoRebootIPUnchanged: 0
                      autoRebootIPCheckFail: 0
                      enable_webrtc_leak: false
                      out_interfaces: eth0
                      exportConfig: "{}"
                      wanProxyEnabled: false
                      wanProxyPort: 3000
                      wanProxyVlessEnabled: false
                      wanProxyLicenseAllowed: true
                      wanProxyVlessPort: 9000
                      wanProxyVlessUuid: YOUR_WAN_VLESS_UUID
                      wanProxySsEnabled: false
                      wanProxySsPort: 11000
                      wanProxySsPassword: YOUR_SS_PASSWORD
                      wanProxyHost: 192.0.2.10
                      wanProxyPublicIp: ""
                error:
                  summary: Internal error
                  value:
                    status: false
                    msg: proxy engine not ready
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: (exception text)
          meaning: Reading a setting failed (for example while the proxy engine is still starting).
          remedy: Retry after a few seconds; check the controller log if it persists.
      x-since: v20.8.0
  /update_proxies_settings:
    post:
      operationId: updateProxiesSettings
      tags:
        - Proxy settings
      summary: Change one section of the global proxy settings
      description: "Saves one section of the Proxy settings page, chosen by `type`; `data` carries that section's fields with the same names `/get_proxies_settings` returns. Sections: `ipv6Config` (ipv6Config, multipleIpv6Config; needs the IPv6 license feature to turn on), `proxyStartPort` (proxyStartPort, autoPort, ipv6Mode, proxyWatchdogInterval, optional vlessEnabled, vlessSni, ssEnabled, ssMethod), `proxyGroupConfig` (group_* health-check fields), `rotationConfig` (needs the rotation feature), `enableProxyAuth` (enableProxyAuth, disableProxyCache, proxyUser, proxyPass), `enableIPAuth` (enableIPAuth, forceLocalAuthen, ipList, optional allowTailscaleNoAuth), `enablePerPortAuth` (needs the selling feature to turn on), `enableWhiteList` / `enableBlackList` / `bandwidthEnable` (need the website-access feature to turn on; bandwidth rules go in `data.data`), `globalWebsiteAuthorizationMode`, `stickyIPEnable`, `enableLogging`, `forceServerResolveDNS`, `webrtc`, `auto_reboot`, `exportConfig`, `wanProxy`. Side effects: `msg: success_app_restart` means the controller restarts (all proxies drop for some seconds) — this happens for an IPv6 change, a port-layout change (start port, auto port, IPv6 mode, VLESS or Shadowsocks on/off), group health-check settings and WebRTC changes. Most other sections reload every proxy config. An unknown `type` changes nothing but still reloads all proxies and answers success. Turning on Shadowsocks or VLESS without the license answers HTTP 403."
      x-xproxy-safety: destructive
      x-agent-note: 'Ask the user before calling: several sections restart the controller and drop every proxy, and the auth sections can lock clients out. Send all fields of the section (missing required fields answer "Configuration failed!"). Verify with /get_proxies_settings afterwards; after success_app_restart wait until the panel answers again.'
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - data
              properties:
                type:
                  type: string
                  enum:
                    - ipv6Config
                    - proxyStartPort
                    - proxyGroupConfig
                    - rotationConfig
                    - enableProxyAuth
                    - enableIPAuth
                    - enablePerPortAuth
                    - enableWhiteList
                    - enableBlackList
                    - globalWebsiteAuthorizationMode
                    - bandwidthEnable
                    - stickyIPEnable
                    - enableLogging
                    - forceServerResolveDNS
                    - webrtc
                    - auto_reboot
                    - exportConfig
                    - wanProxy
                  description: Section to save.
                data:
                  type: object
                  description: Fields of that section (see the description). For `webrtc` send enable_webrtc_leak and wan_interfaces (array); eth0 and tailscale0 are always kept.
                  additionalProperties: true
            examples:
              proxyAuth:
                summary: Set the global proxy login
                value:
                  type: enableProxyAuth
                  data:
                    enableProxyAuth: true
                    disableProxyCache: true
                    proxyUser: user1
                    proxyPass: YOUR_PROXY_PASSWORD
              ports:
                summary: Port layout and protocols
                value:
                  type: proxyStartPort
                  data:
                    proxyStartPort: 4001
                    autoPort: true
                    ipv6Mode: "0"
                    proxyWatchdogInterval: 30
                    vlessEnabled: true
                    vlessSni: www.example.com
                    ssEnabled: false
                    ssMethod: aes-256-gcm
              ipAuth:
                summary: Whitelist client IPs
                value:
                  type: enableIPAuth
                  data:
                    enableIPAuth: true
                    forceLocalAuthen: false
                    ipList: |-
                      198.51.100.7
                      198.51.100.0/24
      responses:
        "200":
          description: Result. `applied` is `live` (saved, nothing restarted) or `reloaded` (VLESS/Shadowsocks listeners re-rendered) for the proxyStartPort and ipv6Config sections.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/StatusMsg"
                  - type: object
                    properties:
                      applied:
                        type: string
                        enum:
                          - live
                          - reloaded
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                    msg: Configuration successfully!
                live:
                  summary: Port section saved without restart
                  value:
                    status: true
                    msg: Configuration successfully!
                    applied: live
                restart:
                  summary: Controller restarts
                  value:
                    status: true
                    msg: success_app_restart
                needUpgrade:
                  summary: License feature missing
                  value:
                    status: false
                    msg: need_upgrade
                failed:
                  summary: Missing field or error
                  value:
                    status: false
                    msg: Configuration failed!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: Turning on Shadowsocks or VLESS (including WAN VLESS/Shadowsocks) without a Premium or Business license.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              example:
                status: false
                msg: Shadowsocks requires a Premium or Business license
      x-errors:
        - msg: success_app_restart
          meaning: Saved; the controller restarts to apply it (status true).
          remedy: Wait until the panel answers again, then verify.
        - msg: need_upgrade
          meaning: The license lacks the feature needed to turn this section on (IPv6, rotation, website access, WAN proxy).
          remedy: Upgrade the license or leave the feature off.
        - msg: need_upgrade_selling
          meaning: Per-port authentication needs the selling feature.
          remedy: Upgrade the license.
        - msg: "Start port too high for Shadowsocks: ..."
          meaning: The start port leaves no room for the Shadowsocks IPv6 band.
          remedy: Use a start port at or below proxyStartPortMax.
        - msg: Start port range collides with WAN proxy port N — disable "Proxy through WAN" or move it first!
          meaning: The new port range overlaps the WAN proxy listener.
          remedy: Move or disable the WAN proxy first.
        - msg: Shadowsocks requires a Premium or Business license
          meaning: HTTP 403; Shadowsocks cannot be turned on with this license.
          remedy: Upgrade the license.
        - msg: VLESS requires a Premium or Business license
          meaning: HTTP 403; VLESS cannot be turned on with this license.
          remedy: Upgrade the license.
        - msg: Shadowsocks ports are already in use (...), free them or change the Starting Port first!
          meaning: Other services already use ports of the Shadowsocks band.
          remedy: Free the listed ports or pick another start port.
        - msg: Unsupported Shadowsocks cipher
          meaning: ssMethod is not aes-128-gcm, aes-256-gcm or chacha20-ietf-poly1305.
          remedy: Send one of those ciphers.
        - msg: The IPv6 mode is invalid!
          meaning: ipv6Mode is not '0', '46' or '64'.
          remedy: Send one of those values as a string.
        - msg: The Proxy Watchdog Interval is invalid, range [5-300s]!
          meaning: proxyWatchdogInterval is outside 5–300.
          remedy: Send a value from 5 to 300.
        - msg: WAN proxy port must be in range [1024-N]
          meaning: wanProxyPort is too low or leaves no room for the VLESS/Shadowsocks offsets.
          remedy: Pick a port in the given range.
        - msg: Proxy engine is not ready yet!
          meaning: The proxy engine is still starting.
          remedy: Retry in a few seconds.
        - msg: Port N collides with ... — pick another port!
          meaning: A WAN proxy port is already used.
          remedy: Pick another wanProxyPort.
        - msg: Configuration failed!
          meaning: A required field of the section is missing or saving failed.
          remedy: Send every field of the section and retry.
      x-since: v20.8.0
  /proxy_group_config:
    get:
      operationId: getProxyGroupConfig
      tags:
        - Proxy settings
      summary: List the proxy groups (one port that spreads traffic over several slots)
      description: Returns every configured proxy group. Each group includes its proxy username and password, so the response can contain secrets.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Groups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProxySettingsGroup"
              example:
                status: true
                data:
                  - primary_port: 9001
                    position_list:
                      - 1
                      - 2
                      - 3
                    proxy_type: "0"
                    user_group: user1
                    pass_group: YOUR_GROUP_PASSWORD
                    ip_group: ""
                    randomize_ip_group: false
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
    post:
      operationId: createProxyGroupConfig
      tags:
        - Proxy settings
      summary: Add a proxy group
      description: Appends the posted group to the group list and reloads all proxies. Needs the proxy-group license feature. The handler does not reject a `primary_port` that already exists, so posting the same group twice creates a duplicate; check /proxy_group_config first and use /edit_proxy_group_config to change a group.
      x-xproxy-safety: destructive
      x-agent-note: Ask the user before creating groups; every call reloads all proxies. Read /proxy_group_config first to avoid duplicates, and verify the new group there afterwards.
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProxySettingsGroup"
            example:
              primary_port: 9001
              position_list:
                - 1
                - 2
                - 3
              proxy_type: "0"
              user_group: user1
              pass_group: YOUR_GROUP_PASSWORD
              ip_group: ""
              randomize_ip_group: false
      responses:
        "200":
          description: The stored group echoed back, or a license refusal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    $ref: "#/components/schemas/ProxySettingsGroup"
              examples:
                ok:
                  summary: Added
                  value:
                    status: true
                    data:
                      primary_port: 9001
                      position_list:
                        - 1
                        - 2
                        - 3
                      proxy_type: "0"
                      user_group: user1
                      pass_group: YOUR_GROUP_PASSWORD
                      ip_group: ""
                      randomize_ip_group: false
                license:
                  summary: No license
                  value:
                    status: false
                    msg: This function is available on higher plan license only. Please contact Administrator!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: This function is available on higher plan license only. Please contact Administrator!
          meaning: The license has no proxy-group feature.
          remedy: Upgrade the license.
      x-since: v20.8.0
  /edit_proxy_group_config:
    post:
      operationId: editProxyGroupConfig
      tags:
        - Proxy settings
      summary: Change an existing proxy group
      description: Finds the group by `primary_port` and merges the posted fields into it, then reloads all proxies. Needs the proxy-group license feature and a non-empty `position_list`.
      x-xproxy-safety: destructive
      x-agent-note: Ask the user before editing; clients of the group reconnect when proxies reload. Verify with GET /proxy_group_config.
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProxySettingsGroup"
            example:
              primary_port: 9001
              position_list:
                - 1
                - 2
              proxy_type: "1"
              user_group: user1
              pass_group: YOUR_GROUP_PASSWORD
              ip_group: 198.51.100.7
              randomize_ip_group: true
      responses:
        "200":
          description: The posted data echoed back, or a refusal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    $ref: "#/components/schemas/ProxySettingsGroup"
              examples:
                ok:
                  summary: Updated
                  value:
                    status: true
                    data:
                      primary_port: 9001
                      position_list:
                        - 1
                        - 2
                      proxy_type: "1"
                      user_group: user1
                      pass_group: YOUR_GROUP_PASSWORD
                      ip_group: 198.51.100.7
                      randomize_ip_group: true
                notFound:
                  summary: Unknown group
                  value:
                    status: false
                    msg: Proxy group not found
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: This function is available on higher plan license only. Please contact Administrator!
          meaning: The license has no proxy-group feature.
          remedy: Upgrade the license.
        - msg: Proxy group must have at least one postion
          meaning: position_list is missing or empty (the typo is in the box message).
          remedy: Send at least one slot.
        - msg: Proxy group not found
          meaning: No group uses this primary_port.
          remedy: Read /proxy_group_config for the existing ports.
      x-since: v20.8.0
  /del_proxy_group_config:
    post:
      operationId: deleteProxyGroupConfig
      tags:
        - Proxy settings
      summary: Delete a proxy group by its port
      description: Removes every group whose `primary_port` matches and saves the list. Proxies are not reloaded by this call, so the group port can keep serving until the next proxy reload or restart. Always answers success, also when no group matched.
      x-xproxy-safety: destructive
      x-agent-note: Ask the user before deleting a group; customers using its port lose access. Verify with GET /proxy_group_config.
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - primary_port
              properties:
                primary_port:
                  type: integer
            example:
              primary_port: 9001
      responses:
        "200":
          description: The posted data echoed back.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: object
                    additionalProperties: true
              example:
                status: true
                data:
                  primary_port: 9001
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.8.0
  /sticky_ip_config:
    post:
      operationId: setStickyIpConfig
      tags:
        - Proxy settings
      summary: Turn sticky IP on or off and set its keep-alive server
      description: Sticky IP keeps each modem's session busy (by pinging `sticky_server`) so the carrier keeps the same public IP. Turning it off stops all sticky jobs; turning it on starts the sticky service with the saved settings. A non-empty `sticky_server` that differs from the saved one is pushed to the running service. Intervals, size and TTL are set through /update_proxies_settings type stickyIPEnable.
      x-xproxy-safety: destructive
      x-agent-note: Ask the user before changing; it affects every modem. Verify with /get_proxies_settings (stickyIPEnable, stickyServer).
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sticky_enable
                - sticky_server
              properties:
                sticky_enable:
                  type: boolean
                sticky_server:
                  type: string
                  description: Host to ping; empty keeps the saved one.
            example:
              sticky_enable: true
              sticky_server: 1.1.1.1
      responses:
        "200":
          description: The posted data echoed back.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: object
                    additionalProperties: true
              example:
                status: true
                data:
                  sticky_enable: true
                  sticky_server: 1.1.1.1
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.8.0
  /xproxy_config_os_spoofing:
    get:
      operationId: getOsSpoofingConfig
      tags:
        - Proxy settings
      summary: Deprecated — OS spoofing settings (always refused)
      description: "Deprecated. The route still exists but always answers `status: false, msg: Deprecated!`. TCP/OS fingerprint profiles are managed per proxy in the panel instead."
      deprecated: true
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Always the deprecation refusal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              example:
                status: false
                msg: Deprecated!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Deprecated!
          meaning: The OS spoofing settings were removed.
          remedy: Do not call this route.
      x-since: v20.8.0
    post:
      operationId: setOsSpoofingConfig
      tags:
        - Proxy settings
      summary: Deprecated — save OS spoofing settings (always refused)
      description: "Deprecated. Changes nothing and always answers `status: false, msg: Deprecated!`."
      deprecated: true
      x-xproxy-safety: destructive
      x-agent-note: Do not use; the route is a no-op kept for old clients.
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            example: {}
      responses:
        "200":
          description: Always the deprecation refusal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              example:
                status: false
                msg: Deprecated!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Deprecated!
          meaning: The OS spoofing settings were removed.
          remedy: Do not call this route.
      x-since: v20.8.0
  /v2/ip_pools:
    get:
      operationId: getIpPools
      tags:
        - Proxy settings
      summary: Page through every public IP the modems have had, with reuse scores
      description: Returns the full public-IP history (no time window), grouped by IP, with how often each IP came back. `score` drops by one per repeat; `freshness` is `fresh` when the score is at or above the IP history guard's threshold, else `warning`. Summary fields cover all IPs matching `search`.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      parameters:
        - name: page
          in: query
          description: Page number from 1.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          description: Rows per page (1–200).
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: search
          in: query
          description: Filter on the IP text.
          schema:
            type: string
          example: 203.0.113
      responses:
        "200":
          description: One page of IPs, or `status false` with the error text.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: object
                    properties:
                      unique_ips:
                        type: integer
                      total_rotations:
                        type: integer
                      freshness_rate:
                        type: integer
                        description: Percent of IPs on this page that are fresh.
                      avg_uses:
                        type: number
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total:
                        type: integer
                      ips:
                        type: array
                        items:
                          type: object
                          properties:
                            ip_address:
                              type: string
                            score:
                              type: integer
                            repeats:
                              type: integer
                            freshness:
                              type: string
                              enum:
                                - fresh
                                - warning
                                - stale
                                - unknown
                            modems_used:
                              type: integer
                            last_seen:
                              type: number
                              description: Unix time (seconds).
                            first_seen:
                              type: number
                              description: Unix time (seconds).
              examples:
                ok:
                  summary: One page
                  value:
                    status: true
                    data:
                      unique_ips: 2
                      total_rotations: 3
                      freshness_rate: 100
                      avg_uses: 1.5
                      page: 1
                      page_size: 50
                      total: 2
                      ips:
                        - ip_address: 203.0.113.45
                          score: 99
                          repeats: 1
                          freshness: fresh
                          modems_used: 2
                          last_seen: 1763366400
                          first_seen: 1763280000
                        - ip_address: 203.0.113.46
                          score: 100
                          repeats: 0
                          freshness: fresh
                          modems_used: 1
                          last_seen: 1763362800
                          first_seen: 1763362800
                error:
                  summary: Database error
                  value:
                    status: false
                    msg: database is locked
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: (exception text)
          meaning: Reading the IP history failed.
          remedy: Retry; check the controller log if it persists.
      x-since: v20.9.85
  /v2/rotation_setting:
    get:
      operationId: getRotationSettings
      tags:
        - Rotation settings
      summary: Read the global rotation, duplicate-IP, Smart IP Guard and IMEI/MAC changer settings
      description: Use this before changing rotation behaviour, and to build the full body that POST /v2/rotation_setting needs. Base IMEIs and MAC addresses are joined with new lines.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      responses:
        "200":
          description: Current settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    $ref: "#/components/schemas/RotationSettings"
              example:
                status: true
                data:
                  rotation_delay_before_process: 0
                  prevent_time_each_port: 5
                  delay_rotation_time: 0
                  delay_rotation_android_time: 0
                  reconnect_isp_failure_time: 300
                  reconnect_isp_failure_max_retry: 3
                  reconnect_ipv6_failure: false
                  detect_collision_ip: true
                  never_change_ip_automatically: false
                  duplicate_ip_rotate_individual_enabled: false
                  duplicate_ip_rotate_individual_wait_seconds: 30
                  duplicate_ip_rotate_individual_max_attempts: 5
                  duplicate_ip_rotate_all_modems_enabled: false
                  duplicate_ip_rotate_all_modems_wait_seconds: 30
                  duplicate_ip_rotate_all_modems_max_attempts: 5
                  ip_history_guard_enabled: true
                  ip_history_guard_time_window_hours: 24
                  ip_history_guard_max_retries: 3
                  ip_history_guard_backoff_delay: 60
                  ip_history_guard_score_threshold: 90
                  ip_history_guard_fresh_score: 95
                  ip_history_guard_auto_stop_enabled: false
                  ip_history_guard_auto_resume_seconds: 0
                  ip_rotation_log_retention_days: 60
                  imei_tc_list:
                    - key: 35847208
                      label: Example Phone A
                  imei_changer_phone_models: []
                  imei_changer_based_imei: "490154203237518"
                  imei_changer_option: 1
                  mac_changer_based_addresses: 02:00:00:00:00:01
                  mac_changer_option: 1
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
    post:
      operationId: setRotationSettings
      tags:
        - Rotation settings
      summary: Save the global rotation settings (full replace of the main fields)
      description: "Use this to change rotation timing, collision handling, duplicate-IP rotation, Smart IP Guard or the IMEI/MAC changer. Read GET /v2/rotation_setting first and send the whole object back with your change: the timing fields, `detect_collision_ip`, `imei_changer` and `mac_changer` are required, and missing duplicate-IP fields are reset to their defaults (off, 30 seconds, 5 attempts). Smart IP Guard fields, `never_change_ip_automatically` and `reconnect_ipv6_failure` are saved only when present. Takes effect immediately for all slots. A missing required field or a non-numeric main value fails with HTTP 500 before anything is saved; a non-numeric Smart IP Guard value fails with HTTP 500 after the main fields were already saved."
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Changes rotation behaviour of every slot. Ask the user before saving; send back the full object from GET and verify with GET /v2/rotation_setting afterwards.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rotation_delay_before_process
                - prevent_time_each_port
                - delay_rotation_time
                - delay_rotation_android_time
                - reconnect_isp_failure_time
                - reconnect_isp_failure_max_retry
                - detect_collision_ip
                - imei_changer
                - mac_changer
              properties:
                rotation_delay_before_process:
                  type: number
                prevent_time_each_port:
                  type: integer
                delay_rotation_time:
                  type: number
                delay_rotation_android_time:
                  type: number
                reconnect_isp_failure_time:
                  type: integer
                reconnect_isp_failure_max_retry:
                  type: integer
                detect_collision_ip:
                  type: boolean
                never_change_ip_automatically:
                  type:
                    - boolean
                    - string
                  description: true/false or 1/0, on/off.
                reconnect_ipv6_failure:
                  type:
                    - boolean
                    - string
                duplicate_ip_rotate_individual_enabled:
                  type: boolean
                  default: false
                duplicate_ip_rotate_individual_wait_seconds:
                  type: integer
                  default: 30
                duplicate_ip_rotate_individual_max_attempts:
                  type: integer
                  default: 5
                duplicate_ip_rotate_all_modems_enabled:
                  type: boolean
                  default: false
                duplicate_ip_rotate_all_modems_wait_seconds:
                  type: integer
                  default: 30
                duplicate_ip_rotate_all_modems_max_attempts:
                  type: integer
                  default: 5
                ip_history_guard_enabled:
                  type: boolean
                ip_history_guard_time_window_hours:
                  type: integer
                ip_history_guard_max_retries:
                  type: integer
                ip_history_guard_backoff_delay:
                  type: integer
                ip_history_guard_score_threshold:
                  type: integer
                ip_history_guard_fresh_score:
                  type: integer
                ip_history_guard_auto_stop_enabled:
                  type: boolean
                ip_history_guard_auto_resume_seconds:
                  type: integer
                imei_changer:
                  type: object
                  required:
                    - phone_models
                    - imei_changer_option
                  properties:
                    phone_models:
                      type: array
                      items: {}
                    based_imei:
                      type: string
                      description: Base IMEIs separated by new lines.
                    imei_changer_option:
                      type: integer
                mac_changer:
                  type: object
                  required:
                    - mac_changer_option
                  properties:
                    mac_changer_option:
                      type: integer
                    based_address:
                      type: string
                      description: Base MAC addresses separated by new lines.
            example:
              rotation_delay_before_process: 0
              prevent_time_each_port: 5
              delay_rotation_time: 0
              delay_rotation_android_time: 0
              reconnect_isp_failure_time: 300
              reconnect_isp_failure_max_retry: 3
              detect_collision_ip: true
              never_change_ip_automatically: false
              imei_changer:
                phone_models: []
                based_imei: "490154203237518"
                imei_changer_option: 1
              mac_changer:
                mac_changer_option: 1
                based_address: 02:00:00:00:00:01
      responses:
        "200":
          description: Saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
              example:
                status: true
        "400":
          description: A switch field has a value that is not true/false.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: false
                  message:
                    type: string
              example:
                status: false
                message: never_change_ip_automatically must be true or false
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: never_change_ip_automatically must be true or false
          meaning: The switch value is not a boolean or a known spelling.
          remedy: Send true or false.
        - msg: reconnect_ipv6_failure must be true or false
          meaning: The switch value is not a boolean or a known spelling.
          remedy: Send true or false.
      x-since: v20.8.0
  /hilink_change_renew_method:
    get:
      operationId: getRenewMethods
      tags:
        - Rotation settings
      summary: Read how each modem type rotates its IP and the offline-hold settings
      description: Use this to see the rotation method per modem family (Huawei Hilink, legacy Android, NextGen Android, XH22) and the offline-hold options used when a carrier keeps the same IP for a short offline time.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      responses:
        "200":
          description: Current methods.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: object
                    additionalProperties: true
                    properties:
                      huawei_method:
                        type:
                          - integer
                          - "null"
                        description: 1-7.
                      legacy_android_method:
                        type:
                          - integer
                          - "null"
                        description: 1-4.
                      nextgen_android_method:
                        type:
                          - integer
                          - "null"
                        description: 1-3; change it with the NextGen Android routes.
                      nextgen_android_connection_mode:
                        type: string
                        description: lan (default) or the configured mode.
                      xh22_rotation_method:
                        type:
                          - integer
                          - "null"
                        description: 1-5.
                      offline_hold_seconds:
                        type: integer
                        description: 0-600.
                      offline_hold_cut:
                        type: string
                        enum:
                          - radio
                          - data
                      offline_hold_verify_ip:
                        type: boolean
                      offline_hold_retries:
                        type: integer
                        description: 0-3.
              example:
                status: true
                data:
                  huawei_method: 1
                  legacy_android_method: 1
                  nextgen_android_method: 1
                  nextgen_android_connection_mode: lan
                  xh22_rotation_method: 1
                  offline_hold_seconds: 150
                  offline_hold_cut: radio
                  offline_hold_verify_ip: true
                  offline_hold_retries: 1
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
    post:
      operationId: setRenewMethods
      tags:
        - Rotation settings
      summary: Change the IP rotation method of Hilink, legacy Android or XH22 modems and the offline-hold settings
      description: "Use this to switch how a modem family gets a new IP. Every field is optional; only the ones sent are checked and saved. Offline-hold values are all validated first and one bad value saves none of them; an invalid method is refused, but fields saved earlier in the same call stay saved (order: XH22 method, offline hold, Huawei, legacy Android). Applies to the next rotation of every modem of that type."
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Changes how every modem of the type rotates. Ask the user first and verify with GET /hilink_change_renew_method.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                huawei_method:
                  type: integer
                  minimum: 1
                  maximum: 7
                legacy_android_method:
                  type: integer
                  minimum: 1
                  maximum: 4
                xh22_rotation_method:
                  type: integer
                  minimum: 1
                  maximum: 5
                offline_hold_seconds:
                  type: integer
                  minimum: 0
                  maximum: 600
                offline_hold_cut:
                  type: string
                  enum:
                    - radio
                    - data
                offline_hold_verify_ip:
                  type: boolean
                offline_hold_retries:
                  type: integer
                  minimum: 0
                  maximum: 3
            example:
              huawei_method: 2
              offline_hold_seconds: 150
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                    msg: Configuration successfully!
                badMethod:
                  summary: Invalid Huawei method
                  value:
                    status: false
                    msg: Please select right method for huawei hilink
                badHold:
                  summary: Invalid offline-hold value
                  value:
                    status: false
                    msg: offline_hold_seconds must be 0-600 (integer)
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Please select right method for XH22
          meaning: xh22_rotation_method is not 1-5.
          remedy: Send a value from 1 to 5.
        - msg: Please select right method for huawei hilink
          meaning: huawei_method is not 1-7.
          remedy: Send a value from 1 to 7.
        - msg: Please select right method for legacy android
          meaning: legacy_android_method is not 1-4.
          remedy: Send a value from 1 to 4.
        - msg: offline_hold_seconds must be 0-600 (integer)
          meaning: Hold time out of range.
          remedy: Send an integer from 0 to 600.
          origin: formatted
        - msg: offline_hold_retries must be 0-3 (integer)
          meaning: Retry count out of range.
          remedy: Send an integer from 0 to 3.
          origin: formatted
        - msg: offline_hold_cut must be one of radio, data
          meaning: Unknown cut mode.
          remedy: Send radio or data.
          origin: formatted
        - msg: offline_hold_verify_ip must be true or false
          meaning: Not a boolean.
          remedy: Send true or false.
          origin: formatted
      x-since: v20.8.0
  /stick_change_renew_method:
    post:
      operationId: setStickRenewMethod
      tags:
        - Rotation settings
      summary: Change the rotation method and auto reset/reconnect of USB stick (QMI/serial) modems
      description: Use this to choose how stick modems get a new IP and whether they reset or reconnect automatically. `method` must be the string "1", "2" or "3". `stick_adjust_time` is saved only when not empty. `stick_auto_reset` and `stick_auto_reconnect` are applied at once. A missing field fails with HTTP 500.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Changes rotation of every stick modem. Ask the user first; there is no GET for these values, so record the previous ones from the panel.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - method
                - stick_adjust_time
                - stick_auto_reset
                - stick_auto_reconnect
              properties:
                method:
                  type: string
                  enum:
                    - "1"
                    - "2"
                    - "3"
                stick_adjust_time:
                  type:
                    - integer
                    - string
                  description: Adjust time in seconds; empty keeps the saved value.
                stick_auto_reset:
                  type: boolean
                stick_auto_reconnect:
                  type: boolean
            example:
              method: "1"
              stick_adjust_time: 10
              stick_auto_reset: false
              stick_auto_reconnect: true
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                    msg: Configuration successfully!
                bad:
                  summary: Invalid method
                  value:
                    status: false
                    msg: Please select right method
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Please select right method
          meaning: method is not the string 1, 2 or 3.
          remedy: Send the method as a string.
      x-since: v20.8.0
  /v2/rotation_history:
    get:
      operationId: getRotationHistory
      tags:
        - Rotation settings
      summary: List past IP rotations of one slot in a time range
      description: Use this to audit when a slot rotated, which IP it got and how long it took. Only rotations with a public IPv4 are listed, newest first. When Smart IP Guard is on, each row also has the IP score and freshness. A missing or non-numeric `position`, `start_date` or `end_date` returns `status false` with a generic message.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      parameters:
        - name: position
          in: query
          required: true
          schema:
            type: integer
        - name: start_date
          in: query
          required: true
          description: Epoch seconds.
          schema:
            type: integer
        - name: end_date
          in: query
          required: true
          description: Epoch seconds.
          schema:
            type: integer
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        "200":
          description: History page or an error.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required:
                      - data
                      - total
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/RotationHistoryRow"
                      total:
                        type: integer
                  - $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: History
                  value:
                    data:
                      - pos: 1
                        current_ip4: 203.0.113.45
                        current_ip6: null
                        last_ip4: 203.0.113.44
                        last_ip6: null
                        rotation_time: 8.2
                        rotation_by: api
                        stamp_rotation: 1763370000000
                        status: success
                        ip_score: 99
                        freshness: fresh
                    total: 1
                error:
                  summary: Bad parameters
                  value:
                    status: false
                    msg: Have an error during request! Contact administrator!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Have an error during request! Contact administrator!
          meaning: A parameter is missing or not a number or the database query failed.
          remedy: Send integer position and epoch-second dates.
      x-since: v20.8.0
  /v2/schedule/rotation_jobs:
    post:
      operationId: getRotationScheduleJobs
      tags:
        - Rotation settings
      summary: List scheduled rotation jobs of one or more slots
      description: Use this to see which automatic rotations are planned and when they run next. Lists both system jobs (created with rotation_add_job) and selling-port interval jobs. POST is used only to carry the body; nothing changes. Returns an empty list while the scheduler is not running. A missing field returns `status false` without data.
      x-xproxy-safety: read
      x-stability: public
      x-hub: routine
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - positions
                - page
                - limit
              properties:
                positions:
                  type: array
                  items:
                    type: integer
                  description: Slots to list; an empty list lists every slot.
                page:
                  type: integer
                  minimum: 1
                limit:
                  type: integer
                  minimum: 1
            example:
              positions:
                - 1
                - 2
              page: 1
              limit: 10
      responses:
        "200":
          description: Jobs page, or `status false` on a bad body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  data:
                    type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/ScheduleRotationJob"
                      total:
                        type: integer
              examples:
                ok:
                  summary: Jobs
                  value:
                    status: true
                    data:
                      data:
                        - id: 3
                          position: 1
                          interval: 30
                          unit: minutes
                          specific_time: 00:00
                          start_time: null
                          end_time: null
                          enabled: 1
                          stamp_created: 2026-11-01 10:00:00
                          type: system
                          next_run: 1763373600
                      total: 1
                bad:
                  summary: Missing field
                  value:
                    status: false
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /v2/schedule/rotation_add_job:
    post:
      operationId: addRotationScheduleJob
      tags:
        - Rotation settings
      summary: Schedule automatic IP rotation every N seconds/minutes/hours for slots
      description: "Use this to make slots rotate on a timer. One job is created and started per position. `run_per_day` forever runs all day (start/end ignored); range runs only between `start_time` and `end_time`. `specific_time` must not be null. Jobs add up: call rotation_jobs first to avoid duplicates and rotation_remove_job to replace a job."
      x-xproxy-safety: destructive
      x-stability: public
      x-hub: routine
      x-agent-note: Creates recurring rotations that change the IP of live slots. Ask the user for the slots and interval before bulk use; verify with /v2/schedule/rotation_jobs.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - positions
                - interval
                - unit
                - run_per_day
                - specific_time
                - start_time
                - end_time
              properties:
                positions:
                  type: array
                  items:
                    type: integer
                interval:
                  type: integer
                  minimum: 1
                unit:
                  type: string
                  enum:
                    - seconds
                    - minutes
                    - hours
                run_per_day:
                  type: string
                  enum:
                    - forever
                    - range
                specific_time:
                  type: string
                  description: Time of day hh:mm the schedule is aligned to.
                start_time:
                  type:
                    - string
                    - "null"
                  description: hh:mm:ss; required when run_per_day is range.
                end_time:
                  type:
                    - string
                    - "null"
                  description: hh:mm:ss; required when run_per_day is range.
            example:
              positions:
                - 1
              interval: 30
              unit: minutes
              run_per_day: forever
              specific_time: 00:00
              start_time: null
              end_time: null
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Added
                  value:
                    status: true
                    msg: Schedule rotation added successfully!
                noSpecific:
                  summary: specific_time null
                  value:
                    status: false
                    msg: Should fill specific time on Only run option!
                failed:
                  summary: Bad body or database error
                  value:
                    status: false
                    msg: Schedule rotation failed to add!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Should fill specific time on Only run option!
          meaning: specific_time is null.
          remedy: Send a time such as 00:00.
        - msg: Should fill on the "from" field of Run every day in time range!
          meaning: run_per_day is range but start_time is null.
          remedy: Send start_time.
        - msg: Should fill on the "to" field of Run every day in time range!
          meaning: run_per_day is range but end_time is null.
          remedy: Send end_time.
        - msg: Schedule rotation failed to add!
          meaning: A field is missing or the job could not be stored.
          remedy: Send every required field and retry.
      x-since: v20.8.0
  /v2/schedule/rotation_remove_job:
    post:
      operationId: removeRotationScheduleJob
      tags:
        - Rotation settings
      summary: Remove one scheduled rotation job, or all system jobs of the given slots
      description: Use this to stop automatic rotation. With a job `id` it removes that job from each listed position; with an empty or null `id` it removes every system job of those positions. Selling-port interval jobs are not touched.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: routine
      x-agent-note: Without an id this deletes every system schedule of the slots. Confirm the slots with the user; verify with /v2/schedule/rotation_jobs.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - positions
                - id
              properties:
                positions:
                  type: array
                  minItems: 1
                  items:
                    type: integer
                id:
                  type:
                    - integer
                    - "null"
                  description: Job id from rotation_jobs; null removes all system jobs of the positions.
            example:
              positions:
                - 1
              id: 3
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Removed
                  value:
                    status: true
                    msg: Remove all schedule rotation system jobs successfully!
                noPositions:
                  summary: Empty positions
                  value:
                    status: false
                    msg: Missing param "positions"!
                failed:
                  summary: Missing field
                  value:
                    status: false
                    msg: Remove schedule rotation failed!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Missing param "positions"!
          meaning: positions is empty.
          remedy: Send at least one position.
        - msg: Remove schedule rotation failed!
          meaning: positions or id is missing from the body or removal failed.
          remedy: Send both fields (id may be null).
      x-since: v20.8.0
  /selling/shared_proxies:
    get:
      operationId: listSellingProxies
      tags:
        - Selling platform
      summary: List the proxies you sell, with customer credentials, expiry and data used
      description: Returns one page of sold proxies with filters. Each row contains the customer's proxy credentials and API token, so the answer holds secrets. Needs the Selling Platform license.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      parameters:
        - name: page
          in: query
          required: false
          description: Page number from 1.
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          required: false
          description: Rows per page.
          schema:
            type: integer
            default: 20
          example: 20
        - name: search
          in: query
          required: false
          description: Matches memo, port, slot, id, tags or group slots.
          schema:
            type: string
          example: shop-a
        - name: modemPosition
          in: query
          required: false
          description: Only proxies using this slot (also inside groups).
          schema:
            type: integer
          example: 1
        - name: id
          in: query
          required: false
          description: One sold-proxy id.
          schema:
            type: integer
          example: 12
        - name: proxyPort
          in: query
          required: false
          schema:
            type: integer
          example: 20001
        - name: rentStatus
          in: query
          required: false
          schema:
            type: string
            enum:
              - expired
              - in_used
          example: in_used
        - name: portStatus
          in: query
          required: false
          description: Whether the port is listening now.
          schema:
            type: string
            enum:
              - active
              - inactive
          example: active
        - name: sharedStatus
          in: query
          required: false
          schema:
            type: string
            enum:
              - enabled
              - disabled
          example: enabled
        - name: nextDayExpired
          in: query
          required: false
          description: Only proxies expiring within this many days.
          schema:
            type: number
          example: 3
        - name: memo
          in: query
          required: false
          schema:
            type: string
          example: shop-a
        - name: tags
          in: query
          required: false
          description: Repeat for several tags (any match).
          schema:
            type: array
            items:
              type: string
          example:
            - vip
      responses:
        "200":
          description: Page of sold proxies, or the license refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/SellingProxyList"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                page:
                  summary: One proxy
                  value:
                    status: true
                    total: 1
                    stats: {}
                    xraySellingAllowed: true
                    data:
                      - id: 12
                        position: 1
                        group_positions: null
                        gen_method: 1
                        shared_port: 20001
                        port_type: PROXY
                        ip_type: IPv4
                        auth_ip_list: ""
                        auth_user_list: YOUR_USER:YOUR_PASSWORD
                        expired_at: 17/12/2026 10:00
                        expired_at_unix: 1797501600000
                        remaining: 30
                        remaining_str: 30 days
                        is_expired: false
                        enabled: true
                        locked: false
                        counter_all_limit: limited
                        counter_all_limit_by: MONTHLY
                        counter_all_limit_quota: 10240
                        counter_all_used_mb: 512.4
                        bw_limit_enabled: false
                        bw_limit_rate: 0
                        connection_limit: 100
                        connection_limit_period: 60
                        idle_timeout: 30
                        interval_rotation: 0
                        allow_api_rotate: true
                        min_second_rotate: 60
                        allow_api_change_rotation: false
                        min_interval_rotation: 0
                        tcp_os: linux
                        memo: shop-a
                        tags:
                          - vip
                        api_token: YOUR_SELLING_TOKEN
                        created_at: 17/11/2026 10:00
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
      x-since: v20.8.0
  /selling/generate:
    post:
      operationId: generateSellingProxies
      tags:
        - Selling platform
      summary: Create new proxies to sell, on one slot each or as group proxies
      description: Creates sold proxies (new listening ports) and starts them. With `genMethod` 1 it creates `numberOfPorts` ports per slot in `selected_positions` (or `positionFrom`..`positionTo`); with 2 it creates `numberOfPorts` ports that spread over all selected slots. Answers with the created rows, which contain credentials and API tokens. VLESS and Shadowsocks port types need a Premium or Business license and are refused with HTTP 403 otherwise.
      x-xproxy-safety: destructive
      x-agent-note: Opens new public proxy ports and may change auth on the box. Confirm slots, count and expiry with the user before calling; verify with /selling/shared_proxies. A missing `numberOfPorts` or `expiredDate` makes the box answer HTTP 500.
      x-stability: panel
      x-hub: approval
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/SellingProxyEdit"
                - type: object
                  required:
                    - numberOfPorts
                    - expiredDate
                  properties:
                    genMethod:
                      type: integer
                      enum:
                        - 1
                        - 2
                      default: 1
                      description: 1 one slot per proxy, 2 group proxy.
                    selected_positions:
                      type: array
                      items:
                        type: integer
                      description: Slots to use. Without it `positionFrom` and `positionTo` are required.
                    positionFrom:
                      type: integer
                    positionTo:
                      type: integer
                    numberOfPorts:
                      type: integer
                      minimum: 1
                    genPort:
                      type: integer
                      enum:
                        - 1
                        - 2
                      default: 1
                      description: 1 random ports, 2 sequential from genPortStart.
                    genPortStart:
                      type: integer
                      default: 20001
                    isAutoGenDifferenceEachPort:
                      type: boolean
                      default: true
                    vlessFlow:
                      type: string
            example:
              genMethod: 1
              selected_positions:
                - 1
                - 2
              numberOfPorts: 1
              genPort: 2
              genPortStart: 20001
              portType: 0
              ipType: 1
              expiredDate: 1797501600000
              isAutoGenAuthentication: true
              isAutoGenDifferenceEachPort: true
              allowApiRotate: true
              minSecondRotate: 60
              memo: shop-a
      responses:
        "200":
          description: Created rows, or the license refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/SellingProxy"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                created:
                  summary: One proxy created
                  value:
                    status: true
                    data:
                      - id: 12
                        position: 1
                        shared_port: 20001
                        port_type: PROXY
                        ip_type: IPv4
                        auth_user_list: YOUR_USER:YOUR_PASSWORD
                        expired_at: 17/12/2026 10:00
                        enabled: true
                        api_token: YOUR_SELLING_TOKEN
                        memo: shop-a
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: VLESS or Shadowsocks port type without a Premium or Business license.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              example:
                status: false
                msg: VLESS and Shadowsocks require a Premium or Business license
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: VLESS and Shadowsocks require a Premium or Business license
          meaning: portType 3 or 4 on a license without Xray selling (HTTP 403).
          remedy: Use portType 0-2 or upgrade the license.
      x-since: v20.8.0
  /selling/bulk_edit:
    post:
      operationId: bulkEditSellingProxies
      tags:
        - Selling platform
      summary: Change settings of several sold proxies at once
      description: "Updates only the fields present in the body (or forced with `default_FIELD: false`) on every id in `ids`, then restarts those ports. Answers with the updated rows, which contain credentials and API tokens. VLESS and Shadowsocks need a Premium or Business license (HTTP 403)."
      x-xproxy-safety: destructive
      x-agent-note: Restarts the listed ports, dropping customer connections, and can change their credentials or expiry. Confirm the ids and fields with the user; verify with /selling/shared_proxies.
      x-stability: panel
      x-hub: approval
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/SellingIds"
                - $ref: "#/components/schemas/SellingProxyEdit"
                - type: object
                  properties:
                    position:
                      type: integer
                      description: New slot for single-destination proxies.
                    selected_positions:
                      type: array
                      items:
                        type: integer
                      description: New slots for group proxies.
            example:
              ids:
                - 12
                - 13
              expiredDate: 1797501600000
              memo: shop-a
      responses:
        "200":
          description: Updated rows, or a refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/SellingProxy"
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                updated:
                  summary: Updated
                  value:
                    status: true
                    data:
                      - id: 12
                        shared_port: 20001
                        port_type: PROXY
                        expired_at: 17/12/2026 10:00
                        enabled: true
                        api_token: YOUR_SELLING_TOKEN
                        memo: shop-a
                noIds:
                  summary: Empty ids
                  value:
                    status: false
                    data: Invalid request [ids not found]!
                badIdle:
                  summary: idleTimeout out of range
                  value:
                    status: false
                    data: Invalid idleTimeout, range [1-86400s]
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: VLESS or Shadowsocks port type without a Premium or Business license.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              example:
                status: false
                msg: VLESS and Shadowsocks require a Premium or Business license
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: VLESS and Shadowsocks require a Premium or Business license
          meaning: portType 3 or 4 on a license without Xray selling (HTTP 403).
          remedy: Use portType 0-2 or upgrade the license.
        - msg: Invalid request [ids not found]!
          meaning: ids is missing or empty (returned in `data`).
          remedy: Send at least one id.
        - msg: Invalid idleTimeout, range [1-86400s]
          meaning: idleTimeout outside 1-86400 (returned in `data`).
          remedy: Use 1-86400 seconds.
      x-since: v20.8.0
  /selling/bulk_delete:
    post:
      operationId: bulkDeleteSellingProxies
      tags:
        - Selling platform
      summary: Delete sold proxies and close their ports
      description: Stops and deletes the listed sold proxies. Their customers lose access at once and their links stop working. Echoes the request body. A body without `ids` makes the box answer HTTP 500.
      x-xproxy-safety: destructive
      x-agent-note: "Irreversible: customers lose their proxies. Confirm every id with the user, never delete in bulk without explicit approval; verify with /selling/shared_proxies."
      x-stability: panel
      x-hub: approval
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SellingIds"
            example:
              ids:
                - 12
      responses:
        "200":
          description: Request echoed, or the license refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      data:
                        $ref: "#/components/schemas/SellingIds"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                deleted:
                  summary: Deleted
                  value:
                    status: true
                    data:
                      ids:
                        - 12
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
      x-since: v20.8.0
  /selling/bulk_extend_expired:
    post:
      operationId: extendSellingProxiesExpiry
      tags:
        - Selling platform
      summary: Move the expiry date of sold proxies, by days, hours or to a fixed time
      description: Sets a new expiry on the listed sold proxies, either `expired_unix_time` or adding `expired_extend_days` / `expired_extend_hours`, then restarts them. Answers with the updated rows, which contain credentials and API tokens. Does not reset data counters (use /selling/renew_proxy for that).
      x-xproxy-safety: destructive
      x-agent-note: Changes what customers are entitled to and restarts their ports. Confirm ids and period with the user; verify `expired_at` in the answer.
      x-stability: panel
      x-hub: approval
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/SellingIds"
                - type: object
                  properties:
                    expired_unix_time:
                      type: integer
                      description: New expiry (epoch).
                    expired_extend_days:
                      type: number
                    expired_extend_hours:
                      type: number
            example:
              ids:
                - 12
              expired_extend_days: 30
      responses:
        "200":
          description: Updated rows, or the license refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/SellingProxy"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                extended:
                  summary: Extended
                  value:
                    status: true
                    data:
                      - id: 12
                        shared_port: 20001
                        expired_at: 17/01/2027 10:00
                        is_expired: false
                        api_token: YOUR_SELLING_TOKEN
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
      x-since: v20.8.0
  /selling/renew_proxy:
    post:
      operationId: renewSellingProxies
      tags:
        - Selling platform
      summary: Renew sold proxies for another period, optionally resetting their data counters
      description: Extends each listed proxy by `period_value` `period_type` (max 3650 days, 520 weeks or 120 months), records it in the renewal history under the dashboard user, and with `reset_counters` zeroes their data counters. Ports stopped by expiry start again. `status` is true when at least one proxy was renewed; `data.failed` lists the others with a reason.
      x-xproxy-safety: destructive
      x-agent-note: Changes customer entitlements and can zero their counters. Confirm ids and period with the user; check `data.failed` in the answer.
      x-stability: panel
      x-hub: approval
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/SellingIds"
                - type: object
                  required:
                    - period_value
                    - period_type
                  properties:
                    period_value:
                      type: integer
                      minimum: 1
                    period_type:
                      type: string
                      enum:
                        - days
                        - weeks
                        - months
                    reset_counters:
                      type: boolean
                      default: false
            example:
              ids:
                - 12
              period_value: 1
              period_type: months
              reset_counters: true
      responses:
        "200":
          description: Renewal result, or a refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                      data:
                        type: object
                        properties:
                          status:
                            type: boolean
                          successful:
                            type: array
                            items:
                              type: integer
                          failed:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                reason:
                                  type: string
                          total_renewed:
                            type: integer
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                renewed:
                  summary: Renewed
                  value:
                    status: true
                    data:
                      status: true
                      successful:
                        - 12
                      failed: []
                      total_renewed: 1
                noIds:
                  summary: No ids
                  value:
                    status: false
                    message: No proxy IDs provided
                badPeriod:
                  summary: Bad period
                  value:
                    status: false
                    message: Period type must be 'days', 'weeks', or 'months'
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SellingRefusal"
              example:
                status: false
                message: Renewal failed
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: No proxy IDs provided
          meaning: ids is missing or empty.
          remedy: Send at least one id.
        - msg: period_value and period_type are required
          meaning: One of them is missing.
          remedy: Send both.
        - msg: Period value must be a positive integer
          meaning: period_value is not a positive integer.
          remedy: Send an integer of 1 or more.
        - msg: Period type must be 'days', 'weeks', or 'months'
          meaning: Unknown period_type.
          remedy: Use days
          weeks or months.: null
        - msg: Period value exceeds maximum (N period_type)
          meaning: More than 3650 days
          520 weeks or 120 months.: null
          remedy: Use a shorter period.
        - msg: Renewal failed
          meaning: Unexpected error (HTTP 500).
          remedy: Check the box logs.
      x-since: v21.0.5
  /selling/reset_data_counter:
    post:
      operationId: resetSellingDataCounter
      tags:
        - Selling platform
      summary: Zero the data counters of sold proxies so a customer who hit the quota can use them again
      description: Resets the upload, download and total counters of the listed proxies and writes a manual entry to their quota reset history. Ports on the older counter are stopped and restarted. Echoes the request body. A body without `ids` makes the box answer HTTP 500.
      x-xproxy-safety: destructive
      x-agent-note: Erases the usage the customer has consumed this period. Confirm ids with the user; verify with /selling/shared_proxies (`counter_all_used_mb`).
      x-stability: panel
      x-hub: approval
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SellingIds"
            example:
              ids:
                - 12
      responses:
        "200":
          description: Request echoed, or the license refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      data:
                        $ref: "#/components/schemas/SellingIds"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                reset:
                  summary: Reset
                  value:
                    status: true
                    data:
                      ids:
                        - 12
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
      x-since: v20.8.0
  /selling/rotate:
    get:
      operationId: rotateSellingProxyIp
      tags:
        - Selling platform
      summary: Let a customer get a new IP for the proxy they rent, with its token link
      description: Rotates the slot behind one sold proxy. Works only when the seller allowed API rotation for that proxy and the last rotation is older than its minimum interval; group proxies are refused. Refusals come in `data` (not allowed) or `message` (all others).
      x-xproxy-safety: action
      x-agent-note: Changes the public IP and drops connections for 10-60 seconds. Do not loop; on "Please waiting for next" wait the given seconds. Check `status`, the HTTP code is 200 even on refusal.
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the sold proxy's API token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - sellingToken: []
      parameters:
        - $ref: "#/components/parameters/SellingToken"
      responses:
        "200":
          description: Rotation result or refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      message:
                        type: string
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                rotated:
                  summary: Rotated
                  value:
                    status: true
                    message: Rotate successfully!
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    message: API Token invalid
                notAllowed:
                  summary: Rotation not allowed
                  value:
                    status: false
                    data: Feature does not allowed
                tooSoon:
                  summary: Too soon
                  value:
                    status: false
                    message: "Please waiting for next: 42 seconds"
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: API Token invalid
          meaning: Token unknown or reset (in `message`).
          remedy: Ask the seller for the current link; tokens change when reset.
        - msg: Feature does not allowed for proxy group
          meaning: The proxy is a group proxy (in `data`).
          remedy: Not available for group proxies.
        - msg: Feature does not allowed
          meaning: The seller did not allow API rotation (in `data`).
          remedy: Ask the seller to enable it.
        - msg: "Please waiting for next: N seconds"
          meaning: Minimum rotation interval not reached.
          remedy: Wait N seconds.
        - msg: Proxy is not ready, try again later!
          meaning: The slot has no modem right now.
          remedy: Retry later.
        - msg: MODEM_STOPPED
          meaning: Rotation refused by the slot (code from the rotation itself, in `message`).
          remedy: Contact the seller.
        - msg: Try again later!
          meaning: Unexpected error.
          remedy: Retry later.
      x-since: v20.8.0
  /selling/change_interval_rotation:
    get:
      operationId: changeSellingRotationInterval
      tags:
        - Selling platform
      summary: Let a customer set or turn off automatic IP rotation of the proxy they rent
      description: Sets the auto-rotation interval in seconds; `seconds=0` turns auto-rotation off. A non-zero value needs the seller's permission and must be at least the proxy's minimum interval and below one year. Group proxies are refused. Refusals come in `data` (token, permission, validation) or `message` (save failures).
      x-xproxy-safety: action
      x-agent-note: Changes how often the customer's IP changes. Ask before changing; verify with /selling/info (`interval_rotation`).
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the sold proxy's API token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - sellingToken: []
      parameters:
        - $ref: "#/components/parameters/SellingToken"
        - name: seconds
          in: query
          required: true
          description: Interval in seconds; 0 turns auto-rotation off.
          schema:
            type: integer
            minimum: 0
          example: 600
      responses:
        "200":
          description: Result or refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      message:
                        type: string
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                changed:
                  summary: Changed
                  value:
                    status: true
                    message: Changed successfully!
                disabled:
                  summary: Turned off
                  value:
                    status: true
                    message: Disable successfully!
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    data: API Token invalid
                tooLow:
                  summary: Below minimum
                  value:
                    status: false
                    data: "Minimum allowed: 300s"
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: API Token invalid
          meaning: Token unknown or reset (in `data`).
          remedy: Ask the seller for the current link.
        - msg: Feature does not allowed for proxy group
          meaning: The proxy is a group proxy (in `data`).
          remedy: Not available for group proxies.
        - msg: Feature does not allowed
          meaning: The seller did not allow interval changes (in `data`).
          remedy: Ask the seller.
        - msg: Invalid param seconds
          meaning: Negative or one year or more (in `data`).
          remedy: Use 0 or a value below one year.
        - msg: "Minimum allowed: Ns"
          meaning: Below the proxy's minimum interval (in `data`).
          remedy: Use at least N seconds.
        - msg: Changed failed [1]!
          meaning: Could not save the off setting (in `message`).
          remedy: Retry; contact the seller.
        - msg: Changed failed [2]!
          meaning: Could not save the interval (in `message`).
          remedy: Retry; contact the seller.
        - msg: Error during change interval rotation, please contact administrator
          meaning: Unexpected error (in `message`).
          remedy: Contact the seller.
      x-since: v20.8.0
  /selling/info:
    get:
      operationId: getSellingProxyInfo
      tags:
        - Selling platform
      summary: Show a customer everything about the proxy they rent, including all their self-service links
      description: Returns the proxy address, type, credentials, limits, expiry, permissions, TCP OS profile, quota reset info and the ready-made links of every other customer route. Returns secrets (the token and the proxy credentials). An unknown token answers with the error in `data`.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the sold proxy's API token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - sellingToken: []
      parameters:
        - $ref: "#/components/parameters/SellingToken"
      responses:
        "200":
          description: Proxy details or refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      message:
                        type: string
                      data:
                        type: object
                        additionalProperties: true
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                info:
                  summary: Proxy details
                  value:
                    status: true
                    message: Get message successfully!
                    data:
                      token: YOUR_SELLING_TOKEN
                      domain: 203.0.113.10
                      proxy_port: 20001
                      proxy_type: PROXY
                      port_type_desc: both http & socks5 proxy
                      proxy_user: YOUR_USER:YOUR_PASSWORD
                      proxy_formatted: http://YOUR_USER:YOUR_PASSWORD@203.0.113.10:20001
                      interval_rotation: not set
                      max_connection: 100 per 60s
                      bandwidth_limited: unlimited
                      rotation_link: http://203.0.113.10:8080/selling/rotate?token=YOUR_SELLING_TOKEN
                      info_link: http://203.0.113.10:8080/selling/info?token=YOUR_SELLING_TOKEN
                      expired_date: 12/17/2026 10:00
                      created_date: 11/17/2026 10:00
                      system_time: 11/17/2026 12:00
                      permission_interval_rotation: disallowed
                      permission_api_rotate: "allowed, min: 60s"
                      tcp_os: linux
                      tcp_os_name: Linux (default, no spoofing)
                      tcp_os_profiles_link: http://203.0.113.10:8080/selling/tcp_os_profiles
                      quota_reset_info: {}
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    data: API Token invalid
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: API Token invalid
          meaning: Token unknown or reset (in `data`).
          remedy: Ask the seller for the current link.
      x-since: v20.8.0
  /selling/change_user:
    get:
      operationId: changeSellingProxyUser
      tags:
        - Selling platform
      summary: Let a customer replace the username and password of the proxy they rent
      description: Replaces the proxy's user:pass with the given pair and restarts the port. Both values must be 3-15 letters or digits. When `user` or `pass` is missing the box answers `status:false` with an empty `message`.
      x-xproxy-safety: destructive
      x-agent-note: The old credentials stop working at once and open connections drop. Ask the user before changing; verify with /selling/info (`proxy_user`).
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the sold proxy's API token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - sellingToken: []
      parameters:
        - $ref: "#/components/parameters/SellingToken"
        - name: user
          in: query
          required: true
          description: New username, 3-15 letters or digits.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9]{3,15}$
          example: newuser
        - name: pass
          in: query
          required: true
          x-secret: true
          description: New password, 3-15 letters or digits.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9]{3,15}$
          example: YOUR_NEW_PASSWORD
      responses:
        "200":
          description: Result or refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                changed:
                  summary: Changed
                  value:
                    status: true
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    message: API Token invalid
                badFormat:
                  summary: Bad format
                  value:
                    status: false
                    message: "Username or password only allowed 3 to 15 characters and allow non-special characters: a-z, A-Z, 0-9"
                missing:
                  summary: user or pass missing
                  value:
                    status: false
                    message: ""
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "500":
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SellingRefusal"
              example:
                status: false
                message: An error occurred while processing the request
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: API Token invalid
          meaning: Token unknown or reset (in `message`).
          remedy: Ask the seller for the current link; tokens change when reset.
        - msg: "Username or password only allowed 3 to 15 characters and allow non-special characters: a-z, A-Z, 0-9"
          meaning: user or pass has the wrong format.
          remedy: Use 3-15 letters or digits.
        - msg: ""
          meaning: token
          user or pass is missing (empty message).: null
          remedy: Send all three parameters.
        - msg: An error occurred while processing the request
          meaning: Unexpected error (HTTP 500).
          remedy: Retry; contact the seller.
      x-since: v20.8.0
  /selling/change_whitelist:
    get:
      operationId: changeSellingProxyWhitelist
      tags:
        - Selling platform
      summary: Let a customer set which IPs may use the proxy they rent without a password
      description: Replaces the proxy's IP whitelist with the IPs in `ips` (comma-separated) and restarts the port. Without `ips` the whitelist is cleared.
      x-xproxy-safety: destructive
      x-agent-note: IPs not in the new list lose password-less access at once. Ask the user before changing; verify by connecting from a listed IP.
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the sold proxy's API token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - sellingToken: []
      parameters:
        - $ref: "#/components/parameters/SellingToken"
        - name: ips
          in: query
          required: false
          description: Comma-separated IPv4 addresses; empty clears the whitelist.
          schema:
            type: string
          example: 203.0.113.5,203.0.113.6
      responses:
        "200":
          description: Result or refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                changed:
                  summary: Changed
                  value:
                    status: true
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    message: API Token invalid
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "500":
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SellingRefusal"
              example:
                status: false
                message: An error occurred while processing the request
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: API Token invalid
          meaning: Token unknown or reset (in `message`).
          remedy: Ask the seller for the current link; tokens change when reset.
        - msg: An error occurred while processing the request
          meaning: Unexpected error (HTTP 500).
          remedy: Retry; contact the seller.
      x-since: v20.8.0
  /selling/rotation_history:
    get:
      operationId: getSellingRotationHistory
      tags:
        - Selling platform
      summary: Show a customer which IPs the proxy they rent had, and when
      description: Lists successful rotations since the proxy was created, by default over the last 30 days. Use `last_days`, or `start_date`/`end_date` (epoch seconds). The success answer has no `status` field.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the sold proxy's API token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - sellingToken: []
      parameters:
        - $ref: "#/components/parameters/SellingToken"
        - name: last_days
          in: query
          required: false
          description: Look back this many days; overrides start_date and end_date.
          schema:
            type: integer
            minimum: 1
          example: 30
        - name: start_date
          in: query
          required: false
          description: Epoch seconds; default 30 days ago.
          schema:
            type: integer
          example: 1763251200
        - name: end_date
          in: query
          required: false
          description: Epoch seconds; default now.
          schema:
            type: integer
          example: 1763337600
      responses:
        "200":
          description: Rotation list or refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            time:
                              type: string
                            position:
                              type: integer
                            ipv4:
                              type: string
                            ipv6:
                              type:
                                - string
                                - "null"
                            rotate_secs:
                              type:
                                - integer
                                - "null"
                      total_unique_ipv4:
                        type: integer
                      total:
                        type: integer
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                history:
                  summary: Two rotations
                  value:
                    items:
                      - time: 2026-11-17 10:00:00
                        position: 1
                        ipv4: 203.0.113.45
                        ipv6: 2001:db8::45
                        rotate_secs: 12
                      - time: 2026-11-17 09:00:00
                        position: 1
                        ipv4: 203.0.113.44
                        ipv6: null
                        rotate_secs: 11
                    total_unique_ipv4: 2
                    total: 2
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    message: API Token invalid
                badDays:
                  summary: Bad last_days
                  value:
                    status: false
                    message: last_days argument is not valid!
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "500":
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SellingRefusal"
              example:
                status: false
                message: An error occurred while processing the request
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: API Token invalid
          meaning: Token unknown or reset (in `message`).
          remedy: Ask the seller for the current link; tokens change when reset.
        - msg: last_days argument is not valid!
          meaning: last_days is not a positive integer.
          remedy: Send a positive integer.
        - msg: start_date argument is not valid!
          meaning: start_date is not a positive integer.
          remedy: Send epoch seconds.
        - msg: end_date argument is not valid!
          meaning: end_date is not a positive integer.
          remedy: Send epoch seconds.
        - msg: ""
          meaning: token is missing (empty message).
          remedy: Send the token.
        - msg: An error occurred while processing the request
          meaning: Unexpected error (HTTP 500).
          remedy: Retry; contact the seller.
      x-since: v20.8.0
  /selling/change_tcp_os:
    get:
      operationId: changeSellingTcpOs
      tags:
        - Selling platform
      summary: Let a customer change the operating system the proxy's TCP fingerprint imitates
      description: Sets the TCP OS fingerprint profile of the proxy and restarts the port. Profile ids come from /selling/tcp_os_profiles. Group proxies are refused (in `data`); other refusals come in `message`.
      x-xproxy-safety: action
      x-agent-note: Restarts the customer's port. Ask before changing; verify with /selling/info (`tcp_os`).
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the sold proxy's API token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - sellingToken: []
      parameters:
        - $ref: "#/components/parameters/SellingToken"
        - name: tcp_os
          in: query
          required: true
          description: Profile id, 1-8 letters or digits.
          schema:
            type: string
            pattern: ^[a-zA-Z0-9]{1,8}$
          example: win3
      responses:
        "200":
          description: Result or refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      message:
                        type: string
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                changed:
                  summary: Changed
                  value:
                    status: true
                    message: TCP OS changed successfully!
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    message: API Token invalid
                notFound:
                  summary: Unknown profile
                  value:
                    status: false
                    message: TCP OS profile not found
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "500":
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SellingRefusal"
              example:
                status: false
                message: An error occurred while processing the request
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: API Token invalid
          meaning: Token unknown or reset (in `message`).
          remedy: Ask the seller for the current link; tokens change when reset.
        - msg: Token and tcp_os parameters are required
          meaning: token or tcp_os missing.
          remedy: Send both.
        - msg: Invalid TCP OS profile ID format
          meaning: tcp_os is not 1-8 letters or digits.
          remedy: Use an id from /selling/tcp_os_profiles.
        - msg: Feature does not allowed for proxy group
          meaning: The proxy is a group proxy (in `data`).
          remedy: Not available for group proxies.
        - msg: TCP OS profile not found
          meaning: No profile with this id.
          remedy: Use an id from /selling/tcp_os_profiles.
        - msg: Failed to update TCP OS
          meaning: Could not save.
          remedy: Retry; contact the seller.
        - msg: An error occurred while processing the request
          meaning: Unexpected error (HTTP 500).
          remedy: Retry; contact the seller.
      x-since: v20.8.24
  /selling/tcp_os_profiles:
    get:
      operationId: listSellingTcpOsProfiles
      tags:
        - Selling platform
      summary: List the TCP OS fingerprint profiles a customer can choose
      description: Returns the id and name of every TCP OS fingerprint profile on the box. Needs no token; still refused when the license has no Selling Platform.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Public; no token or login needed.
      security: []
      responses:
        "200":
          description: Profiles or the license refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            profile_id:
                              type: string
                            profile_name:
                              type: string
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                profiles:
                  summary: Profiles
                  value:
                    status: true
                    data:
                      - profile_id: linux
                        profile_name: Linux (default, no spoofing)
                      - profile_id: win3
                        profile_name: Windows 10/11
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "500":
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SellingRefusal"
              example:
                status: false
                message: An error occurred while processing the request
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: An error occurred while processing the request
          meaning: Unexpected error (HTTP 500).
          remedy: Retry; contact the seller.
      x-since: v20.8.24
  /selling/uptime_stats:
    get:
      operationId: getSellingUptimeStats
      tags:
        - Selling platform
      summary: Show a customer per-day uptime of the proxy they rent
      description: Returns per-day time slots marked up (1) or down for the proxy's slot (for group proxies a slot is up when any member is up). Default range is the last 24 hours; at most 7 days.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the sold proxy's API token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - sellingToken: []
      parameters:
        - $ref: "#/components/parameters/SellingToken"
        - $ref: "#/components/parameters/SellingLastHours"
        - $ref: "#/components/parameters/SellingStartDate"
        - $ref: "#/components/parameters/SellingEndDate"
      responses:
        "200":
          description: Uptime per day or refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      data:
                        type: object
                        description: Date (YYYY-MM-DD) to list of time and status.
                        additionalProperties: true
                      total:
                        type: integer
                        description: Number of days.
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                stats:
                  summary: One day
                  value:
                    status: true
                    data:
                      2026-11-17:
                        - time: 10:00
                          status: 1
                        - time: 10:10
                          status: 1
                    total: 1
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    message: API Token invalid
                tooLong:
                  summary: Range too long
                  value:
                    status: false
                    message: Please select date range is not over than 7 days!
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "500":
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SellingRefusal"
              example:
                status: false
                message: An error occurred while processing the request
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: Token is required
          meaning: token is missing.
          remedy: Send the token.
        - msg: API Token invalid
          meaning: Token unknown or reset (in `message`).
          remedy: Ask the seller for the current link; tokens change when reset.
        - msg: last_hours must be a positive number
          meaning: last_hours is 0 or negative.
          remedy: Send a positive integer.
        - msg: Invalid last_hours format. Must be a positive integer.
          meaning: last_hours is not an integer.
          remedy: Send a positive integer.
        - msg: Invalid date format. Use Unix timestamp in seconds.
          meaning: start_date or end_date is not an integer.
          remedy: Send epoch seconds.
        - msg: Please select date range is not over than 7 days!
          meaning: Range longer than 7 days.
          remedy: Shorten the range.
        - msg: No positions found for proxy group
          meaning: The group proxy has no slots.
          remedy: Contact the seller.
        - msg: An error occurred while processing the request
          meaning: Unexpected error (HTTP 500).
          remedy: Retry; contact the seller.
      x-since: v20.9.32
  /selling/uptime_log:
    get:
      operationId: getSellingUptimeLog
      tags:
        - Selling platform
      summary: Show a customer the up and down events of the proxy they rent
      description: Returns paged up/down events, newest first, for the proxy's slot (all member slots for group proxies). Default range is the last 24 hours; at most 7 days. A non-integer `page` or `limit` makes the box answer HTTP 500.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the sold proxy's API token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - sellingToken: []
      parameters:
        - $ref: "#/components/parameters/SellingToken"
        - $ref: "#/components/parameters/SellingLastHours"
        - $ref: "#/components/parameters/SellingStartDate"
        - $ref: "#/components/parameters/SellingEndDate"
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
          example: 10
      responses:
        "200":
          description: Events or refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            status:
                              description: Up or down state as stored by the box.
                            datetime:
                              type: integer
                              description: Epoch seconds.
                            datetime_str:
                              type: string
                      total:
                        type: integer
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                log:
                  summary: One event
                  value:
                    status: true
                    data:
                      - status: 1
                        datetime: 1763373600
                        datetime_str: 2026-11-17 10:00:00
                    total: 1
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    message: API Token invalid
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "500":
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SellingRefusal"
              example:
                status: false
                message: An error occurred while processing the request
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: Token is required
          meaning: token is missing.
          remedy: Send the token.
        - msg: API Token invalid
          meaning: Token unknown or reset (in `message`).
          remedy: Ask the seller for the current link; tokens change when reset.
        - msg: last_hours must be a positive number
          meaning: last_hours is 0 or negative.
          remedy: Send a positive integer.
        - msg: Invalid last_hours format. Must be a positive integer.
          meaning: last_hours is not an integer.
          remedy: Send a positive integer.
        - msg: Invalid date format. Use Unix timestamp in seconds.
          meaning: start_date or end_date is not an integer.
          remedy: Send epoch seconds.
        - msg: Please select date range is not over than 7 days!
          meaning: Range longer than 7 days.
          remedy: Shorten the range.
        - msg: No positions found for proxy group
          meaning: The group proxy has no slots.
          remedy: Contact the seller.
        - msg: An error occurred while processing the request
          meaning: Unexpected error (HTTP 500).
          remedy: Retry; contact the seller.
      x-since: v20.9.32
  /selling/quota_reset_history_by_token:
    get:
      operationId: getSellingQuotaResetHistory
      tags:
        - Selling platform
      summary: Show a customer when the data quota of the proxy they rent was reset and how much was used before
      description: Returns paged quota reset records (automatic and manual) of the proxy. A non-integer `page` or `limit` makes the box answer HTTP 500.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the sold proxy's API token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - sellingToken: []
      parameters:
        - $ref: "#/components/parameters/SellingToken"
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
          example: 20
      responses:
        "200":
          description: Reset records or refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      data:
                        type: array
                        items:
                          type: object
                          additionalProperties: true
                      total:
                        type: integer
                      page:
                        type: integer
                      limit:
                        type: integer
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                history:
                  summary: One reset
                  value:
                    status: true
                    data:
                      - id: 3
                        shared_proxy_id: 12
                        shared_port: 20001
                        reset_type: MONTHLY
                        quota_type: ALL
                        bytes_before_reset: 1073741824
                        dl_bytes_before_reset: 1000000000
                        ul_bytes_before_reset: 73741824
                        quota_limit_mb: 10240
                        reset_reason: scheduled
                        reset_at: 1763373600000
                        renew_date: 1760781600000
                    total: 1
                    page: 1
                    limit: 20
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    message: API Token invalid
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "500":
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SellingRefusal"
              example:
                status: false
                message: An error occurred while processing the request
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: Token is required
          meaning: token is missing.
          remedy: Send the token.
        - msg: API Token invalid
          meaning: Token unknown or reset (in `message`).
          remedy: Ask the seller for the current link; tokens change when reset.
        - msg: An error occurred while processing the request
          meaning: Unexpected error (HTTP 500).
          remedy: Retry; contact the seller.
      x-since: v20.9.38
  /selling/quota_info_by_token:
    get:
      operationId: getSellingQuotaInfo
      tags:
        - Selling platform
      summary: Show a customer the data used, quota left and next reset time of the proxy they rent
      description: Returns, for each limited counter (DL, UL, ALL), the quota, data used, data left, last and next reset, plus the last reset record per counter.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the sold proxy's API token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - sellingToken: []
      parameters:
        - $ref: "#/components/parameters/SellingToken"
      responses:
        "200":
          description: Quota info or refusal.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: true
                      data:
                        $ref: "#/components/schemas/SellingQuotaInfo"
                  - $ref: "#/components/schemas/SellingRefusal"
                  - $ref: "#/components/schemas/SellingLicenseGate"
              examples:
                quota:
                  summary: Monthly total quota
                  value:
                    status: true
                    data:
                      proxy_id: 12
                      shared_port: 20001
                      renew_date: 1760781600000
                      quotas:
                        ALL:
                          limit_by: MONTHLY
                          quota_mb: 10240
                          used_bytes: 537290342
                          used_mb: 512.4
                          used_dl_mb: 480.1
                          used_ul_mb: 32.3
                          remaining_mb: 9727.6
                          last_reset: 1760781600000
                          next_reset: 1763460000000
                          seconds_until_reset: 86400
                      last_resets: {}
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    message: API Token invalid
                noInfo:
                  summary: No quota info
                  value:
                    status: false
                    message: Quota info not available
                licenseOff:
                  summary: No Selling Platform license
                  value:
                    status: false
                    msg: This function is available on Selling Platform license only. Please contact Administrator!
        "500":
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SellingRefusal"
              example:
                status: false
                message: An error occurred while processing the request
      x-errors:
        - msg: This function is available on Selling Platform license only. Please contact Administrator!
          meaning: The license does not include the Selling Platform.
          remedy: Upgrade the license.
        - msg: Token is required
          meaning: token is missing.
          remedy: Send the token.
        - msg: API Token invalid
          meaning: Token unknown or reset (in `message`).
          remedy: Ask the seller for the current link; tokens change when reset.
        - msg: Quota info not available
          meaning: The box could not read the proxy's quota.
          remedy: Retry; contact the seller.
        - msg: An error occurred while processing the request
          meaning: Unexpected error (HTTP 500).
          remedy: Retry; contact the seller.
      x-since: v20.9.38
  /sms/read:
    get:
      operationId: readSms
      tags:
        - SMS & USSD
      summary: Read the latest SMS messages received by the SIM of one slot
      description: "Use this to fetch verification codes or carrier messages. Returns personal data: sender numbers and message text. Both parameters are required; a missing one, or a modem that cannot be read, returns `status false` with an empty list. The Hub never relays this route; call the box directly."
      x-xproxy-safety: read
      x-stability: public
      x-hub: denied
      security:
        - basicAuth: []
      parameters:
        - name: position
          in: query
          required: true
          description: Slot number, starting at 1.
          schema:
            type: integer
        - name: limit
          in: query
          required: true
          description: Maximum number of messages.
          schema:
            type: integer
      responses:
        "200":
          description: Messages, or `status false` with an empty list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  data:
                    oneOf:
                      - type: object
                        properties:
                          content:
                            type: array
                            items:
                              $ref: "#/components/schemas/SmsUssdMessage"
                      - type: array
                        maxItems: 0
              examples:
                ok:
                  summary: Messages (hand-written)
                  value:
                    status: true
                    data:
                      content:
                        - index: 1
                          phone: "+15550100"
                          date: 2026-11-17 08:00:00
                          content: Your code is 123456
                failed:
                  summary: Missing parameter or read error
                  value:
                    status: false
                    data: []
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /sms/send:
    post:
      operationId: sendSms
      tags:
        - SMS & USSD
      summary: Send an SMS from the SIM of one slot
      description: Use this to send one text message. Needs the SMS/USSD licence feature. Sending costs carrier credit and cannot be undone. Returns `Sent failed!` when the modem refuses or a field is missing. The Hub never relays this route.
      x-xproxy-safety: destructive
      x-stability: public
      x-hub: denied
      x-agent-note: Sending is irreversible and may cost money. Ask the user to confirm the number and text for every message; never loop over many numbers without explicit approval.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - position
                - phone
                - message
              properties:
                position:
                  type: integer
                phone:
                  type: string
                message:
                  type: string
            example:
              position: 1
              phone: "+15550100"
              message: Hello
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Sent
                  value:
                    status: true
                    msg: Sent successfully!
                failed:
                  summary: Not sent
                  value:
                    status: false
                    msg: Sent failed!
                upgrade:
                  summary: Feature not licensed
                  value:
                    status: false
                    msg: need_upgrade
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: need_upgrade
          meaning: The licence has no SMS/USSD feature.
          remedy: Upgrade the plan.
        - msg: Sent failed!
          meaning: The modem did not send or a field is missing.
          remedy: Check the SIM credit and the body; retry once.
      x-since: v20.8.0
  /sms/delete:
    post:
      operationId: deleteSms
      tags:
        - SMS & USSD
      summary: Delete SMS messages stored on the SIM or modem of one slot
      description: Use this to clear the inbox. Needs the SMS/USSD licence feature. Without `index` the modem's messages are deleted; Android phones accept `index` to delete one message. Deleted messages cannot be recovered. A body without `position` fails with HTTP 500. The Hub never relays this route.
      x-xproxy-safety: destructive
      x-stability: public
      x-hub: denied
      x-agent-note: Deletion is irreversible. Ask the user first; verify with /sms/read.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - position
              properties:
                position:
                  type: integer
                index:
                  type: integer
                  description: Message index (Android phones).
            example:
              position: 1
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Deleted
                  value:
                    status: true
                    msg: Deleted successfully!
                failed:
                  summary: Not deleted
                  value:
                    status: false
                    msg: Deleted failed!
                upgrade:
                  summary: Feature not licensed
                  value:
                    status: false
                    msg: need_upgrade
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: need_upgrade
          meaning: The licence has no SMS/USSD feature.
          remedy: Upgrade the plan.
        - msg: Deleted failed!
          meaning: The modem refused the delete.
          remedy: Retry; check the modem.
      x-since: v20.8.0
  /ussd/send:
    post:
      operationId: sendUssd
      tags:
        - SMS & USSD
      summary: Send a USSD code (for example a balance check) from the SIM of one slot
      description: Use this to run a carrier USSD code. Needs the SMS/USSD licence feature. Some codes change the subscription or spend credit and cannot be undone. `data` is the modem's reply (returns personal data such as balance or number); read later replies with /ussd/read. The Hub never relays this route.
      x-xproxy-safety: destructive
      x-stability: public
      x-hub: denied
      x-agent-note: USSD codes can buy plans or move credit irreversibly. Ask the user to confirm the exact code first.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - position
                - command
              properties:
                position:
                  type: integer
                command:
                  type: string
            example:
              position: 1
              command: "*100#"
      responses:
        "200":
          description: Modem reply or failure.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data: {}
              examples:
                ok:
                  summary: Reply (hand-written)
                  value:
                    status: true
                    data: Your balance is 10.25 USD
                failed:
                  summary: Not sent
                  value:
                    status: false
                    data: ""
                upgrade:
                  summary: Feature not licensed
                  value:
                    status: false
                    msg: need_upgrade
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: need_upgrade
          meaning: The licence has no SMS/USSD feature.
          remedy: Upgrade the plan.
      x-since: v20.8.0
  /ussd/read:
    get:
      operationId: readUssd
      tags:
        - SMS & USSD
      summary: Read the last USSD reply of one slot
      description: Use this after /ussd/send when the reply arrives later. Returns personal data (balance, number). A missing or non-numeric position returns `status false`. The Hub never relays this route.
      x-xproxy-safety: read
      x-stability: public
      x-hub: denied
      security:
        - basicAuth: []
      parameters:
        - name: position
          in: query
          required: true
          description: Slot number, starting at 1.
          schema:
            type: integer
      responses:
        "200":
          description: Reply or failure.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  data:
                    oneOf:
                      - type: object
                        properties:
                          content: {}
                      - type: string
              examples:
                ok:
                  summary: Reply (hand-written)
                  value:
                    status: true
                    data:
                      content: Your balance is 10.25 USD
                failed:
                  summary: Bad position or read error
                  value:
                    status: false
                    data: ""
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /v2/release_info:
    get:
      operationId: getReleaseInfo
      tags:
        - Software
      summary: Look up the latest (or a given) XProxy release for this box's architecture
      description: Use this before updating to see which build would be installed. The box asks the xproxy.io release server for its own CPU architecture; with `version` it looks up that version, otherwise the latest public build (dev builds when `install_branch` is dev). Nothing is installed. Network or server errors return `status false` with the reason.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Always public on the box (no login is checked).
      security:
        - basicAuth: []
        - {}
      parameters:
        - name: install_branch
          in: query
          description: prod (default behaviour) or dev.
          schema:
            type: string
        - name: version
          in: query
          description: Version such as v21.3.4 or 21.3.4, or a build number such as 26.1101.1200.
          schema:
            type: string
      responses:
        "200":
          description: Release details or an error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: object
                    additionalProperties: true
                    properties:
                      branch:
                        type: string
                        enum:
                          - prod
                          - dev
                      is_prod:
                        type: boolean
                      img_version:
                        type: string
                      img_build:
                        type: string
                      img_url:
                        type: string
                      img_arch:
                        type: string
                      binary_parts:
                        type:
                          - integer
                          - string
                          - "null"
                      build_date:
                        type: string
              examples:
                ok:
                  summary: Latest release
                  value:
                    status: true
                    data:
                      branch: prod
                      is_prod: true
                      img_version: v21.3.4
                      img_build: 26.1101.1200
                      img_url: https://media1.xproxy.io/releases/xproxy_example
                      img_arch: amd64
                      binary_parts: 1
                      build_date: 2026-11-01 12:00:00
                notFound:
                  summary: Unknown version
                  value:
                    status: false
                    msg: Version not found. Please contact support
                offline:
                  summary: Release server unreachable
                  value:
                    status: false
                    msg: release info unavailable
      x-errors:
        - msg: Version not found. Please contact support
          meaning: No build matches the version or build number for this architecture.
          remedy: Check the version string.
          origin: upstream
        - msg: release info unavailable
          meaning: The release server could not be reached or answered no JSON.
          remedy: Check the box internet connection and retry.
      x-since: v20.8.0
  /v2/updater_new_version:
    get:
      operationId: startSoftwareUpdate
      tags:
        - Software
      summary: Start updating the box software to the latest or a given version
      description: Use this only to install new software. Despite being a GET, it downloads and runs the installer in the background; the panel and proxies restart when it finishes. With `version` the version is first checked against the release server and refused if not found. Returns `scheduled` when started, `updating` when an update is already running. Follow progress with /v2/updater_new_version_status.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Never call without explicit user confirmation. The box restarts and all proxies drop during the update. Verify with /v2/updater_new_version_status until updating is false, then /system_information for the version.
      security:
        - basicAuth: []
      parameters:
        - name: version
          in: query
          description: Target version (v21.3.4 or 21.3.4); default latest.
          schema:
            type: string
        - name: debug
          in: query
          description: 1 or true writes a verbose installer log.
          schema:
            type: string
        - name: verbose
          in: query
          description: Same as debug.
          schema:
            type: string
      responses:
        "200":
          description: Update state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type:
                      - string
                      - boolean
                    description: scheduled, updating, or false with msg.
                  msg:
                    type: string
              examples:
                scheduled:
                  summary: Update started
                  value:
                    status: scheduled
                running:
                  summary: Already updating
                  value:
                    status: updating
                notFound:
                  summary: Unknown version
                  value:
                    status: false
                    msg: Version not found. Please contact support
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Version not found. Please contact support
          meaning: The requested version does not exist for this box.
          remedy: Use a version from /v2/release_info.
          origin: upstream
        - msg: release info unavailable
          meaning: The release server could not be reached to check the version.
          remedy: Retry later.
        - msg: Requested version not found
          meaning: The version check failed.
          remedy: Check the version string and retry.
      x-since: v20.8.0
  /v2/updater_new_version_status:
    get:
      operationId: getSoftwareUpdateStatus
      tags:
        - Software
      summary: Follow the progress of a running software update or rollback
      description: Use this to poll an update. `update_log` is the installer log so far; `updating` turns false when the installer is no longer running. On an internal error it answers an empty log and false.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Always public on the box (no login is checked).
      security:
        - basicAuth: []
        - {}
      responses:
        "200":
          description: Update progress.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      update_log:
                        type: string
                      updating:
                        type: boolean
              example:
                data:
                  update_log: |-
                    Downloading installer...
                    Installing v21.3.4...
                  updating: true
      x-since: v20.8.0
  /v2/updater_stop:
    post:
      operationId: stopSoftwareUpdate
      tags:
        - Software
      summary: Abort a running software update
      description: Use this to stop an update that hangs. It kills the installer download and installer processes and writes an abort line into the update log. Stopping in the middle of installing can leave the box between versions. Takes no body.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Never call without explicit user confirmation; aborting an install can break the box. Verify with /v2/updater_new_version_status.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
              examples:
                ok:
                  summary: Stopped
                  value:
                    status: true
                failed:
                  summary: Kill failed
                  value:
                    status: false
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /v2/rollback_version:
    post:
      operationId: rollbackSoftwareVersion
      tags:
        - Software
      summary: Reinstall an earlier software build (rollback)
      description: Use this to go back to a previous build, for example one listed in `history_versions` of /system_information. The installer runs in the background with the given old build version; the panel and proxies restart. Returns `scheduled` when started or `updating` when an update is already running.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Never call without explicit user confirmation. The box restarts and all proxies drop. Verify with /v2/updater_new_version_status and then the version in /system_information.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - obv
              properties:
                obv:
                  type: string
                  description: Old build version to install.
            example:
              obv: 26.1001.1200
      responses:
        "200":
          description: Rollback state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type:
                      - string
                      - boolean
                  msg:
                    type: string
              examples:
                scheduled:
                  summary: Rollback started
                  value:
                    status: scheduled
                running:
                  summary: Already updating
                  value:
                    status: updating
                missing:
                  summary: No obv
                  value:
                    status: false
                    msg: "Missing required parameter: obv"
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: "Missing required parameter: obv"
          meaning: The body has no obv.
          remedy: Send the old build version.
      x-since: v20.8.0
  /v2/stats/uptime_stats:
    get:
      operationId: getUptimeStats
      tags:
        - Stats & logs
      summary: Read per-10-minute uptime of one slot for each day in a range
      description: Use this to draw an uptime chart. The range may span at most about 3 months (93 days). `data` is keyed by the epoch second of each day, walking back from `end_date` in 24-hour steps; each day has 144 ten-minute buckets with status 1 (up), 0 (down) or null (no data).
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      parameters:
        - name: position
          in: query
          required: true
          schema:
            type: integer
        - name: start_date
          in: query
          required: true
          description: Epoch seconds.
          schema:
            type: integer
        - name: end_date
          in: query
          required: true
          description: Epoch seconds.
          schema:
            type: integer
      responses:
        "200":
          description: Uptime buckets or an error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  date:
                    type: integer
                    description: Echo of start_date.
                  data:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: object
                        properties:
                          time:
                            type: string
                            description: Local time of the bucket (hh:mm).
                          status:
                            type:
                              - integer
                              - "null"
                            enum:
                              - 1
                              - 0
                              - null
              examples:
                ok:
                  summary: One day (shortened)
                  value:
                    status: true
                    date: 1763337600
                    data:
                      "1763337600":
                        - time: 00:00
                          status: 1
                        - time: 00:10
                          status: 0
                        - time: 00:20
                          status: null
                missing:
                  summary: Missing parameter
                  value:
                    status: false
                    msg: position, start_date and end_date are required
                tooLong:
                  summary: Range too long
                  value:
                    status: false
                    msg: Please select date range is not over than 3 months!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: position, start_date and end_date are required
          meaning: A parameter is missing or not an integer.
          remedy: Send all three as integers.
        - msg: Please select date range is not over than 3 months!
          meaning: The range is 93 days or more.
          remedy: Shorten the range.
        - msg: Have an error during request! Contact administrator!
          meaning: The database query failed.
          remedy: Retry; check the box logs.
      x-since: v20.8.0
  /v2/rotation_history_analysis:
    get:
      operationId: getRotationHistoryAnalysis
      tags:
        - Stats & logs
      summary: Summarise rotations of one slot in a range (success rate, unique IPs, average time)
      description: Use this to judge rotation quality of a slot. Counts success, failed and duplicated rotations, the average rotation time in seconds, and lists each distinct IPv4 with how often it was seen (least seen first).
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      parameters:
        - name: position
          in: query
          required: true
          schema:
            type: integer
        - name: start_date
          in: query
          required: true
          description: Epoch seconds.
          schema:
            type: integer
        - name: end_date
          in: query
          required: true
          description: Epoch seconds.
          schema:
            type: integer
      responses:
        "200":
          description: Analysis or an error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: object
                    properties:
                      total_items:
                        type: integer
                      total_success:
                        type: integer
                      total_failed:
                        type: integer
                      total_duplicated:
                        type: integer
                      avg_rotation_time:
                        type:
                          - number
                          - "null"
                      total_unique_ip:
                        type: integer
                      unique_items:
                        type: array
                        items:
                          type: object
                          properties:
                            pos:
                              type: integer
                            current_ip4:
                              type:
                                - string
                                - "null"
                            current_ip6:
                              type:
                                - string
                                - "null"
                            occurrences:
                              type: integer
              examples:
                ok:
                  summary: Analysis
                  value:
                    data:
                      total_items: 3
                      total_success: 2
                      total_failed: 0
                      total_duplicated: 1
                      avg_rotation_time: 8.4
                      total_unique_ip: 2
                      unique_items:
                        - pos: 1
                          current_ip4: 203.0.113.45
                          current_ip6: null
                          occurrences: 1
                        - pos: 1
                          current_ip4: 203.0.113.46
                          current_ip6: 2001:db8::46
                          occurrences: 2
                error:
                  summary: Bad parameters
                  value:
                    status: false
                    msg: Have an error during request! Contact administrator!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Have an error during request! Contact administrator!
          meaning: A parameter is missing or not a number or the query failed.
          remedy: Send integer position and epoch-second dates.
      x-since: v20.8.0
  /v2/proxy_log:
    get:
      operationId: getProxyLog
      tags:
        - Stats & logs
      summary: Read recent proxy access log lines with filters
      description: "Use this to see which clients went where through the proxies, newest first. Reads back through rotated log files until `lines` entries match (default 20, at most 1000). Filters combine: position and port accept repeated values (position[]=1 or position=1), client_ip, client_username, target_host and method match partially, error_code matches exactly or `error` for any non-zero code, log_type is MAIN, SELL or GROUP; start_time/end_time are epoch seconds. Returns client IPs, usernames and visited hosts (personal data)."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      parameters:
        - name: lines
          in: query
          schema:
            type: integer
            default: 20
            maximum: 1000
        - name: filter_log
          in: query
          description: Free-text filter on the raw line.
          schema:
            type: string
        - name: position[]
          in: query
          schema:
            type: array
            items:
              type: integer
        - name: port[]
          in: query
          schema:
            type: array
            items:
              type: integer
        - name: client_ip
          in: query
          schema:
            type: string
        - name: client_username
          in: query
          schema:
            type: string
        - name: target_host
          in: query
          schema:
            type: string
        - name: method
          in: query
          schema:
            type: string
        - name: error_code
          in: query
          schema:
            type: string
        - name: log_type
          in: query
          schema:
            type: string
            enum:
              - MAIN
              - SELL
              - GROUP
        - name: start_time
          in: query
          schema:
            type: integer
        - name: end_time
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: Matching log entries; on a read error the lists are empty.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: object
                    properties:
                      content:
                        type: string
                        description: Raw lines joined by new lines.
                      parsed:
                        type: array
                        items:
                          type: object
                          additionalProperties: true
                      total_filtered:
                        type: integer
                      total_parsed:
                        type: integer
              example:
                status: true
                data:
                  content: "2026-11-17 08:00:00 [MAIN] [POS:1] [:4001] [CLIENT-user1-192.0.2.50:51000] access example.com:443 CONNECT_example.com:443_HTTP/1.1 ErrC: 00000 RBytes:5120 - SBytes:830"
                  parsed:
                    - raw: "2026-11-17 08:00:00 [MAIN] [POS:1] [:4001] [CLIENT-user1-192.0.2.50:51000] access example.com:443 CONNECT_example.com:443_HTTP/1.1 ErrC: 00000 RBytes:5120 - SBytes:830"
                      timestamp: 2026-11-17 08:00:00
                      log_type: MAIN
                      position: 1
                      port: 4001
                      client_username: user1
                      client_ip: 192.0.2.50
                      client_port: 51000
                      target_host: example.com
                      target_port: 443
                      method: CONNECT
                      error_code: "00000"
                      bytes_received: 5120
                      bytes_sent: 830
                      is_error: false
                  total_filtered: 1
                  total_parsed: 1
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /v2/dev_logging:
    get:
      operationId: getDevLogging
      tags:
        - Stats & logs
      summary: Read developer logging on/off and the level of each controller logger
      description: Use this before changing log verbosity for debugging. Each logger shows its default and selected level.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      responses:
        "200":
          description: Logging state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: object
                    properties:
                      settings:
                        type: object
                        properties:
                          enabled:
                            type: boolean
                      loggers:
                        type: array
                        items:
                          type: object
                          properties:
                            logger_name:
                              type: string
                            default_level:
                              type: string
                            selected_level:
                              type: string
              examples:
                ok:
                  summary: State
                  value:
                    status: true
                    data:
                      settings:
                        enabled: false
                      loggers:
                        - logger_name: webapi_v2
                          default_level: INFO
                          selected_level: DEBUG
                failed:
                  summary: Load failed
                  value:
                    status: false
                    msg: Failed to load dev logging settings
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Failed to load dev logging settings
          meaning: The logging configuration could not be read.
          remedy: Retry; check the box logs.
      x-since: v20.9.50
    post:
      operationId: setDevLogging
      tags:
        - Stats & logs
      summary: Turn developer logging on or off and set logger levels
      description: Use this to raise log verbosity while debugging and to lower it afterwards. The body may be wrapped in `data`. Loggers without a name or level are skipped. Settings are saved and applied at once; verbose levels make logs grow quickly.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Ask the user first and switch it back off after debugging; verbose logging fills disk. Verify with GET /v2/dev_logging.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                settings:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                loggers:
                  type: array
                  items:
                    type: object
                    properties:
                      logger_name:
                        type: string
                      selected_level:
                        type: string
                        description: DEBUG, INFO, WARNING, ERROR (level is accepted too).
            example:
              settings:
                enabled: true
              loggers:
                - logger_name: webapi_v2
                  selected_level: DEBUG
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                    msg: Configuration successfully!
                failed:
                  summary: Not applied
                  value:
                    status: false
                    msg: Failed to apply configuration
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Failed to apply configuration
          meaning: Saving or applying the levels failed.
          remedy: Check logger names and levels.
        - msg: Configuration failed!
          meaning: Unexpected error.
          remedy: Retry; check the box logs.
      x-since: v20.9.50
  /get_label_list:
    get:
      operationId: getLabelList
      tags:
        - System settings
      summary: List the CPE device labels configured on the box
      description: Use this to see which CPE labels (virtual LAN interfaces) exist before adding or deleting one.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      responses:
        "200":
          description: All labels.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/CpeLabel"
              example:
                status: true
                data:
                  - label: 14
                    manu: XCPE
                    address: 192.0.2.14
                    vlan: 0
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /add_new_label:
    post:
      operationId: addLabel
      tags:
        - System settings
      summary: Add a CPE device label and bring up its virtual interface
      description: Use this to register a CPE device. Without VLAN the label must be below 100. The interface is created at once. A missing field or a non-numeric label fails with HTTP 500.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Creates a network interface on the box. Ask the user first; verify with GET /get_label_list.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - label
                - manu
                - address
                - vlan
              properties:
                label:
                  type: integer
                manu:
                  type: string
                address:
                  type: string
                vlan:
                  type: boolean
            example:
              label: 14
              manu: XCPE
              address: 192.0.2.14
              vlan: false
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Added
                  value:
                    status: true
                    msg: Configuration successfully!
                range:
                  summary: Label too high without VLAN
                  value:
                    status: false
                    msg: Label must be less than 100 when VLAN is disabled!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Label must be less than 100 when VLAN is disabled!
          meaning: Label is 100 or more and vlan is false.
          remedy: Use a smaller label or enable VLAN.
        - msg: Label already exist!
          meaning: Meant to refuse duplicates; the current check never matches so duplicates are not detected.
          remedy: Check GET /get_label_list before adding.
      x-since: v20.8.0
  /delete_label:
    post:
      operationId: deleteLabel
      tags:
        - System settings
      summary: Delete a CPE device label and take down its interface
      description: Use this to remove a CPE label. The label must match the stored value exactly (same type as in /get_label_list).
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Removes a network interface that CPE traffic may use. Ask the user first; verify with GET /get_label_list.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - label
              properties:
                label:
                  type:
                    - integer
                    - string
            example:
              label: 14
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Deleted
                  value:
                    status: true
                    msg: Configuration successfully!
                missing:
                  summary: Unknown label
                  value:
                    status: false
                    msg: Label not exist!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Label not exist!
          meaning: No stored label equals the value sent.
          remedy: Copy the label from GET /get_label_list.
      x-since: v20.8.0
  /get_system_settings:
    get:
      operationId: getSystemSettings
      tags:
        - System settings
      summary: Read every system setting of the box (timezone, network, login, DDNS, telemetry, recovery)
      description: "Use this to show or back up the system settings page. Returns secrets: the dashboard password, the DuckDNS token and the SigNoz ingestion key, in clear text. Only trusted tools should call it; never log or display the response. `timezones` lists every timezone name the box accepts."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      responses:
        "200":
          description: All system settings (hand-written example; the timezone list is shortened).
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: object
                    additionalProperties: true
                    properties:
                      timezones:
                        type: array
                        items:
                          type: string
                      current_timezone:
                        type: string
                      static_ip:
                        type: object
                        properties:
                          ip:
                            type: string
                          netmask:
                            type: string
                          gateway:
                            type: string
                      dashboard_auth:
                        type: object
                        additionalProperties: true
                      duckdns:
                        type: object
                        properties:
                          ddns_token:
                            type: string
                          ddns_hostname:
                            type: string
                          ddns_log:
                            type: string
                      defaultDashboardPort:
                        type: integer
                      forceDHCPEnable:
                        type: boolean
                      controller_log_retention_days:
                        type: integer
                      controller_log_max_mb:
                        type: integer
                      watch_dog:
                        type: object
                        properties:
                          enable:
                            type: boolean
                          time:
                            type:
                              - integer
                              - "null"
                      bridgingServiceConfig:
                        type: string
                        description: Bridged services one per line.
                      ttl:
                        type: object
                        properties:
                          enable:
                            type: boolean
                          number:
                            type:
                              - integer
                              - "null"
                      telemetry:
                        type: object
                        additionalProperties: true
                      system_recovery:
                        type: object
                        additionalProperties: true
              example:
                status: true
                data:
                  timezones:
                    - UTC
                    - Europe/Berlin
                    - Asia/Ho_Chi_Minh
                  current_timezone: UTC
                  static_ip:
                    ip: 192.0.2.20
                    netmask: 255.255.255.0
                    gateway: 192.0.2.1
                  dashboard_auth:
                    enableDashAuth: true
                    forceDashApiLegacyAuth: false
                    dashboardUser: admin
                    dashboardPass: YOUR_DASHBOARD_PASSWORD
                    enableIPAuth: false
                    forceLocalAuthen: false
                    allowTailscaleNoAuth: false
                    ipList: 203.0.113.0/24
                    dashboardDomainOnly: false
                  duckdns:
                    ddns_token: YOUR_DDNS_TOKEN
                    ddns_hostname: my-box
                    ddns_log: OK
                  defaultDashboardPort: 80
                  forceDHCPEnable: true
                  controller_log_retention_days: 7
                  controller_log_max_mb: 500
                  watch_dog:
                    enable: false
                    time: 10
                  bridgingServiceConfig: ""
                  ttl:
                    enable: false
                    number: 64
                  telemetry:
                    enabled: false
                    provider: signoz
                    service_name: xproxy-logs
                    log_path: /etc/xproxy/logs
                    signoz:
                      endpoint: ""
                      ingestion_key: YOUR_INGESTION_KEY
                    graylog:
                      endpoint: ""
                      host: xproxy-server
                      timeout: 10
                  system_recovery:
                    fix_pci_usb_controller: true
                    dongle_dhcp_fix: true
                    dhcp_fix_backoff_enabled: true
                    dhcp_fix_backoff_base_seconds: 60
                    dhcp_fix_backoff_max_seconds: 3600
                    dhcp_fix_backoff_factor: 2
                    dhcp_fix_link_dead_seconds: 90
                    dhcp_fix_web_dead_minutes: 10
                    dhcp_fix_no_ip_minutes: 3
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /update_system_settings:
    post:
      operationId: updateSystemSettings
      tags:
        - System settings
      summary: Change one section of the system settings (selected by type)
      description: "Use this to save one settings section. `type` picks the section and `data` carries the same shape GET /get_system_settings returns for it. Side effects by type: current_timezone restarts the panel (msg success_app_restart); static_ip reboots the box (success_app_reboot) and can make it unreachable on a wrong address; dashboard_port restarts the panel on the new port; dashboard_auth replaces the dashboard login and whitelist at once (and on the VPS when forwarding is on); duckdns tests the token before saving; telemetry restarts log shipping; system_recovery updates the dongle and USB recovery service. Other types: force_dhcp, controller_log_retention, watch_dog, bridging_service, ttl, gui_theme. An unknown type, or a timezone change whose link command fails, still answers `status true`. The request may carry secrets (dashboard password, DDNS token, ingestion key)."
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Never call without explicit user confirmation for the section and values. static_ip, timezone and dashboard_port reboot or restart the box; a wrong dashboard_auth or static_ip can lock everyone out. Verify with GET /get_system_settings after the box is back.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - data
              properties:
                type:
                  type: string
                  enum:
                    - current_timezone
                    - static_ip
                    - dashboard_auth
                    - duckdns
                    - dashboard_port
                    - force_dhcp
                    - controller_log_retention
                    - watch_dog
                    - bridging_service
                    - ttl
                    - telemetry
                    - system_recovery
                    - gui_theme
                data:
                  type: object
                  additionalProperties: true
                  description: Section payload keyed like the GET response.
            examples:
              timezone:
                summary: Change timezone
                value:
                  type: current_timezone
                  data:
                    current_timezone: Europe/Berlin
              watchdog:
                summary: Enable watchdog
                value:
                  type: watch_dog
                  data:
                    watch_dog:
                      enable: true
                      time: 10
              ttl:
                summary: Set TTL
                value:
                  type: ttl
                  data:
                    ttl:
                      enable: true
                      number: 64
      responses:
        "200":
          description: Result of the section save.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                    msg: Configuration successfully!
                restart:
                  summary: Panel restarts
                  value:
                    status: true
                    msg: success_app_restart
                reboot:
                  summary: Box reboots
                  value:
                    status: true
                    msg: success_app_reboot
                badTz:
                  summary: Invalid timezone
                  value:
                    status: false
                    msg: Invalid timezone!
                failed:
                  summary: Bad body
                  value:
                    status: false
                    msg: Configuration failed!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: success_app_restart
          meaning: Saved; the panel restarts now.
          remedy: Wait about a minute then reconnect.
        - msg: success_app_reboot
          meaning: Static IP saved; the box reboots now.
          remedy: Reconnect on the new address after the reboot.
        - msg: Invalid timezone!
          meaning: The timezone is not a known name.
          remedy: Use a value from timezones.
        - msg: Static IP invalid. Please correct and try again!
          meaning: Bad static IP.
          remedy: Send a valid IPv4.
        - msg: Gateway IP invalid. Please correct and try again!
          meaning: Bad gateway.
          remedy: Send a valid IPv4.
        - msg: Netmask invalid. Please correct and try again!
          meaning: Bad netmask.
          remedy: Send a dotted mask or a prefix up to 32.
        - msg: Static IP is same with Gateway IP. Please change to another!
          meaning: IP equals gateway.
          remedy: Use a different address.
        - msg: does not same subnet
          meaning: The static IP is not in the /24 of the gateway (message starts with the two addresses).
          remedy: Use an address in the gateway subnet.
        - msg: Need enable Dashboard Authentication when filled Username/Password!
          meaning: User or password sent with login disabled.
          remedy: Enable login or clear the fields.
        - msg: Need fill Username/Password when enabled Dashboard Authentication!
          meaning: Login enabled without credentials.
          remedy: Send both.
        - msg: Need enable Password Authentication when Whitelist IP Authentication enabled!
          meaning: Whitelist needs password login.
          remedy: Enable password login.
        - msg: Need enable Password Authentication when Authentication in LAN enabled!
          meaning: LAN auth needs password login.
          remedy: Enable password login.
        - msg: Need enable Password Authentication when Tailscale devices may skip the login!
          meaning: Tailscale bypass needs password login.
          remedy: Enable password login.
        - msg: Test and setting successfully!
          meaning: DuckDNS token works and is saved.
          remedy: None.
        - msg: Domain or Token invalid!
          meaning: DuckDNS rejected the hostname or token.
          remedy: Check both in DuckDNS.
        - msg: Please choice the port in the range (80-65535)
          meaning: Dashboard port out of range.
          remedy: Use 80-65535.
        - msg: Please set watchdog time
          meaning: Watchdog enabled without time.
          remedy: Send a time.
        - msg: TTL must be a number between 1 and 255!
          meaning: Bad TTL.
          remedy: Send 1-255.
        - msg: Service name is required
          meaning: Telemetry enabled without service name.
          remedy: Send service_name.
        - msg: Log path is required
          meaning: Telemetry enabled without log path.
          remedy: Send log_path.
        - msg: SigNoz endpoint and ingestion key are required
          meaning: SigNoz chosen without endpoint or key.
          remedy: Send both.
        - msg: Graylog endpoint is required
          meaning: Graylog chosen without endpoint.
          remedy: Send the endpoint.
        - msg: Failed to initialize
          meaning: Telemetry saved but the provider did not start (message ends with the provider).
          remedy: Check endpoint and key.
        - msg: Invalid value for
          meaning: A recovery field has the wrong type (message ends with the field).
          remedy: Send the right type.
        - msg: Backoff base interval must be at least 5 seconds
          meaning: Recovery value out of range.
          remedy: Raise the value.
        - msg: Backoff max interval must be >= base interval
          meaning: Recovery value out of range.
          remedy: Fix the interval.
        - msg: Backoff factor must be at least 1
          meaning: Recovery value out of range.
          remedy: Raise the value.
        - msg: No response must be 30-86400 seconds
          meaning: Recovery value out of range.
          remedy: Use 30-86400.
        - msg: Web page down must be 0 (never) or 2-1440 minutes
          meaning: Recovery value out of range.
          remedy: Use 0 or 2-1440.
        - msg: No IP must be 1-1440 minutes
          meaning: Recovery value out of range.
          remedy: Use 1-1440.
        - msg: Failed to enable USB recovery service
          meaning: The recovery service did not start.
          remedy: Retry; check the box logs.
        - msg: Failed to apply system recovery setting
          meaning: Unexpected error while saving recovery.
          remedy: Retry; check the box logs.
        - msg: Theme saved!
          meaning: GUI theme saved.
          remedy: None.
        - msg: Configuration failed!
          meaning: type or data is missing or malformed.
          remedy: Send type and the section payload.
      x-since: v20.8.0
  /v2/get_monitor_time:
    get:
      operationId: getMonitorTime
      tags:
        - System settings
      summary: Read how often the VPS relay connection is checked
      description: Use this to read the VPS relay monitoring interval in seconds.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      security:
        - basicAuth: []
      responses:
        "200":
          description: Interval.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      monitor_time:
                        type:
                          - integer
                          - "null"
              example:
                status: true
                data:
                  monitor_time: 30
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /v2/set_monitor_time:
    post:
      operationId: setMonitorTime
      tags:
        - System settings
      summary: Change how often the VPS relay connection is checked
      description: Use this to set the VPS relay monitoring interval. The value must be greater than 5 seconds and applies at once. A missing or non-numeric value fails with HTTP 500.
      x-xproxy-safety: destructive
      x-stability: panel
      x-hub: approval
      x-agent-note: Changes VPS relay monitoring for all forwarded ports. Ask the user first; verify with GET /v2/get_monitor_time.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - monitor_time
              properties:
                monitor_time:
                  type: integer
                  minimum: 6
            example:
              monitor_time: 30
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                    msg: Configuration successfully!
                low:
                  summary: Too small
                  value:
                    status: false
                    msg: Configuration Failed! Please set monitoring time greater 5 seconds!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Configuration Failed! Please set monitoring time greater 5 seconds!
          meaning: Value is 5 or less.
          remedy: Send 6 or more.
      x-since: v20.8.0
  /xproxy_reboot:
    post:
      operationId: rebootSystem
      tags:
        - System settings
      summary: Reboot the whole box (operating system)
      description: Use this only when a full restart is needed. The box answers first, then reboots; every proxy and the panel are offline for one to a few minutes. Takes no body.
      x-xproxy-safety: destructive
      x-stability: public
      x-hub: approval
      x-agent-note: Never call without explicit user confirmation. All proxies drop. Verify by polling /health/ready until core_ready is true.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Reboot scheduled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              example:
                status: true
                msg: Configuration successfully!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /xproxy_soft_reboot:
    post:
      operationId: restartPanel
      tags:
        - System settings
      summary: Restart the XProxy service without rebooting the operating system
      description: Use this to reload the controller after a stuck state. The box answers first, then restarts the XProxy service; proxies and the panel drop for about a minute. Takes no body.
      x-xproxy-safety: destructive
      x-stability: public
      x-hub: approval
      x-agent-note: Never call without explicit user confirmation. All proxies drop briefly. Verify by polling /health/ready until core_ready is true.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Restart scheduled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              example:
                status: true
                msg: Configuration successfully!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /{token}/status:
    get:
      operationId: getStatusWithPortToken
      tags:
        - Token links
      summary: Check a proxy's status with its per-port token link
      description: Use this to give an end user a status link for one proxy without sharing the dashboard login. Works only while per-port authentication (`port_auth_config`) is on. The token must belong to the port in `proxy`. The answer is the same as `/status`.
      x-xproxy-safety: read
      x-stability: public
      x-hub: denied
      x-auth-note: Authenticated only by the token in the path; the dashboard login and "Basic auth for all API" do not apply. Refusals answer HTTP 401 with a `message`.
      security:
        - {}
      parameters:
        - name: token
          in: path
          required: true
          x-secret: true
          description: "Per-port token of the proxy, shown in the panel when per-port authentication is on. Treat it like a password: anyone with the link can use it."
          schema:
            type: string
          example: YOUR_PORT_TOKEN
        - $ref: "#/components/parameters/proxyQuery"
      responses:
        "200":
          description: Slot state.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ModemStatus"
                  - $ref: "#/components/schemas/StatusMsg"
              example:
                status: true
                msg: MODEM_READY
                public_ip: 203.0.113.45
                public_ip_v6: null
                last_public_ip: 203.0.113.44
        "401":
          $ref: "#/components/responses/TokenUnauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Not support!
          meaning: Per-port authentication is off on this box.
          remedy: Turn on per-port authentication in the proxy settings.
        - msg: Unauthorized!
          meaning: The token does not match this port.
          remedy: Copy the link again from the panel.
      x-since: v20.8.0
  /{token}/reset:
    get:
      operationId: rotateIpWithPortToken
      tags:
        - Token links
      summary: Get a new public IP for a proxy with its per-port token link
      description: Use this to let an end user rotate one proxy without the dashboard login. Works only while per-port authentication is on. Refuses with HTTP 401 `reset_too_much` when the last rotation was less than the minimum interval (5 seconds by default) ago; otherwise behaves like `/reset`.
      x-xproxy-safety: action
      x-agent-note: Changes the proxy's public IP and drops its connections for 10-60 seconds. Do not loop; a 401 reset_too_much means wait.
      x-stability: public
      x-hub: denied
      x-auth-note: Authenticated only by the token in the path; the dashboard login and "Basic auth for all API" do not apply. Refusals answer HTTP 401 with a `message`.
      security:
        - {}
      parameters:
        - name: token
          in: path
          required: true
          x-secret: true
          description: "Per-port token of the proxy, shown in the panel when per-port authentication is on. Treat it like a password: anyone with the link can use it."
          schema:
            type: string
          example: YOUR_PORT_TOKEN
        - $ref: "#/components/parameters/proxyQuery"
      responses:
        "200":
          description: Rotation accepted or refused (same codes as /reset).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                sent:
                  summary: Rotation started
                  value:
                    status: true
                    msg: command_sent
                busy:
                  summary: Rotation already running
                  value:
                    status: false
                    msg: modem_resetting
        "401":
          description: Per-port authentication off, wrong token, port without a modem, or rotated too recently.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenUnauthorized"
              examples:
                notSupported:
                  summary: Per-port authentication off
                  value:
                    message: Not support!
                badToken:
                  summary: Wrong token
                  value:
                    message: Unauthorized!
                wrongPort:
                  summary: No modem on this port
                  value:
                    message: Wrong port!
                tooSoon:
                  summary: Rotated too recently
                  value:
                    message: reset_too_much
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Not support!
          meaning: Per-port authentication is off on this box.
          remedy: Turn on per-port authentication in the proxy settings.
        - msg: Unauthorized!
          meaning: The token does not match this port.
          remedy: Copy the link again from the panel.
        - msg: Wrong port!
          meaning: No modem uses the port in proxy.
          remedy: Check the proxy value.
        - msg: reset_too_much
          meaning: The last rotation was less than the minimum interval ago.
          remedy: Wait a few seconds and retry.
      x-since: v20.8.0
  /{token}/reboot_usb:
    get:
      operationId: rebootDongleWithPortToken
      tags:
        - Token links
      summary: Reboot the modem behind a proxy with its per-port token link
      description: Use this to let an end user reboot the modem of one proxy. Works only while per-port authentication is on. Unlike `/reboot_usb` there is no license check. Same result messages as `/reboot_usb`.
      x-xproxy-safety: action
      x-agent-note: Takes the proxy offline for up to a few minutes. Use only when the modem is offline or broken.
      x-stability: public
      x-hub: denied
      x-auth-note: Authenticated only by the token in the path; the dashboard login and "Basic auth for all API" do not apply. Refusals answer HTTP 401 with a `message`.
      security:
        - {}
      parameters:
        - name: token
          in: path
          required: true
          x-secret: true
          description: "Per-port token of the proxy, shown in the panel when per-port authentication is on. Treat it like a password: anyone with the link can use it."
          schema:
            type: string
          example: YOUR_PORT_TOKEN
        - $ref: "#/components/parameters/proxyQuery"
      responses:
        "200":
          description: Reboot result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                done:
                  summary: Reboot sent
                  value:
                    status: true
                    msg: Reboot modem done!
                notFound:
                  summary: Unknown port
                  value:
                    status: false
                    msg: Not found!
        "401":
          $ref: "#/components/responses/TokenUnauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: Not support!
          meaning: Per-port authentication is off on this box.
          remedy: Turn on per-port authentication in the proxy settings.
        - msg: Unauthorized!
          meaning: The token does not match this port.
          remedy: Copy the link again from the panel.
      x-since: v20.8.0
  /{token}/reset_group:
    get:
      operationId: rotateIpGroupWithToken
      tags:
        - Token links
      summary: Get new public IPs for a proxy group with its group token link
      description: "Use this to let an end user rotate a whole proxy group. `proxy` is `HOST:PORT` of the group's primary port; the token is the group token shown with the group in the panel. Every slot of the group is rotated in parallel and the answer is `status: true` once the requests are sent. A port that is no group's primary port rotates nothing and still answers `status: true`. This link does not depend on per-port authentication."
      x-xproxy-safety: action
      x-agent-note: Rotates every proxy in the group and drops their connections. The answer does not report per-slot results; poll each proxy's status.
      x-stability: public
      x-hub: denied
      x-auth-note: Authenticated only by the group token in the path; the dashboard login does not apply.
      security:
        - {}
      parameters:
        - name: token
          in: path
          required: true
          x-secret: true
          description: Group token of the proxy group, shown in the panel. Treat it like a password.
          schema:
            type: string
          example: YOUR_GROUP_TOKEN
        - name: proxy
          in: query
          required: true
          description: HOST:PORT of the group's primary port.
          schema:
            type: string
          example: 192.0.2.10:4001
      responses:
        "200":
          description: Requests sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
              example:
                status: true
        "401":
          description: The token does not match the group.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenUnauthorized"
              example:
                message: Unauthorized!
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.8.0
  /api/v1/info_list:
    get:
      operationId: getInfoList
      tags:
        - Proxies
      summary: List connected proxies with ports, public IPs and modem details
      description: Use this to discover which slots are online and which ports to use. Only slots whose modem has an active data connection are returned; empty or offline slots are left out. `total` counts all listed slots before paging. Paging applies only when both `page` and `limit` are valid integers.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: 'Always needs a trusted caller: loopback, a LAN address (unless "force auth for local" is on), a whitelisted IP, an allowed Tailscale address, or valid dashboard Basic credentials (checked only when dashboard authentication is enabled).'
      security:
        - basicAuth: []
        - {}
      parameters:
        - name: page
          in: query
          description: Page number, starting at 1. Ignored unless `limit` is also set.
          schema:
            type: integer
            minimum: 1
        - name: limit
          in: query
          description: Rows per page. Ignored unless `page` is also set.
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Connected slots.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - total
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/InfoListItem"
                  total:
                    type: integer
              example:
                data:
                  - position: 1
                    host: 192.0.2.10
                    proxy_port: 4001
                    proxy_port_v6: 6001
                    socks5_port: 5001
                    socks5_port_ipv6: 7001
                    vless_port: 10001
                    vless_port_v6: null
                    ss_port: 12001
                    ss_port_v6: null
                    public_ip: 203.0.113.45
                    public_ip_ipv6: 2001:db8::45
                    last_rotation: 1763370000.5
                    last_updated_ip: 1763370060.2
                    device_manufacture: HW-Hilink
                    device_imei: "490154203237518"
                    device_number: "+15550100"
                    device_ip: 192.0.2.101
                    device_rebooting: false
                    device_resetting: false
                    device_extra_info:
                      provider: Example Mobile
                total: 1
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /api/v1/proxy_list/{port_type}:
    get:
      operationId: getProxyListByType
      tags:
        - Proxies
      summary: Get a plain-text list of proxy addresses of one type, one per line
      description: Use this to import all online proxies into a tool that reads one proxy per line. Lists every slot with an active data connection as `HOST:PORT` for `proxy`, `socks5`, `proxy_ipv6` and `socks5_ipv6`. `vless` and `vless_ipv6` return VLESS REALITY share links and `ss` returns Shadowsocks links; those lines appear only when the license includes the protocol and the slot has the port. An unknown type returns an empty body. The body is plain text even though the box labels it `text/html`.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: Always needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
        - {}
      parameters:
        - name: port_type
          in: path
          required: true
          description: Which port of each slot to list.
          schema:
            type: string
            enum:
              - proxy
              - socks5
              - proxy_ipv6
              - socks5_ipv6
              - vless
              - vless_ipv6
              - ss
          example: proxy
      responses:
        "200":
          description: One proxy per line, each line ending with a newline. Empty when no slot is online.
          content:
            text/html:
              schema:
                type: string
              examples:
                proxy:
                  summary: port_type proxy
                  value: |
                    192.0.2.10:4001
                    192.0.2.10:4002
                vless:
                  summary: port_type vless
                  value: |
                    vless://YOUR_UUID@192.0.2.10:10001?encryption=none&security=reality&sni=dl.google.com&fp=chrome&pbk=YOUR_PUBLIC_KEY&sid=YOUR_SHORT_ID&type=tcp&flow=xtls-rprx-vision#4001-1
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /api/v1/status/proxy/{proxy}:
    get:
      operationId: getStatusOfProxy
      tags:
        - Proxies
      summary: Check whether a proxy is online and read its public IP
      description: Use this to poll a proxy after a rotation until it reports `MODEM_READY` with the new IP. Looks the slot up by the port in `HOST:PORT`.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: 'Open by default: with "Basic auth for all API" (`api_auth_check`) off, anyone who can reach the box can call it. When it is on, the caller must be trusted (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or send dashboard Basic credentials, which are checked only when dashboard authentication (`dashboard_disable_auth` off) is enabled.'
      security:
        - basicAuth: []
        - {}
      parameters:
        - $ref: "#/components/parameters/proxyPath"
      responses:
        "200":
          description: Slot state, or `invalid_format_proxy` when the path is not `HOST:PORT`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ModemStatus"
                  - $ref: "#/components/schemas/StatusMsg"
              examples:
                ready:
                  summary: Online
                  value:
                    status: true
                    msg: MODEM_READY
                    public_ip: 203.0.113.45
                    public_ip_v6: 2001:db8::45
                    last_public_ip: 203.0.113.44
                resetting:
                  summary: Rotation in progress
                  value:
                    status: false
                    msg: MODEM_RESETTING
                notFound:
                  summary: No slot uses this port
                  value:
                    status: false
                    msg: MODEM_NOT_FOUND
                badFormat:
                  summary: Path is not HOST:PORT
                  value:
                    status: false
                    msg: invalid_format_proxy
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: MODEM_RESETTING
          meaning: A rotation is running on this slot.
          remedy: Poll again every few seconds.
        - msg: MODEM_DISCONNECTED
          meaning: The slot has no public IP (offline modem or empty slot).
          remedy: Check the modem in the panel; reboot it if it stays offline.
        - msg: MODEM_NOT_FOUND
          meaning: No slot matches the port or position.
          remedy: Use a port or position from /api/v1/info_list.
        - msg: COLLISION_IP
          meaning: The new IP equals the previous one (duplicate-IP detection on).
          remedy: Rotate again if you need a different IP.
        - msg: invalid_format_proxy
          meaning: The proxy value is not HOST:PORT.
          remedy: Send it as HOST:PORT, for example 192.0.2.10:4001.
      x-since: v20.8.0
  /api/v1/status/position/{position}:
    get:
      operationId: getStatusOfPosition
      tags:
        - Proxies
      summary: Check whether a slot is online and read its public IP
      description: Use this to poll a slot by its number after a rotation. An empty slot answers `MODEM_DISCONNECTED`; a number above the box's slot count answers `MODEM_NOT_FOUND`.
      x-xproxy-safety: read
      x-stability: public
      x-hub: approval
      x-auth-note: 'Open by default: with "Basic auth for all API" (`api_auth_check`) off, anyone who can reach the box can call it. When it is on, the caller must be trusted (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or send dashboard Basic credentials, which are checked only when dashboard authentication (`dashboard_disable_auth` off) is enabled.'
      security:
        - basicAuth: []
        - {}
      parameters:
        - $ref: "#/components/parameters/positionPath"
      responses:
        "200":
          description: Slot state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModemStatus"
              examples:
                ready:
                  summary: Online
                  value:
                    status: true
                    msg: MODEM_READY
                    public_ip: 203.0.113.45
                    public_ip_v6: null
                    last_public_ip: 203.0.113.44
                disconnected:
                  summary: Empty or offline slot (lab capture)
                  value:
                    status: false
                    msg: MODEM_DISCONNECTED
                notFound:
                  summary: Position above the slot count (lab capture)
                  value:
                    status: false
                    msg: MODEM_NOT_FOUND
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: MODEM_RESETTING
          meaning: A rotation is running on this slot.
          remedy: Poll again every few seconds.
        - msg: MODEM_DISCONNECTED
          meaning: The slot has no public IP (offline modem or empty slot).
          remedy: Check the modem in the panel; reboot it if it stays offline.
        - msg: MODEM_NOT_FOUND
          meaning: No slot matches the port or position.
          remedy: Use a port or position from /api/v1/info_list.
        - msg: COLLISION_IP
          meaning: The new IP equals the previous one (duplicate-IP detection on).
          remedy: Rotate again if you need a different IP.
        - msg: invalid_format_proxy
          meaning: The proxy value is not HOST:PORT.
          remedy: Send it as HOST:PORT, for example 192.0.2.10:4001.
      x-since: v20.8.0
  /api/v1/rotate_ip/proxy/{proxy}:
    get:
      operationId: rotateIpForProxy
      tags:
        - Rotation
      summary: Get a new public IP for one proxy
      description: "Use this to rotate the IP of the slot behind a proxy port. The call starts the rotation and returns at once; poll the status operation until it reports `MODEM_READY`. When a rotation delay is configured on the box, the answer is `status: true` with an empty `msg` and the rotation starts after the delay. For IPv6-multiple ports the IPv6 address is rotated."
      x-xproxy-safety: action
      x-agent-note: "Changes the public IP and drops open connections on this proxy for 10-60 seconds. Do not call it in a loop: the box refuses rotations closer than the minimum interval (reset_too_much). Check `status`, not the HTTP code. This is a GET, so never place it where a browser could prefetch it."
      x-stability: public
      x-hub: approval
      x-auth-note: 'Open by default: with "Basic auth for all API" (`api_auth_check`) off, anyone who can reach the box can call it. When it is on, the caller must be trusted (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or send dashboard Basic credentials, which are checked only when dashboard authentication (`dashboard_disable_auth` off) is enabled.'
      security:
        - basicAuth: []
        - {}
      parameters:
        - $ref: "#/components/parameters/proxyPath"
      responses:
        "200":
          description: Rotation accepted or refused.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                sent:
                  summary: Rotation started
                  value:
                    status: true
                    msg: command_sent
                delayed:
                  summary: Rotation delay configured
                  value:
                    status: true
                    msg: ""
                tooSoon:
                  summary: Too soon after the last rotation
                  value:
                    status: false
                    msg: reset_too_much
                notFound:
                  summary: Unknown port
                  value:
                    status: false
                    msg: slot_not_found
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: command_sent
          meaning: With status true, the rotation started. With status false, the modem did not accept the command.
          remedy: On status false wait a few seconds and check the slot status before retrying.
        - msg: modem_resetting
          meaning: A rotation is already running on this slot.
          remedy: Wait for MODEM_READY before rotating again.
        - msg: reset_too_much
          meaning: The last rotation was less than the minimum interval ago (5 seconds by default).
          remedy: Wait and retry.
        - msg: modem_disconnected
          meaning: The modem type cannot rotate (not detected as a router or AT stick).
          remedy: Check the modem in the panel.
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license.
        - msg: slot_not_found
          meaning: No slot matches the port or position.
          remedy: Use a port or position from /api/v1/info_list.
        - msg: invalid_format_proxy
          meaning: The proxy value is not HOST:PORT.
          remedy: Send it as HOST:PORT, for example 192.0.2.10:4001.
      x-since: v20.8.0
  /api/v1/rotate_ip/position/{position}:
    get:
      operationId: rotateIpForPosition
      tags:
        - Rotation
      summary: Get a new public IP for one slot
      description: "Use this to rotate the IP of a slot by its number. Returns at once; poll the slot status until it reports `MODEM_READY`. A slot stopped by the box (auto-stop) is refused with `MODEM_STOPPED`. With a rotation delay configured the answer is `status: true` with an empty `msg`."
      x-xproxy-safety: action
      x-agent-note: "Changes the public IP and drops open connections on this slot for 10-60 seconds. Do not loop: rotations closer than the minimum interval are refused. Check `status`, not the HTTP code."
      x-stability: public
      x-hub: approval
      x-auth-note: 'Open by default: with "Basic auth for all API" (`api_auth_check`) off, anyone who can reach the box can call it. When it is on, the caller must be trusted (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or send dashboard Basic credentials, which are checked only when dashboard authentication (`dashboard_disable_auth` off) is enabled.'
      security:
        - basicAuth: []
        - {}
      parameters:
        - $ref: "#/components/parameters/positionPath"
      responses:
        "200":
          description: Rotation accepted or refused.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                sent:
                  summary: Rotation started
                  value:
                    status: true
                    msg: command_sent
                stopped:
                  summary: Slot stopped by the box
                  value:
                    status: false
                    msg: MODEM_STOPPED
                noLicense:
                  summary: License without IP rotation
                  value:
                    status: false
                    msg: need_upgrade
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: MODEM_STOPPED
          meaning: The box stopped this slot (auto-stop after repeated failures).
          remedy: Clear the stop in the panel first.
        - msg: command_sent
          meaning: With status true, the rotation started. With status false, the modem did not accept the command.
          remedy: On status false wait a few seconds and check the slot status before retrying.
        - msg: modem_resetting
          meaning: A rotation is already running on this slot.
          remedy: Wait for MODEM_READY before rotating again.
        - msg: reset_too_much
          meaning: The last rotation was less than the minimum interval ago (5 seconds by default).
          remedy: Wait and retry.
        - msg: modem_disconnected
          meaning: The modem type cannot rotate.
          remedy: Check the modem in the panel.
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license.
        - msg: slot_not_found
          meaning: No modem in this slot.
          remedy: Use a position from /api/v1/info_list.
      x-since: v20.8.0
  /api/v1/reboot/proxy/{proxy}:
    get:
      operationId: rebootDongleForProxy
      tags:
        - Modem reboot
      summary: Reboot the modem behind one proxy
      description: Use this when a proxy stays offline or slow and a rotation does not help. Reboots the modem of the slot behind the port. When a router-type modem does not answer, the box resets its USB port instead. The proxy is offline until the modem is back (usually 30-120 seconds).
      x-xproxy-safety: action
      x-agent-note: Takes the proxy offline for up to a few minutes and drops all its connections. Use only after status shows the modem offline or broken, not as a way to rotate.
      x-stability: public
      x-hub: approval
      x-auth-note: 'Open by default: with "Basic auth for all API" (`api_auth_check`) off, anyone who can reach the box can call it. When it is on, the caller must be trusted (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or send dashboard Basic credentials, which are checked only when dashboard authentication (`dashboard_disable_auth` off) is enabled.'
      security:
        - basicAuth: []
        - {}
      parameters:
        - $ref: "#/components/parameters/proxyPath"
      responses:
        "200":
          description: Reboot result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                done:
                  summary: Reboot sent
                  value:
                    status: true
                    msg: Reboot modem done!
                notFound:
                  summary: Unknown port
                  value:
                    status: false
                    msg: modem_not_found
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: modem_not_found
          meaning: No slot matches the port or position.
          remedy: Use a port or position from /api/v1/info_list.
        - msg: "Reboot failed: modem did not answer"
          meaning: The modem ignored the reboot and the USB reset was not possible.
          remedy: Check the modem and its USB connection on site.
        - msg: Modem disconnected!
          meaning: The modem type cannot be rebooted by the box.
          remedy: Check the modem in the panel.
        - msg: invalid_format_proxy
          meaning: The proxy value is not HOST:PORT.
          remedy: Send it as HOST:PORT, for example 192.0.2.10:4001.
      x-since: v20.8.0
  /api/v1/reboot/position/{position}:
    get:
      operationId: rebootDongleForPosition
      tags:
        - Modem reboot
      summary: Reboot the modem in one slot
      description: Use this when a slot stays offline and a rotation does not help. Reboots the modem by slot number; a non-answering router-type modem gets a USB reset instead.
      x-xproxy-safety: action
      x-agent-note: Takes the slot offline for up to a few minutes and drops all its connections. Use only after status shows the modem offline or broken.
      x-stability: public
      x-hub: approval
      x-auth-note: 'Open by default: with "Basic auth for all API" (`api_auth_check`) off, anyone who can reach the box can call it. When it is on, the caller must be trusted (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or send dashboard Basic credentials, which are checked only when dashboard authentication (`dashboard_disable_auth` off) is enabled.'
      security:
        - basicAuth: []
        - {}
      parameters:
        - $ref: "#/components/parameters/positionPath"
      responses:
        "200":
          description: Reboot result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                done:
                  summary: Reboot sent
                  value:
                    status: true
                    msg: Reboot modem done!
                usbReset:
                  summary: Modem did not answer, USB port reset
                  value:
                    status: true
                    msg: Modem did not answer, USB reset done!
                emptySlot:
                  summary: Empty slot
                  value:
                    status: false
                    msg: Modem disconnected!
                notFound:
                  summary: Position above the slot count
                  value:
                    status: false
                    msg: modem_not_found
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-errors:
        - msg: modem_not_found
          meaning: No slot matches the port or position.
          remedy: Use a port or position from /api/v1/info_list.
        - msg: "Reboot failed: modem did not answer"
          meaning: The modem ignored the reboot and the USB reset was not possible.
          remedy: Check the modem and its USB connection on site.
        - msg: Modem disconnected!
          meaning: The modem type cannot be rebooted by the box.
          remedy: Check the modem in the panel.
        - msg: invalid_format_proxy
          meaning: The proxy value is not HOST:PORT.
          remedy: Send it as HOST:PORT, for example 192.0.2.10:4001.
      x-since: v20.8.0
  /vpn_config:
    get:
      operationId: getVpnConfig
      tags:
        - VPN
      summary: Read the VPN server settings of every slot
      description: "Returns a map from slot position to its VPN settings, or `data: null` when no slot has a VPN configured. This response returns secrets (`vpn_pass`, `vpn_rotation_token`)."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: VPN settings per slot.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type:
                      - object
                      - "null"
                    additionalProperties:
                      $ref: "#/components/schemas/VpnSlotConfig"
              example:
                status: true
                data:
                  "1":
                    vpn_enable: 1
                    number_client: 2
                    enable_vpn_vps: 0
                    vpn_mtu: "1420"
                    vpn_type: wg
                    vpn_user: ""
                    vpn_pass: YOUR_VPN_PASSWORD
                    vpn_expire_at: null
                    vpn_quota_gb: null
                    vpn_quota_used_bytes: 0
                    vpn_rotation_token: YOUR_VPN_ROTATION_TOKEN
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /vpn_server_config:
    post:
      operationId: setVpnServerConfig
      tags:
        - VPN
      summary: Turn a slot's VPN server on or off and change its settings
      description: Creates or updates the VPN server of one slot and regenerates its configuration. Needs the VPN license feature. While a slot's VPN is on its type cannot change; turn it off first. `vpn_mtu` `FF` means 1420. Changing the quota or re-enabling resets the used bytes. Existing client profiles are regenerated unless `keep_vpn_file` is true, which invalidates profiles already handed out.
      x-xproxy-safety: destructive
      x-agent-note: Ask the user before calling; regenerating a slot's VPN cuts connected VPN clients and can invalidate their profiles. Verify with GET /vpn_config.
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - position
                - vpn_enable
                - number_client
                - enable_vpn_vps
                - vpn_mtu
                - vpn_type
                - vpn_user
                - vpn_pass
              properties:
                position:
                  type: integer
                  minimum: 1
                vpn_enable:
                  type: boolean
                number_client:
                  type: integer
                  minimum: 1
                enable_vpn_vps:
                  type: boolean
                vpn_mtu:
                  type: string
                  description: MTU, or FF for the default 1420.
                vpn_type:
                  type: string
                  enum:
                    - wg
                    - opvn
                vpn_user:
                  type: string
                  description: OpenVPN login user (empty for WireGuard).
                vpn_pass:
                  type: string
                  description: OpenVPN login password (empty for WireGuard).
                keep_vpn_file:
                  type: boolean
                  default: false
                vpn_expire_at:
                  type:
                    - string
                    - "null"
                vpn_quota_gb:
                  type:
                    - number
                    - "null"
                  description: 0 or empty means no quota.
            example:
              position: 1
              vpn_enable: true
              number_client: 2
              enable_vpn_vps: false
              vpn_mtu: FF
              vpn_type: wg
              vpn_user: ""
              vpn_pass: YOUR_VPN_PASSWORD
              keep_vpn_file: false
              vpn_expire_at: null
              vpn_quota_gb: null
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Saved
                  value:
                    status: true
                    msg: Configuration successfully!
                typeLocked:
                  summary: Type change while on
                  value:
                    status: false
                    msg: VPN server already enable can not change VPN type!
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: This function is available on higher plan license only. Please contact Administrator!
          meaning: The license has no VPN feature.
          remedy: Upgrade the license.
        - msg: VPN service is not available
          meaning: The VPN service is not running in the controller.
          remedy: Restart the controller and retry.
        - msg: "Missing required fields: [...]"
          meaning: A required field is missing.
          remedy: Send every required field.
        - msg: VPN server already enable can not change VPN type!
          meaning: The slot's VPN is on with another type.
          remedy: Turn it off (vpn_enable false) first, then change the type.
        - msg: "Configuration failed: ..."
          meaning: Saving or generating the VPN config failed.
          remedy: Check the controller log and retry.
      x-since: v20.8.0
  /v2/get_vpn_port:
    get:
      operationId: getVpnPort
      tags:
        - VPN
      summary: Read the base ports of the WireGuard and OpenVPN servers
      description: Returns the first port of the WireGuard range (`wg_port`) and of the OpenVPN range (`opvn_port`); each slot uses base + position.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Base ports.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      wg_port:
                        type: integer
                      opvn_port:
                        type: integer
              example:
                status: true
                data:
                  wg_port: 8001
                  opvn_port: 9001
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /v2/set_vpn_port:
    post:
      operationId: setVpnPort
      tags:
        - VPN
      summary: Change the base ports of the WireGuard and OpenVPN servers
      description: Saves both base ports, kills every OpenVPN process and restarts the controller. Both fields are required and are not range-checked by the box.
      x-xproxy-safety: destructive
      x-agent-note: "Ask the user first: it restarts the controller (all proxies drop briefly) and every VPN client profile must be updated with the new ports. Verify with GET /v2/get_vpn_port once the panel answers again."
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - wg_port
                - opvn_port
              properties:
                wg_port:
                  type: integer
                  minimum: 1024
                  maximum: 65535
                opvn_port:
                  type: integer
                  minimum: 1024
                  maximum: 65535
            example:
              wg_port: 8001
              opvn_port: 9001
      responses:
        "200":
          description: Saved; the controller restarts.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              example:
                status: true
                msg: Configuration successfully!
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      x-since: v20.8.0
  /vpn/rotate:
    get:
      operationId: rotateVpnIp
      tags:
        - VPN rotation
      summary: Get a new public IP for the slot behind a box VPN, using its rotation link
      description: Use this to rotate the IP of the slot a VPN profile exits through, for example from a phone connected to the box VPN. The token is the rotation token shown on the box's VPN page. Token and VPN problems answer with `message`; the rotation itself answers with `msg` and the same codes as `/api/v1/rotate_ip/position/{position}`.
      x-xproxy-safety: action
      x-agent-note: Changes the public IP of the VPN's slot and interrupts the VPN traffic for 10-60 seconds. Do not loop. Check `status`; the HTTP code is 200 even on refusal.
      x-stability: public
      x-hub: approval
      x-auth-note: Authenticated only by the VPN rotation token; the dashboard login and "Basic auth for all API" do not apply.
      security:
        - vpnToken: []
      responses:
        "200":
          description: Rotation result or token refusal.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/StatusMsg"
                  - type: object
                    properties:
                      status:
                        type: boolean
                        const: false
                      message:
                        type: string
                        enum:
                          - Token required
                          - Invalid token
                          - VPN is not enabled
                          - Try again later
              examples:
                sent:
                  summary: Rotation started
                  value:
                    status: true
                    msg: command_sent
                badToken:
                  summary: Unknown token
                  value:
                    status: false
                    message: Invalid token
                disabled:
                  summary: VPN profile disabled
                  value:
                    status: false
                    message: VPN is not enabled
      x-errors:
        - msg: Token required
          meaning: token is missing or blank.
          remedy: Use the full rotation link from the VPN page.
        - msg: Invalid token
          meaning: No VPN profile has this rotation token.
          remedy: Copy the link again; it changes when the token is regenerated.
        - msg: VPN is not enabled
          meaning: The VPN profile is turned off.
          remedy: Enable the VPN on the box.
        - msg: Try again later
          meaning: Unexpected error on the box.
          remedy: Retry later; check the box logs if it persists.
        - msg: MODEM_STOPPED
          meaning: The box stopped this slot.
          remedy: Clear the stop in the panel.
        - msg: reset_too_much
          meaning: Rotated less than the minimum interval ago.
          remedy: Wait and retry.
        - msg: need_upgrade
          meaning: The license does not include IP rotation.
          remedy: Upgrade the license.
      x-since: v21.0.15
  /v2/forwarding/get_vps_config:
    get:
      operationId: getVpsForwardingConfig
      tags:
        - VPS forwarding
      summary: Read the VPS connection and forwarding rules
      description: "Returns the VPS address, SSH port, user, whether forwarding is on, the auth method, the saved rules, the available tunnel engines and the VPS host-key fingerprint. Secrets are never returned: `vps_relay_pass` is always empty and only `*_set` flags and key fingerprints show whether a password, private key or sudo password is stored."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: VPS settings and rules.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    allOf:
                      - $ref: "#/components/schemas/VpsForwardingRules"
                      - type: object
                        properties:
                          vps_relay_address_servery:
                            type:
                              - string
                              - "null"
                            description: VPS address (the key name has this spelling).
                          vps_relay_port:
                            type: integer
                          vps_relay_user:
                            type:
                              - string
                              - "null"
                          vps_relay_enable:
                            type: boolean
                          vps_relay_authen_method:
                            type:
                              - string
                              - "null"
                          vps_relay_pass:
                            type: string
                            const: ""
                          vps_relay_pass_set:
                            type: boolean
                          vps_relay_key_set:
                            type: boolean
                          vps_relay_key_fingerprint:
                            type: string
                          vps_relay_sudo_pass_set:
                            type: boolean
                          vps_tunnel_stacks:
                            type: array
                            items:
                              type: string
                          vps_relay_host_key_fingerprint:
                            type: string
              example:
                status: true
                data:
                  vps_relay_address_servery: 203.0.113.50
                  vps_relay_port: 22
                  vps_relay_user: root
                  vps_relay_enable: true
                  vps_relay_authen_method: password
                  vps_relay_pass: ""
                  vps_relay_pass_set: true
                  vps_relay_key_set: false
                  vps_relay_key_fingerprint: ""
                  vps_relay_sudo_pass_set: false
                  vps_relay_adjust_proxy_port: 0
                  vps_relay_adjust_web_port: 0
                  vps_relay_adjust_selling_port: 0
                  vps_relay_adjust_group_port: 0
                  vps_relay_adjust_vpn_port: 0
                  vps_relay_adjust_ssh_port: 10000
                  vps_relay_enable_proxy: true
                  vps_relay_enable_selling: false
                  vps_relay_enable_group: false
                  vps_relay_enable_vpn: false
                  vps_relay_enable_web: true
                  vps_relay_enable_ssh: false
                  vps_net_isolate_enable: false
                  vps_proc_isolate_enable: false
                  vps_socks5_udp_enable: true
                  vps_relay_selling_access_log: false
                  vps_starting_relay_port: 20000
                  vps_relay_tunnels: 4
                  vps_tunnel_stack: xrelay
                  vps_tunnel_stacks:
                    - xrelay
                    - wireguard
                  vps_relay_host_key_fingerprint: YOUR_VPS_HOST_KEY_FINGERPRINT
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v20.8.0
  /v2/forwarding/get_mapping_ports:
    get:
      operationId: getVpsForwardingMappingPorts
      tags:
        - VPS forwarding
      summary: List every forwarded port with its VPS port and state
      description: Returns one row per forwarding service (relay tunnels and per-port forwards) with the local port, public VPS port, status and the last error with its diagnosed cause.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Rows, or the error text.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: array
                    items:
                      allOf:
                        - $ref: "#/components/schemas/VpsForwardingServiceRow"
                        - type: object
                          properties:
                            error:
                              type:
                                - string
                                - "null"
                            cause:
                              type:
                                - string
                                - "null"
              examples:
                ok:
                  summary: Rows
                  value:
                    status: true
                    data:
                      - service_name: xlocal@4001
                        svc_type: xlocal
                        modem_position: 1
                        vps_address: 203.0.113.50
                        relay_port: 20001
                        local_port: 4001
                        vps_port: 4001
                        status: running
                        service_live: true
                        memory_use: 12.5
                        last_check: 1763366400
                        error: null
                        cause: null
                error:
                  summary: Failed
                  value:
                    status: false
                    msg: "Failed to get mapping ports: database is locked"
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: "Failed to get mapping ports: ..."
          meaning: Reading the service table failed.
          remedy: Retry; check the controller log.
      x-since: v20.8.0
  /v2/forwarding/preflight:
    get:
      operationId: getVpsForwardingPreflight
      tags:
        - VPS forwarding
      summary: Check whether the box is safe to expose through the VPS
      description: Evaluates the security checklist (license, dashboard password when the dashboard is exposed, proxy login when proxies are exposed). `enable_web` and `enable_proxy` evaluate a draft service selection; when omitted the saved rules are used. The same check gates /v2/forwarding/config_rules.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      parameters:
        - name: enable_web
          in: query
          description: Draft value for exposing the dashboard (true/false, 1/0).
          schema:
            type: string
          example: "true"
        - name: enable_proxy
          in: query
          description: Draft value for exposing the proxies (true/false, 1/0).
          schema:
            type: string
          example: "true"
      responses:
        "200":
          description: Checklist, or a failure.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    $ref: "#/components/schemas/VpsForwardingPreflight"
              examples:
                blocked:
                  summary: Dashboard password missing
                  value:
                    status: true
                    data:
                      client_ip: 192.0.2.20
                      license_ok: true
                      services:
                        web: true
                        proxy: true
                      dashboard:
                        password_set: false
                        user: admin
                      proxy:
                        password_set: true
                        user: user1
                      blocking: true
                      items:
                        - id: dash_password
                          scope: dashboard
                          level: error
                          fix: secure_setup
                          title: Dashboard password
                          msg: So only you can open the dashboard through the VPS
                        - id: proxy_password
                          scope: proxy
                          level: ok
                          fix: null
                          title: Proxy username & password
                          msg: Set (user "user1")
                error:
                  summary: Failed
                  value:
                    status: false
                    msg: Failed to evaluate VPS forwarding security
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Failed to evaluate VPS forwarding security
          meaning: The checklist could not be built.
          remedy: Retry; check the controller log.
      x-since: v21.2.34
  /v2/forwarding/config_rules:
    post:
      operationId: setVpsForwardingRules
      tags:
        - VPS forwarding
      summary: Change which services the VPS publishes and on which ports
      description: Validates the rules (keys left out keep their saved value). Needs the VPS forwarding license feature. While forwarding is off the rules are only saved. While forwarding is on, the security preflight must pass and a go-live job starts that checks everything, sets up the VPS and applies the rules without a panel restart; the answer then carries `job_id` and the job reports progress in the panel. Stored VPS credentials are reused when the body leaves them empty.
      x-xproxy-safety: destructive
      x-agent-note: "Ask the user first: while forwarding is live this republishes services on the public VPS (and can expose the dashboard or SSH). Run GET /v2/forwarding/preflight first. Verify with GET /v2/forwarding/get_vps_config and /v2/forwarding/get_mapping_ports after the job ends."
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VpsForwardingRules"
            example:
              vps_relay_enable_proxy: true
              vps_relay_enable_web: false
              vps_relay_adjust_proxy_port: 0
              vps_starting_relay_port: 20000
              vps_relay_tunnels: 4
              vps_tunnel_stack: xrelay
      responses:
        "200":
          description: Saved, go-live job started, or a refusal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  code:
                    type: string
                    const: preflight_blocked
                  data:
                    oneOf:
                      - type: object
                        properties:
                          job_id:
                            type: string
                        required:
                          - job_id
                        additionalProperties: false
                      - $ref: "#/components/schemas/VpsForwardingPreflight"
              examples:
                saved:
                  summary: Forwarding off
                  value:
                    status: true
                    msg: Saved. The rules apply when VPS forwarding is turned on.
                job:
                  summary: Forwarding on, job started
                  value:
                    status: true
                    data:
                      job_id: YOUR_JOB_ID
                blocked:
                  summary: Preflight failed
                  value:
                    status: false
                    code: preflight_blocked
                    msg: Secure the dashboard and proxies before exposing them on the VPS
                    data:
                      client_ip: 192.0.2.20
                      license_ok: true
                      services:
                        web: true
                        proxy: true
                      dashboard:
                        password_set: false
                        user: admin
                      proxy:
                        password_set: true
                        user: user1
                      blocking: true
                      items:
                        - id: dash_password
                          scope: dashboard
                          level: error
                          fix: secure_setup
                          title: Dashboard password
                          msg: So only you can open the dashboard through the VPS
                range:
                  summary: Bad offset
                  value:
                    status: false
                    msg: VPS proxy port 70001 is out of range (100-65000), please adjust the proxy offset.
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: This function is available on higher plan license only. Please contact Administrator!
          meaning: The license has no VPS forwarding feature.
          remedy: Upgrade the license.
        - msg: Secure the dashboard and proxies before exposing them on the VPS
          meaning: "code preflight_blocked: an exposed service has no login; data holds the checklist."
          remedy: Set a dashboard password and proxy login, then retry.
        - msg: Parallel tunnels per port must be between 1 and 16.
          meaning: vps_relay_tunnels is out of range.
          remedy: Send 1–16.
        - msg: Unknown tunnel engine.
          meaning: vps_tunnel_stack is not xrelay or wireguard.
          remedy: Send xrelay or wireguard.
        - msg: Network isolation needs the Relay engine. ...
          meaning: vps_net_isolate_enable is on with the wireguard engine.
          remedy: Turn off network isolation or use xrelay.
        - msg: VPS NAME port N is out of range (LOW-HIGH), please adjust the FIELD.
          meaning: An offset moves a public port out of range.
          remedy: Change the named offset.
        - msg: VPS selling offset must be between -65000 and 65000.
          meaning: Selling (or group) offset out of range.
          remedy: Send a value in range.
          origin: formatted
        - msg: Starting relay port must be between 100 and 65532.
          meaning: vps_starting_relay_port out of range.
          remedy: Send 100–65532.
        - msg: A VPS setup is already running
          meaning: Another go-live job runs.
          remedy: Wait for it to finish.
        - msg: Failed to add forwarding configs!
          meaning: Unexpected error.
          remedy: Check the controller log and retry.
      x-since: v20.8.0
  /v2/forwarding/vps_health:
    get:
      operationId: getVpsForwardingHealth
      tags:
        - VPS forwarding
      summary: Read the VPS's health (CPU, RAM, disk, relay) and service totals
      description: Returns the latest health snapshot of the VPS collected over SSH plus counts of the forwarding services. When the VPS cannot be reached `reachable` is false with an `error`.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Health view, or the error text.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: object
                    additionalProperties: true
                    properties:
                      reachable:
                        type: boolean
                      error:
                        type: string
                      checked_at:
                        type: integer
                      cpu:
                        type: object
                        properties:
                          pct:
                            type:
                              - number
                              - "null"
                      ram:
                        type: object
                        properties:
                          used_mb:
                            type: integer
                          total_mb:
                            type: integer
                          pct:
                            type: number
                      disk:
                        type: object
                        properties:
                          used_gb:
                            type: number
                          total_gb:
                            type: number
                          pct:
                            type: number
                      net:
                        type: object
                        properties:
                          in_mbps:
                            type:
                              - number
                              - "null"
                          out_mbps:
                            type:
                              - number
                              - "null"
                      uptime_s:
                        type:
                          - integer
                          - "null"
                      connections:
                        type: integer
                      cpus:
                        type: integer
                      boxes:
                        type: integer
                        description: Boxes sharing this VPS.
                      relay:
                        type: object
                        properties:
                          state:
                            type: string
                          memory_mb:
                            type:
                              - number
                              - "null"
                          version:
                            type:
                              - string
                              - "null"
                      relay_issue:
                        type:
                          - string
                          - object
                          - "null"
                      services:
                        type: object
                        properties:
                          total:
                            type: integer
                          running:
                            type: integer
                          conns:
                            type: integer
                          up_mbps:
                            type: number
                          down_mbps:
                            type: number
              examples:
                ok:
                  summary: Healthy
                  value:
                    status: true
                    data:
                      reachable: true
                      checked_at: 1763366400
                      cpu:
                        pct: 3.5
                      ram:
                        used_mb: 310
                        total_mb: 1987
                        pct: 15.6
                      disk:
                        used_gb: 4.2
                        total_gb: 24.5
                        pct: 17.1
                      net:
                        in_mbps: 12.4
                        out_mbps: 11.9
                      uptime_s: 864000
                      connections: 42
                      cpus: 1
                      boxes: 1
                      relay:
                        state: active
                        memory_mb: 28.3
                        version: 3.0.0
                      relay_issue: null
                      services:
                        total: 6
                        running: 6
                        conns: 40
                        up_mbps: 11.2
                        down_mbps: 12.1
                unreachable:
                  summary: VPS down
                  value:
                    status: true
                    data:
                      reachable: false
                      error: timed out
                      relay_issue: null
                      services:
                        total: 6
                        running: 0
                        conns: 0
                        up_mbps: 0
                        down_mbps: 0
                error:
                  summary: Failed
                  value:
                    status: false
                    msg: "Failed to read VPS health: ..."
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: "Failed to read VPS health: ..."
          meaning: Building the view failed.
          remedy: Retry; check the controller log.
      x-since: v21.2.34
  /v2/forwarding/service_detail:
    get:
      operationId: getVpsForwardingServiceDetail
      tags:
        - VPS forwarding
      summary: Inspect one forwarding service with its events, logs and diagnosed cause
      description: Returns the service row, its last error, recent VPS events, box and VPS log lines and a diagnosed cause and hint. Reads logs over SSH, so it can take some seconds.
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      parameters:
        - name: name
          in: query
          required: true
          description: Service name from /v2/forwarding/get_mapping_ports.
          schema:
            type: string
          example: xlocal@4001
      responses:
        "200":
          description: Service detail, or a refusal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    allOf:
                      - $ref: "#/components/schemas/VpsForwardingServiceRow"
                      - type: object
                        properties:
                          last_error:
                            type:
                              - object
                              - "null"
                            additionalProperties: true
                          vps_state:
                            type: string
                          events:
                            type: array
                            items:
                              type: object
                              properties:
                                time:
                                  type:
                                    - number
                                    - "null"
                                msg:
                                  type: string
                                where:
                                  type: string
                          logs:
                            type: object
                            properties:
                              box:
                                type: array
                                items:
                                  type: string
                              vps:
                                type: array
                                items:
                                  type: string
                          cause:
                            type:
                              - string
                              - "null"
                          hint:
                            type:
                              - string
                              - "null"
              examples:
                ok:
                  summary: Detail
                  value:
                    status: true
                    data:
                      service_name: xlocal@4001
                      status: running
                      local_port: 4001
                      vps_port: 4001
                      relay_port: 20001
                      last_error: null
                      events: []
                      logs:
                        box: []
                        vps: []
                      cause: null
                      hint: null
                notFound:
                  summary: Unknown service
                  value:
                    status: false
                    msg: Service xlocal@4999 not found
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Service NAME not found
          meaning: No service has this name.
          remedy: Take the name from /v2/forwarding/get_mapping_ports.
        - msg: "Failed to inspect NAME: ..."
          meaning: Reading the logs failed (for example the VPS is unreachable).
          remedy: Check /v2/forwarding/vps_health.
      x-since: v21.2.34
  /v2/forwarding/restart_service:
    post:
      operationId: restartVpsForwardingService
      tags:
        - VPS forwarding
      summary: Recreate one forwarding service on the box and the VPS
      description: Re-creates the named service (box unit and/or VPS relay entry). Connections through that service drop while it restarts.
      x-xproxy-safety: action
      x-agent-note: Ask the user before restarting services in bulk; each restart drops that port's connections. Verify with GET /v2/forwarding/service_detail.
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
            example:
              name: xlocal@4001
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Restarted
                  value:
                    status: true
                    msg: xlocal@4001 restarted
                failed:
                  summary: Not restarted
                  value:
                    status: false
                    msg: Could not restart xlocal@4001
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Could not restart NAME
          meaning: Unknown service or the restart failed (the service's last error is returned instead when known).
          remedy: Check /v2/forwarding/service_detail.
        - msg: "Failed to restart NAME: ..."
          meaning: Unexpected error.
          remedy: Check the controller log.
      x-since: v21.2.34
  /v2/forwarding/doctor:
    post:
      operationId: runVpsForwardingDoctor
      tags:
        - VPS forwarding
      summary: Run the full VPS forwarding diagnosis
      description: Checks security, SSH, the relay, the firewall, services and public ports, and returns a list of items with a status and, where possible, a one-click fix action for /v2/forwarding/doctor_fix. When forwarding is off it returns a single warning item. Opens SSH and probes ports, so it takes some seconds; it does not change the setup.
      x-xproxy-safety: action
      x-agent-note: Safe to run; it only reads and probes. Do not run it in a loop. Apply fixes only after asking the user.
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Report, or a failure.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  msg:
                    type: string
                  data:
                    type: object
                    properties:
                      checked_at:
                        type: integer
                      duration_ms:
                        type: integer
                      ok:
                        type: boolean
                      support:
                        type: boolean
                        description: True when a failed item needs support.
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            title:
                              type: string
                            status:
                              type: string
                              enum:
                                - ok
                                - warning
                                - failed
                            msg:
                              type: string
                            hint:
                              type: string
                            fix:
                              type:
                                - object
                                - "null"
                              properties:
                                action:
                                  type: string
                                label:
                                  type: string
                            support:
                              type: boolean
              examples:
                ok:
                  summary: Report
                  value:
                    status: true
                    data:
                      checked_at: 1763366400
                      duration_ms: 4200
                      ok: false
                      support: false
                      items:
                        - id: security
                          title: Dashboard & proxy protection
                          status: ok
                          msg: Protected
                          hint: ""
                          fix: null
                          support: false
                        - id: firewall
                          title: VPS firewall
                          status: failed
                          msg: 2 ports blocked
                          hint: Open them in the VPS firewall.
                          fix:
                            action: open_firewall
                            label: Open ports in VPS firewall
                          support: false
                failed:
                  summary: Failed
                  value:
                    status: false
                    msg: "Doctor failed: ..."
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: "Doctor failed: ..."
          meaning: The diagnosis crashed.
          remedy: Check the controller log.
      x-since: v21.2.34
  /v2/forwarding/doctor_fix:
    post:
      operationId: applyVpsForwardingDoctorFix
      tags:
        - VPS forwarding
      summary: Apply one repair suggested by the VPS forwarding doctor
      description: "Runs one fix action from a doctor item: repair_relay (re-push every relay entry), fix_sshd, cleanup_legacy (remove the old agent from the VPS), open_firewall (open the forwarding ports in ufw/firewalld), restart_failed (restart services not running), repush_frontends (needs a prior doctor run), repair_wireguard, trust_host_key (accept the VPS's new SSH identity). The answer `status` is the fix result."
      x-xproxy-safety: action
      x-agent-note: "Ask the user before every fix: they change the VPS (firewall, sshd, services), and trust_host_key accepts a changed SSH identity, which must be confirmed as expected. Run /v2/forwarding/doctor again to verify."
      x-stability: panel
      x-hub: approval
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: string
                  enum:
                    - repair_relay
                    - fix_sshd
                    - cleanup_legacy
                    - open_firewall
                    - restart_failed
                    - repush_frontends
                    - repair_wireguard
                    - trust_host_key
            example:
              action: open_firewall
      responses:
        "200":
          description: Fix result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusMsg"
              examples:
                ok:
                  summary: Fixed
                  value:
                    status: true
                    msg: opened 6 ports in ufw
                unknown:
                  summary: Unknown action
                  value:
                    status: false
                    msg: Unknown fix reboot
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-errors:
        - msg: Unknown fix ACTION
          meaning: action is not one of the listed fixes.
          remedy: Use an action from a doctor item.
        - msg: No ufw/firewalld on the VPS; open the ports in the provider firewall.
          meaning: open_firewall found no host firewall.
          remedy: Open the ports in the VPS provider's firewall.
        - msg: "Run the doctor first: no failing port is recorded."
          meaning: repush_frontends needs a doctor run that found failing ports.
          remedy: Run /v2/forwarding/doctor first.
        - msg: "Fix failed: ..."
          meaning: Unexpected error.
          remedy: Check the controller log.
      x-since: v21.2.34
  /v2/proxy/public_reach:
    get:
      operationId: getProxyPublicReach
      tags:
        - VPS forwarding
      summary: Read whether the proxy ports are reachable from the internet (cached)
      description: "Returns the last known reachability of every listening proxy port and the box's public and LAN IP, without probing. Ports are unknown (`open: null`) until POST /v2/proxy/public_reach/check has run. Detects the public IP once if it is not known yet."
      x-xproxy-safety: read
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Reachability view.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    $ref: "#/components/schemas/VpsForwardingReach"
              example:
                status: true
                data:
                  public_ip: 203.0.113.10
                  lan_ip: 192.0.2.10
                  checked_at: 2026-11-17T08:00:00Z
                  ports:
                    - port: 4001
                      kind: http
                      position: 1
                      open: true
                    - port: 5001
                      kind: socks
                      position: 1
                      open: true
                  unavailable: false
                  open_count: 1
                  total: 1
                  wan: null
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v21.2.34
  /v2/proxy/public_reach/check:
    post:
      operationId: checkProxyPublicReach
      tags:
        - VPS forwarding
      summary: Probe now whether the proxy ports are reachable from the internet
      description: "Asks the xproxy.io probe server to TCP-connect back to the caller box's own public IP on every listening proxy port, then returns the same view as GET /v2/proxy/public_reach. Only the box's own source IP is probed. When the probe server is down or slow, the answer is still 200 with `unavailable: true`, and further probes are skipped for 60 seconds."
      x-xproxy-safety: action
      x-agent-note: Sends the box's port list to xproxy.io; run once per check, not in a loop. Read the result from the answer or GET /v2/proxy/public_reach.
      x-stability: panel
      x-hub: routine
      x-auth-note: Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.
      security:
        - basicAuth: []
      responses:
        "200":
          description: Reachability view after the probe.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    const: true
                  data:
                    $ref: "#/components/schemas/VpsForwardingReach"
              example:
                status: true
                data:
                  public_ip: 203.0.113.10
                  lan_ip: 192.0.2.10
                  checked_at: 2026-11-17T08:00:00Z
                  ports:
                    - port: 4001
                      kind: http
                      position: 1
                      open: true
                    - port: 5001
                      kind: socks
                      position: 1
                      open: true
                  unavailable: false
                  open_count: 1
                  total: 1
                  wan: null
        "401":
          $ref: "#/components/responses/Unauthorized"
      x-since: v21.2.34
