openapi.yaml

openapi: 3.0.3
info:
  title: VortexUI Panel API
  version: "0.1.0"
  description: >
    Control-plane REST API for VortexUI. All endpoints under `/api` (except
    `/api/login` and `/api/health`) require a Bearer JWT obtained from
    `/api/login`. Mutating routes additionally require an RBAC permission
    (sudo admins bypass all permission checks). The public `/sub/{token}`
    endpoint is authenticated solely by the opaque subscription token.

servers:
  - url: http://localhost:8080
    description: Local panel

tags:
  - name: Auth
  - name: Account
  - name: Users
  - name: Nodes
  - name: Inbounds
  - name: Admins
  - name: Roles
  - name: Subscription
  - name: Subscription Hosts
  - name: Routing Packs
  - name: Clean IP
  - name: IP Limit
  - name: Capabilities

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Error:
      type: object
      properties:
        message: {type: string}
    Credentials:
      type: object
      properties:
        vmess_uuid: {type: string, format: uuid}
        vless_uuid: {type: string, format: uuid}
        trojan_password: {type: string}
        ss_password: {type: string}
        ss_method: {type: string, example: aes-128-gcm}
    User:
      type: object
      properties:
        id: {type: string, format: uuid}
        username: {type: string}
        status: {type: string, enum: [active, limited, expired, disabled, on_hold]}
        note: {type: string}
        data_limit: {type: integer, format: int64, description: bytes; 0 = unlimited}
        used_traffic: {type: integer, format: int64}
        expire_at: {type: string, format: date-time, nullable: true}
        reset_strategy: {type: string, enum: [no_reset, daily, weekly, monthly]}
        device_limit: {type: integer, description: 0 = unlimited}
        allowed_hwids: {type: array, items: {type: string}}
        proxies: {$ref: '#/components/schemas/Credentials'}
        sub_token: {type: string}
        created_at: {type: string, format: date-time}
        updated_at: {type: string, format: date-time}
    NodeHealth:
      type: object
      properties:
        cpu_percent: {type: number}
        mem_percent: {type: number}
        disk_percent: {type: number}
        core_running: {type: boolean}
        connections: {type: integer}
    Node:
      type: object
      properties:
        id: {type: string, format: uuid}
        name: {type: string}
        address: {type: string, example: "1.2.3.4:50051"}
        core: {type: string, enum: [xray, singbox]}
        enabled_cores:
          type: array
          items: {type: string, enum: [xray, singbox]}
          description: Active proxy engines on this node (multi-core A/B)
        status: {type: string, enum: [connected, disconnected, error, disabled]}
        usage_ratio: {type: number}
        last_seen: {type: string, format: date-time, nullable: true}
        health: {$ref: '#/components/schemas/NodeHealth'}
        core_version: {type: string}
        agent_version: {type: string}
        created_at: {type: string, format: date-time}
    Inbound:
      type: object
      properties:
        id: {type: string, format: uuid}
        node_id: {type: string, format: uuid}
        tag: {type: string}
        core:
          type: string
          enum: [xray, singbox, ""]
          description: Engine override; empty inherits node default
        protocol: {type: string, enum: [vmess, vless, trojan, shadowsocks, hysteria2, tuic, wireguard]}
        listen: {type: string}
        port: {type: integer}
        network: {type: string, enum: [tcp, ws, grpc, httpupgrade, xhttp]}
        security: {type: string, enum: [none, tls, reality]}
        sni: {type: array, items: {type: string}}
        path: {type: string}
        host: {type: array, items: {type: string}}
        flow: {type: string}
        raw: {type: object, additionalProperties: true}
        enabled: {type: boolean}
    Outbound:
      type: object
      properties:
        id: {type: string, format: uuid}
        node_id: {type: string, format: uuid}
        tag: {type: string}
        protocol: {type: string, enum: [freedom, blackhole, dns, vmess, vless, trojan, shadowsocks, socks, http]}
        address: {type: string, description: required for proxy protocols}
        port: {type: integer, description: required for proxy protocols}
        uuid: {type: string, description: vmess/vless credential}
        password: {type: string, description: trojan/shadowsocks/socks/http credential}
        username: {type: string, description: socks/http credential}
        method: {type: string, description: shadowsocks cipher}
        flow: {type: string}
        network: {type: string, enum: [tcp, ws, grpc]}
        security: {type: string, enum: [none, tls, reality]}
        sni: {type: string}
        path: {type: string}
        host: {type: string}
        raw: {type: object, additionalProperties: true}
        enabled: {type: boolean}
    RoutingRule:
      type: object
      description: >
        Evaluated in ascending priority. At least one matcher and exactly one of
        outbound_tag / balancer_tag are required.
      properties:
        id: {type: string, format: uuid}
        node_id: {type: string, format: uuid}
        priority: {type: integer}
        name: {type: string}
        inbound_tags: {type: array, items: {type: string}}
        domains: {type: array, items: {type: string}}
        ip: {type: array, items: {type: string}}
        port: {type: string, description: '"443", "80,443", or "1000-2000"'}
        protocols: {type: array, items: {type: string}}
        network: {type: string, enum: [tcp, udp]}
        outbound_tag: {type: string}
        balancer_tag: {type: string}
        enabled: {type: boolean}
    Balancer:
      type: object
      properties:
        id: {type: string, format: uuid}
        node_id: {type: string, format: uuid}
        tag: {type: string}
        selectors: {type: array, items: {type: string}, description: outbound tag prefixes}
        strategy: {type: string, enum: [random, roundRobin, leastPing, leastLoad]}
        observe: {type: boolean}
        probe_url: {type: string}
        probe_interval: {type: string, description: 'e.g. "10s"'}
        enabled: {type: boolean}
    Admin:
      type: object
      properties:
        id: {type: string, format: uuid}
        username: {type: string}
        sudo: {type: boolean}
        role_id: {type: string, format: uuid, nullable: true}
        totp_enabled: {type: boolean}
        user_quota: {type: integer}
        traffic_quota: {type: integer, format: int64}
        last_login: {type: string, format: date-time, nullable: true}
        created_at: {type: string, format: date-time}
    AdminQuotaUsage:
      type: object
      properties:
        admin_id: {type: string, format: uuid}
        username: {type: string}
        user_quota: {type: integer}
        user_count: {type: integer}
        users_remaining: {type: integer, nullable: true}
        traffic_quota: {type: integer, format: int64}
        traffic_quota_mode: {type: string, enum: [allocated, consumed]}
        traffic_used: {type: integer, format: int64}
        traffic_allocated: {type: integer, format: int64}
        traffic_remaining: {type: integer, format: int64, nullable: true}
        wallet_traffic_bytes: {type: integer, format: int64}
        wallet_user_credits: {type: integer}
    AdminWallet:
      type: object
      properties:
        admin_id: {type: string, format: uuid}
        traffic_bytes: {type: integer, format: int64}
        user_credits: {type: integer}
    WalletLedgerEntry:
      type: object
      properties:
        id: {type: string, format: uuid}
        admin_id: {type: string, format: uuid}
        delta_traffic: {type: integer, format: int64}
        delta_users: {type: integer}
        reason: {type: string}
        actor_admin_id: {type: string, format: uuid}
        created_at: {type: string, format: date-time}
    Role:
      type: object
      properties:
        id: {type: string, format: uuid}
        name: {type: string}
        permissions:
          type: array
          items:
            type: string
            enum: [user:read, user:write, node:read, node:write, inbound:read, inbound:write, admin:manage, system:read]

    SubHost:
      type: object
      description: >
        Per-inbound subscription host override (Marzban-style). Lets the link
        rendered into a user's subscription advertise a different address / SNI /
        Host header / path / transport security than the raw inbound, without
        touching the live core config. String fields support template variables
        (e.g. `{USERNAME}`, `{SERVER_IP}`, `{SERVER_PORT}`, `{PROTOCOL}`).
      properties:
        id: {type: string, format: uuid}
        inbound_id: {type: string, format: uuid}
        remark: {type: string, description: 'display/remark template, e.g. "{USERNAME} · DE"'}
        address: {type: string, description: override host/IP advertised to clients}
        port: {type: integer, description: override port (0 = inherit inbound port)}
        sni: {type: string}
        host: {type: string, description: Host header override}
        path: {type: string}
        alpn: {type: string, description: 'comma-separated, e.g. "h2,http/1.1"'}
        fingerprint: {type: string, description: 'uTLS fingerprint, e.g. chrome'}
        security: {type: string, enum: [inbound_default, none, tls, reality], description: 'transport security; inbound_default keeps the inbound setting'}
        allow_insecure: {type: boolean}
        mux_enable: {type: boolean}
        fragment: {type: string, description: 'fragment spec, e.g. "1,40-60,30-50"'}
        priority: {type: integer, description: ascending order within an inbound}
        enabled: {type: boolean}
    RoutingPack:
      type: object
      description: >
        Reusable smart routing rule set (a named collection of routing rules) that
        can be applied to nodes or embedded into Clash/sing-box subscriptions. A
        pack can be the global default and/or assigned per user.
      properties:
        id: {type: string, format: uuid}
        name: {type: string}
        description: {type: string}
        is_default: {type: boolean}
        rules: {type: array, items: {$ref: '#/components/schemas/RoutingRule'}}
        created_at: {type: string, format: date-time}
        updated_at: {type: string, format: date-time}
    CleanIPResult:
      type: object
      description: Scored result of a clean-IP (Cloudflare CDN) scan.
      properties:
        ip: {type: string}
        latency_ms: {type: integer}
        loss_pct: {type: number}
        score: {type: number}
        reachable: {type: boolean}
        scanned_at: {type: string, format: date-time}
    IPLimitPolicy:
      type: object
      description: >
        Account-sharing / device-limit enforcement policy. When a user exceeds
        their concurrent IP/device cap the chosen action is taken (kill_connections
        is Xray-only; sing-box degrades to disable_temporarily).
      properties:
        enabled: {type: boolean}
        action: {type: string, enum: [warn, disable_temporarily, kill_connections]}
        alert_cooldown: {type: integer, description: seconds between repeated alerts}
        restore_after: {type: integer, description: seconds before a temporarily disabled user is restored}
    IPLimitEvent:
      type: object
      properties:
        id: {type: string, format: uuid}
        user_id: {type: string, format: uuid}
        username: {type: string}
        ip_count: {type: integer}
        action: {type: string, enum: [warn, disable_temporarily, kill_connections]}
        ips: {type: array, items: {type: string}}
        created_at: {type: string, format: date-time}
    Capabilities:
      type: object
      description: >
        Per-core capability matrix — the single source of truth for which
        protocol/transport/security combinations a core supports. Keyed by core
        name (`xray`, `singbox`).
      additionalProperties:
        type: object
        properties:
          protocols: {type: array, items: {type: string}}
          transports: {type: array, items: {type: string}}
          securities: {type: array, items: {type: string}}
          udp_native: {type: array, items: {type: string}, description: protocols that manage their own transport}
          no_transport: {type: array, items: {type: string}, description: protocols that carry no stream transport}
          protocol_securities:
            type: object
            additionalProperties: {type: array, items: {type: string}}
            description: allowed security layers per protocol

  responses:
    Unauthorized: {description: missing/invalid token, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
    Forbidden: {description: insufficient permission, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
    NotFound: {description: not found, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}

security:
  - bearerAuth: []

paths:
  /api/health:
    get:
      tags: [Auth]
      security: []
      summary: Liveness probe
      responses:
        "200": {description: ok}

  /api/login:
    post:
      tags: [Auth]
      security: []
      summary: Authenticate an admin and obtain a JWT
      description: Rate limited per client IP (10/min). 2FA code required when the admin has TOTP enabled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username: {type: string}
                password: {type: string}
                totp_code: {type: string}
      responses:
        "200":
          description: token issued
          content: {application/json: {schema: {type: object, properties: {token: {type: string}}}}}
        "401": {$ref: '#/components/responses/Unauthorized'}
        "429": {description: too many attempts; see Retry-After}

  /api/account/2fa/setup:
    post:
      tags: [Account]
      summary: Begin TOTP enrollment for the calling admin
      responses:
        "200":
          description: enrollment secret + otpauth URL (render as QR)
          content: {application/json: {schema: {type: object, properties: {secret: {type: string}, url: {type: string}}}}}
        "409": {description: 2FA already enabled}
  /api/account/2fa/confirm:
    post:
      tags: [Account]
      summary: Activate 2FA by confirming a code
      requestBody:
        required: true
        content: {application/json: {schema: {type: object, required: [code], properties: {code: {type: string}}}}}
      responses:
        "200": {description: enabled}
        "400": {description: invalid or no pending code}
  /api/account/2fa/disable:
    post:
      tags: [Account]
      summary: Disable 2FA (requires a valid current code)
      requestBody:
        required: true
        content: {application/json: {schema: {type: object, required: [code], properties: {code: {type: string}}}}}
      responses:
        "200": {description: disabled}
        "400": {description: invalid code or 2FA not enabled}

  /api/overview:
    get:
      tags: [Overview]
      summary: Dashboard summary — user aggregates + node fleet (perm system:read)
      description: >
        User counts per status and total used traffic, plus each node's derived
        connectivity (same staleness rule as subscriptions) and last reported
        health. Computed from persisted state; no live hub round-trip.
      responses:
        "200":
          description: overview
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: object
                    properties:
                      total: {type: integer}
                      total_used: {type: integer, format: int64}
                      by_status: {type: object, additionalProperties: {type: integer}}
                  nodes:
                    type: object
                    properties:
                      total: {type: integer}
                      online: {type: integer}
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id: {type: string, format: uuid}
                            name: {type: string}
                            core: {type: string}
                            online: {type: boolean}
                            last_seen: {type: string, format: date-time, nullable: true}
                            health: {type: object, additionalProperties: true}
                            core_version: {type: string}
                            agent_version: {type: string}

  /api/logs:
    get:
      tags: [System]
      summary: Recent panel logs (perm system:read)
      description: >
        Returns the panel's in-memory ring buffer of recent log records. Node and
        core logs are not included. Filter by minimum level and cap the count.
      parameters:
        - {name: level, in: query, schema: {type: string, enum: [debug, info, warn, error]}, description: "minimum level (default info)"}
        - {name: limit, in: query, schema: {type: integer, default: 200}}
      responses:
        "200":
          description: log entries (oldest→newest)
          content:
            application/json:
              schema:
                type: object
                properties:
                  entries:
                    type: array
                    items:
                      type: object
                      properties:
                        time: {type: string, format: date-time}
                        level: {type: string}
                        message: {type: string}
                        attrs: {type: object, additionalProperties: true}

  /api/users:
    get:
      tags: [Users]
      summary: List users (perm user:read)
      parameters:
        - {name: search, in: query, schema: {type: string}}
        - {name: status, in: query, schema: {type: string}}
        - {name: limit, in: query, schema: {type: integer, default: 50}}
        - {name: offset, in: query, schema: {type: integer, default: 0}}
      responses:
        "200":
          description: page of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  users: {type: array, items: {$ref: '#/components/schemas/User'}}
                  total: {type: integer}
        "403": {$ref: '#/components/responses/Forbidden'}
    post:
      tags: [Users]
      summary: Create a user (perm user:write)
      description: Credentials and sub_token are generated server-side. A non-fatal `warning` is returned if live provisioning was incomplete.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username]
              properties:
                username: {type: string}
                note: {type: string}
                data_limit: {type: integer, format: int64}
                expire_at: {type: string, format: date-time, nullable: true}
                device_limit: {type: integer}
                reset_strategy: {type: string, enum: [no_reset, daily, weekly, monthly]}
                inbound_ids: {type: array, items: {type: string, format: uuid}}
                on_hold: {type: boolean}
      responses:
        "201":
          description: created
          content: {application/json: {schema: {type: object, properties: {user: {$ref: '#/components/schemas/User'}, warning: {type: string}}}}}
        "403": {$ref: '#/components/responses/Forbidden'}
  /api/users/{id}:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    get:
      tags: [Users]
      summary: Get a user (perm user:read)
      responses:
        "200": {description: user, content: {application/json: {schema: {$ref: '#/components/schemas/User'}}}}
        "404": {$ref: '#/components/responses/NotFound'}
    put:
      tags: [Users]
      summary: Update a user's mutable metadata (perm user:write)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                note: {type: string}
                status: {type: string, enum: [active, disabled]}
                data_limit: {type: integer, format: int64}
                expire_at: {type: string, format: date-time, nullable: true}
                device_limit: {type: integer}
                reset_strategy: {type: string}
      responses:
        "200": {description: updated, content: {application/json: {schema: {type: object, properties: {user: {$ref: '#/components/schemas/User'}, warning: {type: string}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}
    delete:
      tags: [Users]
      summary: Delete a user (perm user:write)
      responses:
        "204": {description: deleted}
        "404": {$ref: '#/components/responses/NotFound'}

  /api/users/{id}/sub:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    get:
      tags: [Users]
      summary: Get a user's subscription URLs + share links (perm user:read)
      description: >
        Returns the subscription URL (absolute, derived from the request host,
        and relative), per-format variants, and the individual share links for
        QR rendering. Unhealthy nodes are pruned, as in the public endpoint.
      responses:
        "200":
          description: subscription info
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: {type: string}
                  subscription_path: {type: string}
                  subscription_url: {type: string}
                  formats:
                    type: object
                    properties:
                      auto: {type: string}
                      clash: {type: string}
                      singbox: {type: string}
                      base64: {type: string}
                  links: {type: array, items: {type: string}}
        "404": {$ref: '#/components/responses/NotFound'}

  /api/users/{id}/online:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    get:
      tags: [Users]
      summary: A user's live connections + active devices (perm user:read)
      description: >
        `live_connections` is the real count summed across the cores the user is
        bound to (Xray GetAllOnlineUsers); `live_tracking` is false when no online
        source is wired. `active_devices` is the distinct devices seen within the
        window from the Redis tracker (subscription-fetch activity); `device_tracking`
        is false when Redis is not configured. Unreachable nodes are skipped.
      responses:
        "200":
          description: online info
          content:
            application/json:
              schema:
                type: object
                properties:
                  live_connections: {type: integer}
                  live_tracking: {type: boolean}
                  active_devices: {type: integer}
                  device_tracking: {type: boolean}
                  window_seconds: {type: integer}

  /api/users/{id}/reset:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    post:
      tags: [Users]
      summary: Reset a user's used traffic now (perm user:write)
      description: Zeroes used traffic and re-activates + re-provisions the user if they were quota-limited.
      responses:
        "200": {description: reset, content: {application/json: {schema: {type: object, properties: {user: {$ref: '#/components/schemas/User'}, warning: {type: string}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}

  /api/users/{id}/revoke-sub:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    post:
      tags: [Users]
      summary: Rotate a user's subscription token (perm user:write)
      description: Issues a new subscription token, invalidating the old subscription URL. Protocol credentials are unchanged.
      responses:
        "200": {description: rotated, content: {application/json: {schema: {type: object, properties: {user: {$ref: '#/components/schemas/User'}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}

  /api/nodes:
    get:
      tags: [Nodes]
      summary: List nodes (perm node:read)
      responses:
        "200": {description: nodes, content: {application/json: {schema: {type: object, properties: {nodes: {type: array, items: {$ref: '#/components/schemas/Node'}}}}}}}
    post:
      tags: [Nodes]
      summary: Create + register a node (perm node:write)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, address]
              properties:
                name: {type: string}
                address: {type: string}
                core: {type: string, enum: [xray, singbox]}
                usage_ratio: {type: number}
      responses:
        "201": {description: created, content: {application/json: {schema: {type: object, properties: {node: {$ref: '#/components/schemas/Node'}, warning: {type: string}}}}}}
  /api/nodes/{id}:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    get:
      tags: [Nodes]
      summary: Get a node (perm node:read)
      responses:
        "200": {description: node, content: {application/json: {schema: {$ref: '#/components/schemas/Node'}}}}
        "404": {$ref: '#/components/responses/NotFound'}
    put:
      tags: [Nodes]
      summary: Update a node, re-establishing its connection (perm node:write)
      requestBody:
        required: true
        content: {application/json: {schema: {type: object, properties: {name: {type: string}, address: {type: string}, usage_ratio: {type: number}}}}}
      responses:
        "200": {description: updated, content: {application/json: {schema: {type: object, properties: {node: {$ref: '#/components/schemas/Node'}, warning: {type: string}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}
    delete:
      tags: [Nodes]
      summary: Deregister + delete a node (perm node:write)
      responses:
        "204": {description: deleted}
  /api/nodes/{id}/logs:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    get:
      tags: [Nodes]
      summary: Recent core log lines from a node (perm node:read)
      description: >
        Returns the node agent's in-memory ring buffer of recent core stdout/stderr
        lines. Fails with 502 when the node is unreachable or its agent cannot
        provide logs.
      parameters:
        - {name: limit, in: query, schema: {type: integer, default: 200}}
      responses:
        "200": {description: log lines (oldest first), content: {application/json: {schema: {type: object, properties: {lines: {type: array, items: {type: string}}}}}}}
        "502": {description: node unreachable / logs unavailable}

  /api/inbounds:
    get:
      tags: [Inbounds]
      summary: List a node's inbounds (perm inbound:read)
      parameters: [{name: node_id, in: query, required: true, schema: {type: string, format: uuid}}]
      responses:
        "200": {description: inbounds, content: {application/json: {schema: {type: object, properties: {inbounds: {type: array, items: {$ref: '#/components/schemas/Inbound'}}}}}}}
    post:
      tags: [Inbounds]
      summary: Create an inbound + resync its node (perm inbound:write)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [node_id, tag, port, protocol]
              properties:
                node_id: {type: string, format: uuid}
                tag: {type: string}
                protocol: {type: string}
                listen: {type: string}
                port: {type: integer}
                network: {type: string}
                security: {type: string}
                sni: {type: array, items: {type: string}}
                path: {type: string}
                host: {type: array, items: {type: string}}
                flow: {type: string}
                raw: {type: object, additionalProperties: true}
                enabled: {type: boolean}
      responses:
        "201": {description: created, content: {application/json: {schema: {type: object, properties: {inbound: {$ref: '#/components/schemas/Inbound'}, warning: {type: string}}}}}}
  /api/inbounds/{id}:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    put:
      tags: [Inbounds]
      summary: Update an inbound + resync (perm inbound:write)
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/Inbound'}}}
      responses:
        "200": {description: updated, content: {application/json: {schema: {type: object, properties: {inbound: {$ref: '#/components/schemas/Inbound'}, warning: {type: string}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}
    delete:
      tags: [Inbounds]
      summary: Delete an inbound + resync (perm inbound:write)
      responses:
        "204": {description: deleted}

  /api/outbounds:
    get:
      tags: [Outbounds]
      summary: List a node's outbounds (perm inbound:read)
      parameters: [{name: node_id, in: query, required: true, schema: {type: string, format: uuid}}]
      responses:
        "200": {description: outbounds, content: {application/json: {schema: {type: object, properties: {outbounds: {type: array, items: {$ref: '#/components/schemas/Outbound'}}}}}}}
    post:
      tags: [Outbounds]
      summary: Create an outbound + resync its node (perm inbound:write)
      description: >
        Egress handler. freedom/blackhole/dns need no endpoint; proxy protocols
        (vmess/vless/trojan/shadowsocks/socks/http) require address+port. The
        well-known tags `direct` (freedom) and `blocked` (blackhole) are always
        synthesized if absent, and `direct` is forced to be the default egress.
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/Outbound'}}}
      responses:
        "201": {description: created, content: {application/json: {schema: {type: object, properties: {outbound: {$ref: '#/components/schemas/Outbound'}, warning: {type: string}}}}}}
        "400": {description: validation error}
  /api/outbounds/{id}:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    put:
      tags: [Outbounds]
      summary: Update an outbound + resync (perm inbound:write)
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/Outbound'}}}
      responses:
        "200": {description: updated, content: {application/json: {schema: {type: object, properties: {outbound: {$ref: '#/components/schemas/Outbound'}, warning: {type: string}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}
    delete:
      tags: [Outbounds]
      summary: Delete an outbound + resync (perm inbound:write)
      responses:
        "204": {description: deleted}

  /api/routing:
    get:
      tags: [Routing]
      summary: List a node's routing rules in priority order (perm inbound:read)
      parameters: [{name: node_id, in: query, required: true, schema: {type: string, format: uuid}}]
      responses:
        "200": {description: rules, content: {application/json: {schema: {type: object, properties: {rules: {type: array, items: {$ref: '#/components/schemas/RoutingRule'}}}}}}}
    post:
      tags: [Routing]
      summary: Create a routing rule + resync (perm inbound:write)
      description: >
        Rules are evaluated in ascending priority. A rule must have at least one
        matcher and exactly one target (outbound_tag XOR balancer_tag).
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/RoutingRule'}}}
      responses:
        "201": {description: created, content: {application/json: {schema: {type: object, properties: {rule: {$ref: '#/components/schemas/RoutingRule'}, warning: {type: string}}}}}}
        "400": {description: validation error}
  /api/routing/{id}:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    put:
      tags: [Routing]
      summary: Update a routing rule + resync (perm inbound:write)
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/RoutingRule'}}}
      responses:
        "200": {description: updated, content: {application/json: {schema: {type: object, properties: {rule: {$ref: '#/components/schemas/RoutingRule'}, warning: {type: string}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}
    delete:
      tags: [Routing]
      summary: Delete a routing rule + resync (perm inbound:write)
      responses:
        "204": {description: deleted}

  /api/balancers:
    get:
      tags: [Balancers]
      summary: List a node's balancers (perm inbound:read)
      parameters: [{name: node_id, in: query, required: true, schema: {type: string, format: uuid}}]
      responses:
        "200": {description: balancers, content: {application/json: {schema: {type: object, properties: {balancers: {type: array, items: {$ref: '#/components/schemas/Balancer'}}}}}}}
    post:
      tags: [Balancers]
      summary: Create a balancer + resync (perm inbound:write)
      description: >
        Distributes traffic across outbounds whose tag matches a selector prefix.
        leastPing/leastLoad (or observe=true) drive an Xray observatory / sing-box
        urltest group that probes members.
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/Balancer'}}}
      responses:
        "201": {description: created, content: {application/json: {schema: {type: object, properties: {balancer: {$ref: '#/components/schemas/Balancer'}, warning: {type: string}}}}}}
        "400": {description: validation error}
  /api/balancers/{id}:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    put:
      tags: [Balancers]
      summary: Update a balancer + resync (perm inbound:write)
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/Balancer'}}}
      responses:
        "200": {description: updated, content: {application/json: {schema: {type: object, properties: {balancer: {$ref: '#/components/schemas/Balancer'}, warning: {type: string}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}
    delete:
      tags: [Balancers]
      summary: Delete a balancer + resync (perm inbound:write)
      responses:
        "204": {description: deleted}

  /api/reality/keypair:
    get:
      tags: [Inbounds]
      summary: Generate a REALITY X25519 keypair + short ID (perm inbound:write)
      description: >
        Returns fresh key material for building a REALITY inbound. Nothing is
        persisted; store the chosen values under the inbound's
        `raw.reality` ({private_key, short_ids, server_names, dest}).
      responses:
        "200":
          description: key material
          content:
            application/json:
              schema:
                type: object
                properties:
                  private_key: {type: string}
                  public_key: {type: string}
                  short_id: {type: string}

  /api/backup:
    get:
      tags: [Backup]
      summary: Export the full proxy configuration (perm admin:manage)
      description: >
        Downloads a portable JSON snapshot of nodes, inbounds, outbounds, routing
        rules, balancers, users (with credentials), and user→inbound bindings.
        Excludes traffic metrics and admin/auth records.
      responses:
        "200":
          description: backup document
          content:
            application/json:
              schema:
                type: object
                properties:
                  version: {type: integer}
                  exported_at: {type: string, format: date-time}
                  nodes: {type: array, items: {$ref: '#/components/schemas/Node'}}
                  inbounds: {type: array, items: {$ref: '#/components/schemas/Inbound'}}
                  outbounds: {type: array, items: {$ref: '#/components/schemas/Outbound'}}
                  routing: {type: array, items: {$ref: '#/components/schemas/RoutingRule'}}
                  balancers: {type: array, items: {$ref: '#/components/schemas/Balancer'}}
                  users: {type: array, items: {$ref: '#/components/schemas/User'}}
                  bindings:
                    type: array
                    items: {type: object, properties: {user_id: {type: string, format: uuid}, inbound_id: {type: string, format: uuid}}}
  /api/backup/restore:
    post:
      tags: [Backup]
      summary: Restore configuration from a snapshot (perm admin:manage)
      description: >
        DESTRUCTIVE. Wipes the current proxy configuration and re-applies the
        posted document in a single transaction. Live cores reconcile when nodes
        next (re)connect. Refuses a document with an unsupported version.
      requestBody:
        required: true
        content: {application/json: {schema: {type: object, description: a document previously returned by GET /api/backup}}}
      responses:
        "200": {description: restored, content: {application/json: {schema: {type: object, properties: {restored: {type: object, additionalProperties: {type: integer}}}}}}}
        "400": {description: invalid or unsupported backup document}

  /api/admins:
    get:
      tags: [Admins]
      summary: List admins (perm admin:manage)
      responses:
        "200": {description: admins, content: {application/json: {schema: {type: object, properties: {admins: {type: array, items: {$ref: '#/components/schemas/Admin'}}}}}}}
    post:
      tags: [Admins]
      summary: Create an admin (perm admin:manage)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username: {type: string}
                password: {type: string}
                sudo: {type: boolean}
                enable_totp: {type: boolean}
      responses:
        "201": {description: created; totp_url present when enable_totp, content: {application/json: {schema: {type: object, properties: {admin: {$ref: '#/components/schemas/Admin'}, totp_url: {type: string}}}}}}
        "409": {description: username taken}
  /api/admins/{id}:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    put:
      tags: [Admins]
      summary: Update an admin (perm admin:manage)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password: {type: string, description: re-hashed only if non-empty}
                sudo: {type: boolean}
                user_quota: {type: integer}
                traffic_quota: {type: integer, format: int64}
                role_id: {type: string, format: uuid, nullable: true}
                disable_totp: {type: boolean}
      responses:
        "200": {description: updated, content: {application/json: {schema: {type: object, properties: {admin: {$ref: '#/components/schemas/Admin'}}}}}}
        "409": {description: cannot demote the last sudo admin}
    delete:
      tags: [Admins]
      summary: Delete an admin (perm admin:manage)
      description: Refuses self-deletion (400) and removing the last sudo admin (409).
      responses:
        "204": {description: deleted}
        "400": {description: cannot delete yourself}
        "409": {description: cannot delete the last sudo admin}
  /api/admins/usage:
    get:
      tags: [Admins]
      summary: List quota usage for all resellers (sudo)
      responses:
        "200":
          description: usage rows
          content:
            application/json:
              schema:
                type: object
                properties:
                  usage:
                    type: array
                    items: {$ref: '#/components/schemas/AdminQuotaUsage'}
  /api/admins/{id}/quota:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    get:
      tags: [Admins]
      summary: Get quota usage for one admin (sudo or self)
      responses:
        "200":
          description: usage
          content:
            application/json:
              schema:
                type: object
                properties:
                  usage: {$ref: '#/components/schemas/AdminQuotaUsage'}
        "403": {description: forbidden}
  /api/admins/{id}/wallet:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    get:
      tags: [Admins]
      summary: Get prepaid wallet and ledger for one admin (sudo or self)
      responses:
        "200":
          description: wallet view
          content:
            application/json:
              schema:
                type: object
                properties:
                  wallet: {$ref: '#/components/schemas/AdminWallet'}
                  ledger:
                    type: array
                    items: {$ref: '#/components/schemas/WalletLedgerEntry'}
        "403": {description: forbidden}
    post:
      tags: [Admins]
      summary: Top up an admin wallet (perm admin:manage)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                traffic_bytes: {type: integer, format: int64}
                user_credits: {type: integer}
                reason: {type: string}
      responses:
        "200": {description: updated wallet}

  /api/roles:
    get:
      tags: [Roles]
      summary: List roles (perm admin:manage)
      responses:
        "200": {description: roles, content: {application/json: {schema: {type: object, properties: {roles: {type: array, items: {$ref: '#/components/schemas/Role'}}}}}}}
    post:
      tags: [Roles]
      summary: Create a role (perm admin:manage)
      requestBody:
        required: true
        content: {application/json: {schema: {type: object, required: [name], properties: {name: {type: string}, permissions: {type: array, items: {type: string}}}}}}
      responses:
        "201": {description: created, content: {application/json: {schema: {type: object, properties: {role: {$ref: '#/components/schemas/Role'}}}}}}

  /sub/{token}:
    get:
      tags: [Subscription]
      security: []
      summary: Fetch a user's subscription (public, token-authenticated)
      description: >
        Response format adapts to the client's User-Agent (Clash YAML, sing-box
        JSON, or base64 share links) and can be forced with `?format=`. In
        addition to `base64`, `clash`, and `singbox`, v1.2.3 adds `xray`
        (raw Xray/V2Ray JSON), `outline` (`ss://` list), and `links` (plain
        V2rayN share links). Unhealthy nodes are pruned. Sets
        `Subscription-Userinfo`, `Profile-Title`, and `Profile-Update-Interval`
        headers. Enforces HWID allowlist / device limit.
      parameters:
        - {name: token, in: path, required: true, schema: {type: string}}
        - {name: format, in: query, schema: {type: string, enum: [base64, clash, singbox, xray, outline, links]}}
        - {name: X-Device-Id, in: header, schema: {type: string}, description: device identifier for device-limit enforcement}
      responses:
        "200":
          description: subscription body
          content:
            text/plain: {schema: {type: string}}
            text/yaml: {schema: {type: string}}
            application/json: {schema: {type: string}}
        "403": {description: device not authorized / device limit reached}
        "404": {description: unknown token}

  /api/sub-hosts:
    get:
      tags: [Subscription Hosts]
      summary: List subscription host overrides (perm inbound:read)
      parameters:
        - {name: inbound_id, in: query, schema: {type: string, format: uuid}, description: filter to one inbound}
      responses:
        "200": {description: hosts in priority order, content: {application/json: {schema: {type: object, properties: {hosts: {type: array, items: {$ref: '#/components/schemas/SubHost'}}}}}}}
        "403": {$ref: '#/components/responses/Forbidden'}
    post:
      tags: [Subscription Hosts]
      summary: Create a subscription host override (perm inbound:write)
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/SubHost'}}}
      responses:
        "201": {description: created, content: {application/json: {schema: {type: object, properties: {host: {$ref: '#/components/schemas/SubHost'}}}}}}
        "400": {description: validation error}
  /api/sub-hosts/{id}:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    put:
      tags: [Subscription Hosts]
      summary: Update a subscription host override (perm inbound:write)
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/SubHost'}}}
      responses:
        "200": {description: updated, content: {application/json: {schema: {type: object, properties: {host: {$ref: '#/components/schemas/SubHost'}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}
    delete:
      tags: [Subscription Hosts]
      summary: Delete a subscription host override (perm inbound:write)
      responses:
        "204": {description: deleted}
        "404": {$ref: '#/components/responses/NotFound'}
  /api/sub-hosts/reorder:
    post:
      tags: [Subscription Hosts]
      summary: Reorder subscription host overrides (perm inbound:write)
      description: Sets the ascending priority of hosts (typically within one inbound) from the supplied ordered id list.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ids]
              properties:
                inbound_id: {type: string, format: uuid}
                ids: {type: array, items: {type: string, format: uuid}, description: host ids in desired order}
      responses:
        "200": {description: reordered, content: {application/json: {schema: {type: object, properties: {hosts: {type: array, items: {$ref: '#/components/schemas/SubHost'}}}}}}}
        "400": {description: validation error}

  /api/routing-packs:
    get:
      tags: [Routing Packs]
      summary: List smart routing rule packs (perm inbound:read)
      responses:
        "200": {description: packs, content: {application/json: {schema: {type: object, properties: {packs: {type: array, items: {$ref: '#/components/schemas/RoutingPack'}}}}}}}
    post:
      tags: [Routing Packs]
      summary: Create a routing pack (perm inbound:write)
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/RoutingPack'}}}
      responses:
        "201": {description: created, content: {application/json: {schema: {type: object, properties: {pack: {$ref: '#/components/schemas/RoutingPack'}}}}}}
        "400": {description: validation error}
  /api/routing-packs/{id}:
    parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
    put:
      tags: [Routing Packs]
      summary: Update a routing pack (perm inbound:write)
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/RoutingPack'}}}
      responses:
        "200": {description: updated, content: {application/json: {schema: {type: object, properties: {pack: {$ref: '#/components/schemas/RoutingPack'}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}
    delete:
      tags: [Routing Packs]
      summary: Delete a routing pack (perm inbound:write)
      responses:
        "204": {description: deleted}
        "404": {$ref: '#/components/responses/NotFound'}
  /api/routing-packs/apply:
    post:
      tags: [Routing Packs]
      summary: Apply a routing pack to a node + resync (perm inbound:write)
      description: Replaces the target node's routing rules with the pack's rules and resyncs its core.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [node_id, pack_id]
              properties:
                node_id: {type: string, format: uuid}
                pack_id: {type: string, format: uuid}
      responses:
        "200": {description: applied, content: {application/json: {schema: {type: object, properties: {applied: {type: integer, description: rules applied}, warning: {type: string}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}
  /api/routing-packs/default:
    put:
      tags: [Routing Packs]
      summary: Set the global default routing pack (perm inbound:write)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [pack_id]
              properties:
                pack_id: {type: string, format: uuid}
      responses:
        "200": {description: default set, content: {application/json: {schema: {type: object, properties: {pack: {$ref: '#/components/schemas/RoutingPack'}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}
  /api/routing-packs/user/{user_id}:
    parameters: [{name: user_id, in: path, required: true, schema: {type: string, format: uuid}}]
    get:
      tags: [Routing Packs]
      summary: Get the routing pack assigned to a user (perm inbound:read)
      responses:
        "200": {description: assignment, content: {application/json: {schema: {type: object, properties: {pack: {$ref: '#/components/schemas/RoutingPack', nullable: true}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}
    put:
      tags: [Routing Packs]
      summary: Assign a routing pack to a user (perm inbound:write)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [pack_id]
              properties:
                pack_id: {type: string, format: uuid}
      responses:
        "200": {description: assigned, content: {application/json: {schema: {type: object, properties: {pack: {$ref: '#/components/schemas/RoutingPack'}}}}}}
        "404": {$ref: '#/components/responses/NotFound'}

  /api/clean-ip/scan:
    post:
      tags: [Clean IP]
      summary: Scan candidate clean IPs (perm node:write)
      description: >
        Probes the supplied Cloudflare/CDN candidate IPs for latency and packet
        loss and scores them. Outbound targets are validated against SSRF (private
        / link-local ranges are rejected).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ips]
              properties:
                ips: {type: array, items: {type: string}, description: candidate IPv4/IPv6 addresses}
                port: {type: integer, description: 'TCP port to probe (default 443)'}
      responses:
        "200": {description: scan results, content: {application/json: {schema: {type: object, properties: {results: {type: array, items: {$ref: '#/components/schemas/CleanIPResult'}}}}}}}
        "400": {description: validation / SSRF rejection}
  /api/clean-ip/results:
    get:
      tags: [Clean IP]
      summary: Latest clean-IP scan results (perm node:read)
      responses:
        "200": {description: results (best score first), content: {application/json: {schema: {type: object, properties: {results: {type: array, items: {$ref: '#/components/schemas/CleanIPResult'}}}}}}}

  /api/ip-limit/policy:
    get:
      tags: [IP Limit]
      summary: Get the IP-limit enforcement policy (perm system:read)
      responses:
        "200": {description: policy, content: {application/json: {schema: {$ref: '#/components/schemas/IPLimitPolicy'}}}}
    put:
      tags: [IP Limit]
      summary: Update the IP-limit enforcement policy (perm admin:manage)
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/IPLimitPolicy'}}}
      responses:
        "200": {description: updated, content: {application/json: {schema: {$ref: '#/components/schemas/IPLimitPolicy'}}}}
        "400": {description: validation error}
  /api/ip-limit/events:
    get:
      tags: [IP Limit]
      summary: Recent IP-limit enforcement events (perm system:read)
      parameters:
        - {name: limit, in: query, schema: {type: integer, default: 100}}
      responses:
        "200": {description: events (newest first), content: {application/json: {schema: {type: object, properties: {events: {type: array, items: {$ref: '#/components/schemas/IPLimitEvent'}}}}}}}

  /api/capabilities:
    get:
      tags: [Capabilities]
      summary: Per-core protocol/transport/security capability matrix (perm inbound:read)
      description: >
        Returns the single source of truth for what each core supports. The
        inbound editor uses this to constrain protocol / transport / security
        choices to the selected node's core.
      responses:
        "200": {description: capability matrix, content: {application/json: {schema: {$ref: '#/components/schemas/Capabilities'}}}}