3x-ui/frontend/src/pages/api-docs/endpoints.ts

export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'WS';
export type ParamLocation =
  | 'path'
  | 'query'
  | 'header'
  | 'body'
  | 'body (form)'
  | 'body (json)'
  | 'body (multipart)';
export type ParamType =
  | 'string'
  | 'integer'
  | 'integer[]'
  | 'number'
  | 'boolean'
  | 'object'
  | 'object[]'
  | 'array'
  | 'file';

export interface EndpointParam {
  name: string;
  in: ParamLocation;
  type: ParamType;
  desc?: string;
  optional?: boolean;
  defaultValue?: string | number | boolean;
}

export interface Endpoint {
  method: HttpMethod;
  path: string;
  summary: string;
  description?: string;
  deprecated?: boolean;
  params?: EndpointParam[];
  body?: string;
  response?: string;
  errorResponse?: string;
  errorStatus?: number;
  responseSchema?: string;
  responseSchemaArray?: boolean;
}

export interface SubscriptionHeader {
  name: string;
  desc: string;
}

export interface Section {
  id: string;
  title: string;
  description?: string;
  subHeader?: SubscriptionHeader[];
  endpoints: Endpoint[];
}

export const sections: readonly Section[] = [
  {
    id: 'authentication',
    title: 'Authentication',
    description:
      'Two authentication modes are supported. UI sessions use a cookie set by the login endpoint. Programmatic clients (bots, scripts, remote panels) authenticate with a Bearer token taken from Settings → Security → API Token. Both work for every endpoint under /panel/api/*.',
    endpoints: [
      {
        method: 'POST',
        path: '/login',
        summary:
          'Authenticate with username + password and receive a session cookie. Required before any cookie-based API call.',
        params: [
          { name: 'username', in: 'body', type: 'string', desc: 'Panel admin username.' },
          { name: 'password', in: 'body', type: 'string', desc: 'Panel admin password.' },
          {
            name: 'twoFactorCode',
            in: 'body',
            type: 'string',
            desc: 'OTP code when 2FA is enabled. Omit otherwise.',
          },
        ],
        body: '{\n  "username": "admin",\n  "password": "admin",\n  "twoFactorCode": "123456"\n}',
        response: '{\n  "success": true,\n  "msg": "Logged in successfully"\n}',
        errorResponse: '{\n  "success": false,\n  "msg": "Wrong username or password"\n}',
      },
      {
        method: 'POST',
        path: '/logout',
        summary: 'Clear the session cookie. Requires the CSRF header for browser sessions.',
        response: '{\n  "success": true\n}',
      },
      {
        method: 'GET',
        path: '/csrf-token',
        summary:
          'Mint a CSRF token for the current session. The SPA replays it in the X-CSRF-Token header on unsafe requests. Bearer-token callers can skip this — the middleware short-circuits CSRF for authenticated API requests.',
        response: '{\n  "success": true,\n  "obj": "csrf-token-string"\n}',
      },
      {
        method: 'POST',
        path: '/getTwoFactorEnable',
        summary:
          'Returns whether 2FA is enabled on the panel — used by the login page to decide whether to show the OTP field.',
        response: '{\n  "success": true,\n  "obj": false\n}',
      },
    ],
  },

  {
    id: 'inbounds',
    title: 'Inbounds',
    description:
      'Manage inbound configurations and their clients. All endpoints live under /panel/api/inbounds and require a logged-in session or Bearer token. Link-generating endpoints honour forwarded headers only when the request comes from a configured trusted proxy.',
    endpoints: [
      {
        method: 'GET',
        path: '/panel/api/inbounds/list',
        summary:
          'List every inbound owned by the authenticated user, including each inbound’s clientStats traffic counters. settings, streamSettings, and sniffing are returned as nested JSON objects (no escaped strings); legacy callers that send them back as JSON-encoded strings are still accepted on write.',
        responseSchema: 'Inbound',
        responseSchemaArray: true,
      },
      {
        method: 'GET',
        path: '/panel/api/inbounds/list/slim',
        summary:
          'Same shape as /list but with settings.clients[] stripped down to {email, enable, comment} and ClientStats not enriched with UUID/SubId. Use this for list pages; fetch /get/:id when you need the full per-client payload (uuid, password, flow, ...).',
        response:
          '{\n  "success": true,\n  "obj": [\n    {\n      "id": 1,\n      "remark": "VLESS-443",\n      "settings": {\n        "clients": [\n          { "email": "alice", "enable": true }\n        ],\n        "decryption": "none"\n      },\n      "clientStats": []\n    }\n  ]\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/inbounds/options',
        summary:
          'Lightweight picker projection of the authenticated user’s inbounds. Returns id, remark, tag, protocol, port, a server-computed tlsFlowCapable flag (true for VLESS on TCP with tls or reality, or on XHTTP with VLESS encryption / vlessenc enabled), and ssMethod (the Shadowsocks cipher, empty for non-Shadowsocks inbounds — used by the client UI to generate a valid Shadowsocks 2022 PSK). Use this for dropdowns and attach pickers — it skips settings, streamSettings, and clientStats so the payload stays small even on panels with thousands of clients.',
        responseSchema: 'InboundOption',
        responseSchemaArray: true,
      },
      {
        method: 'GET',
        path: '/panel/api/inbounds/allLinks',
        summary:
          'Return every protocol URL (vless://, vmess://, trojan://, ss://, hysteria://, mtproto) across all inbounds and all of their clients. Links are rendered through the subscription engine, so the configured remark template (name-only display part) is applied per client — the same output the client info/QR pages use. Protocols without a URL form (socks, http, mixed, wireguard, dokodemo, tunnel) contribute nothing. Used by the panel’s "Export all inbound links" action.',
        response:
          '{\n  "success": true,\n  "obj": [\n    "vless://uuid@host:443?security=reality&...#Germany-alice",\n    "vmess://eyJ2IjoyLC..."\n  ]\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/inbounds/get/:id',
        summary: 'Fetch a single inbound by numeric ID.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Inbound ID.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/add',
        summary:
          'Create a new inbound. Send the full inbound payload (protocol, port, settings, streamSettings, sniffing, remark, expiryTime, total, enable). settings, streamSettings, and sniffing may be sent as nested JSON objects (preferred) or as JSON-encoded strings (legacy).',
        body: '{\n  "enable": true,\n  "remark": "VLESS-443",\n  "listen": "",\n  "port": 443,\n  "protocol": "vless",\n  "expiryTime": 0,\n  "total": 0,\n  "settings": {\n    "clients": [{ "id": "...", "email": "user1" }],\n    "decryption": "none",\n    "fallbacks": []\n  },\n  "streamSettings": {\n    "network": "tcp",\n    "security": "reality",\n    "realitySettings": { "show": false, "dest": "..." }\n  },\n  "sniffing": {\n    "enabled": true,\n    "destOverride": ["http", "tls"]\n  }\n}',
        errorResponse: '{\n  "success": false,\n  "msg": "Port 443 is already in use"\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/del/:id',
        summary: 'Delete an inbound by ID. Also removes its associated client stats rows.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Inbound ID.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/bulkDel',
        summary:
          'Delete many inbounds in one call. Processes the list sequentially; failures are reported per id and the rest still proceed. Restarts xray at most once.',
        body: '{\n  "ids": [1, 2, 3]\n}',
        response:
          '{\n  "success": true,\n  "obj": {\n    "deleted": 2,\n    "skipped": [\n      { "id": 3, "reason": "..." }\n    ]\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/update/:id',
        summary:
          'Replace an inbound’s configuration. Body shape mirrors /add. Heavy on inbounds with thousands of clients — prefer /setEnable for enable-only flips.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Inbound ID.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/setEnable/:id',
        summary:
          'Toggle only the enable flag without serialising the whole settings JSON. Recommended for UI switches on large inbounds.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Inbound ID.' }],
        body: '{\n  "enable": false\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/:id/subSortIndex',
        summary:
          'Set only the subscription sort order. Reads the stored inbound, so a reorder cannot carry a stale client list over a concurrent edit.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Inbound ID.' }],
        body: '{\n  "subSortIndex": 2\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/:id/resetTraffic',
        summary:
          'Zero out upload + download counters for a single inbound. Does not touch per-client counters.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Inbound ID.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/:id/delAllClients',
        summary:
          'Remove every client attached to a single inbound while keeping the inbound itself. Collects emails from settings.clients[] and feeds them into the optimized bulk-delete path (runtime user removal + traffic-row cleanup + SyncInbound). Destructive and cannot be undone.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Inbound ID.' }],
        response: '{\n  "success": true,\n  "obj": {\n    "deleted": 12\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/resetAllTraffics',
        summary:
          'Reset upload + download counters on every inbound. Destructive — accounting history is lost.',
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/import',
        summary:
          'Bulk-import an inbound from a JSON blob (e.g. one exported via the UI). The body uses form encoding with a single "data" field.',
        params: [
          {
            name: 'data',
            in: 'body (form)',
            type: 'string',
            desc: 'JSON-encoded inbound payload.',
          },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/pushClientTraffics',
        summary:
          "Receive a master panel's aggregated per-client usage, keyed by the master's GUID. Stored in a side table used only for the UI display overlay and local quota enforcement — never folded into the local counters that masters poll, so delta accounting stays intact. Called panel-to-panel by the node traffic sync job.",
        params: [
          {
            name: 'masterGuid',
            in: 'body (json)',
            type: 'string',
            desc: 'Stable GUID of the pushing master panel.',
          },
          {
            name: 'traffics',
            in: 'body (json)',
            type: 'object[]',
            desc: 'Client traffic rows; only email/up/down are read.',
          },
        ],
        body: '{\n  "masterGuid": "9f6c2d-…",\n  "traffics": [\n    { "email": "alice", "up": 1048576, "down": 2097152 }\n  ]\n}',
        response: '{\n  "success": true\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/inbounds/:id/fallbacks',
        summary:
          "List the fallback rules attached to a master VLESS/Trojan TCP-TLS inbound. Each rule links one child inbound (the dest) to optional SNI/ALPN/path/dest/xver match criteria. When dest is empty the child inbound's listen+port is used.",
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Master inbound ID.' }],
        response:
          '{\n  "success": true,\n  "obj": [\n    {\n      "id": 1,\n      "masterId": 10,\n      "childId": 11,\n      "name": "",\n      "alpn": "",\n      "path": "/vlws",\n      "dest": "",\n      "xver": 2,\n      "sortOrder": 0\n    }\n  ]\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/inbounds/:id/fallbacks',
        summary:
          'Replace the entire fallback list for a master inbound. Body is JSON. Triggers an Xray restart.',
        params: [
          { name: 'id', in: 'path', type: 'number', desc: 'Master inbound ID.' },
          {
            name: 'fallbacks',
            in: 'body (json)',
            type: 'object[]',
            desc: 'Array of {childId, name, alpn, path, dest, xver, sortOrder} entries. Leave dest empty to auto-resolve from the child inbound\'s listen+port; set it (e.g. "8443", "127.0.0.1:8443", "/dev/shm/x.sock") to override.',
          },
        ],
        body: '{\n  "fallbacks": [\n    { "childId": 11, "path": "/vlws", "xver": 2 },\n    { "childId": 12, "alpn": "h2", "dest": "8443" }\n  ]\n}',
        response: '{\n  "success": true,\n  "msg": "Inbound updated"\n}',
      },
    ],
  },

  {
    id: 'server',
    title: 'Server',
    description:
      'System status, log retrieval, certificate generators, Xray binary management, and backup/restore. All under /panel/api/server.',
    endpoints: [
      {
        method: 'GET',
        path: '/panel/api/openapi.json',
        summary:
          'Serve this API description as an OpenAPI 3 document — the same file that powers the API Docs page. Requires a session or Bearer token like the rest of /panel/api. Useful for generating clients or importing into API tooling.',
      },
      {
        method: 'GET',
        path: '/panel/api/server/status',
        summary:
          'Real-time machine snapshot: CPU, memory, swap, disk, network IO, load averages, open connections, Xray state. Cached and refreshed every 2 seconds in the background.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "cpu": 12.5,\n    "mem": { "current": 2147483648, "total": 8589934592 },\n    "swap": { "current": 0, "total": 4294967296 },\n    "disk": { "current": 53687091200, "total": 268435456000 },\n    "netIO": { "up": 1073741824, "down": 2147483648 },\n    "xray": { "state": "running", "version": "v25.10.31" },\n    "tcpCount": 42,\n    "load": { "load1": 0.5, "load5": 0.3, "load15": 0.2 }\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/server/fail2banStatus',
        summary:
          'Reports whether per-client IP limits can be enforced on this host. The panel uses it to gate the "IP Limit" field, since enforcement depends on Fail2ban being installed.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "enabled": true,\n    "installed": true,\n    "usable": true,\n    "windows": false\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/server/cpuHistory/:bucket',
        summary:
          'Legacy: aggregated CPU history. Use /history/cpu/:bucket instead — same data with a uniform {t, v} shape.',
        params: [
          {
            name: 'bucket',
            in: 'path',
            type: 'number',
            desc: 'Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.',
          },
        ],
      },
      {
        method: 'GET',
        path: '/panel/api/server/history/:metric/:bucket',
        summary:
          'Aggregated time-series for one metric. Returns an array of {t, v} samples covering the last ~6 hours.',
        params: [
          {
            name: 'metric',
            in: 'path',
            type: 'string',
            desc: 'cpu | mem | netUp | netDown | online | load1 | load5 | load15.',
          },
          {
            name: 'bucket',
            in: 'path',
            type: 'number',
            desc: 'Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.',
          },
        ],
        response:
          '{\n  "success": true,\n  "obj": [\n    { "t": 1700000000, "v": 12.5 },\n    { "t": 1700000002, "v": 13.1 }\n  ]\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/server/xrayMetricsState',
        summary:
          'Xray runtime metrics state — whether the xray config has a `metrics` block, which expvar keys are flowing, and the current snapshot values for each. Returns an empty state when metrics are not configured.',
      },
      {
        method: 'GET',
        path: '/panel/api/server/xrayMetricsHistory/:metric/:bucket',
        summary:
          'Time-series history for one Xray runtime metric over the last ~6 hours. Same {t, v} shape as /history/:metric/:bucket.',
        params: [
          {
            name: 'metric',
            in: 'path',
            type: 'string',
            desc: 'xrAlloc | xrSys | xrHeapObjects | xrNumGC | xrPauseNs.',
          },
          {
            name: 'bucket',
            in: 'path',
            type: 'number',
            desc: 'Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.',
          },
        ],
      },
      {
        method: 'GET',
        path: '/panel/api/server/xrayObservatory',
        summary:
          'Latest snapshot from the Xray observatory — per-outbound latency, health status, and last-probe time. Only populated when the Xray config has an observatory configured.',
      },
      {
        method: 'GET',
        path: '/panel/api/server/xrayObservatoryHistory/:tag/:bucket',
        summary:
          'Time-series of observatory probe results for one outbound tag. Same {t, v} shape as the other history endpoints.',
        params: [
          {
            name: 'tag',
            in: 'path',
            type: 'string',
            desc: 'Outbound tag from the observatory config.',
          },
          {
            name: 'bucket',
            in: 'path',
            type: 'number',
            desc: 'Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.',
          },
        ],
      },
      {
        method: 'GET',
        path: '/panel/api/server/getXrayVersion',
        summary: 'List Xray binary versions available for install on this host.',
        response: '{\n  "success": true,\n  "obj": ["v25.10.31", "v25.9.15", "v25.8.1"]\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/server/getPanelUpdateInfo',
        summary: 'Check whether a newer 3x-ui release is available on GitHub.',
      },
      {
        method: 'GET',
        path: '/panel/api/server/getUpdateStatus',
        summary:
          'Report the outcome of the most recently launched panel self-update (see POST updatePanel). Compare the returned runId against the one updatePanel returned to tell this run apart from a stale result.',
        responseSchema: 'PanelUpdateStatus',
      },
      {
        method: 'GET',
        path: '/panel/api/server/getConfigJson',
        summary: 'Return the assembled Xray config that\u2019s currently running on this host.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "log": { "loglevel": "warning" },\n    "inbounds": [...],\n    "outbounds": [...],\n    "routing": { "rules": [...] }\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/server/getDb',
        summary:
          'Stream a full database backup as an attachment: the SQLite .db file on SQLite panels, or a pg_dump custom-format archive (.dump) on PostgreSQL panels. Use as a manual backup.',
      },
      {
        method: 'GET',
        path: '/panel/api/server/getMigration',
        summary:
          'Stream a cross-engine migration file as an attachment: a .dump (SQL text) on SQLite, or a .db SQLite database built from the live data on PostgreSQL.',
      },
      {
        method: 'GET',
        path: '/panel/api/server/getNewUUID',
        summary: 'Generate a fresh UUID v4. Convenience helper for client IDs.',
        response: '{\n  "success": true,\n  "obj": "550e8400-e29b-41d4-a716-446655440000"\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/server/getWebCertFiles',
        summary:
          'Return this panel\'s own web TLS certificate and key file paths. The central panel calls it on a node (via the node API token) so "Set Cert from Panel" fills a node-assigned inbound with paths that exist on the node.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "webCertFile": "/root/cert/example.com/fullchain.pem",\n    "webKeyFile": "/root/cert/example.com/privkey.pem"\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/server/descendants',
        summary:
          'Read-only summaries (guid, parentGuid, name, address, status, versions) of the nodes this panel manages. A parent panel calls it on a node (via the node API token) to surface transitive sub-nodes in a chained topology. Counts are computed by the parent, not returned here.',
        response:
          '{\n  "success": true,\n  "obj": [\n    {\n      "guid": "c3d4-...",\n      "parentGuid": "a1b2-...",\n      "name": "Node3",\n      "address": "10.0.0.3",\n      "status": "online"\n    }\n  ]\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/server/getNewX25519Cert',
        summary: 'Generate a new X25519 keypair for Reality.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "privateKey": "uN9qLfV3zH8w...",\n    "publicKey": "5v8xPqR2sM7k..."\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/server/getNewmldsa65',
        summary:
          'Generate a new ML-DSA-65 keypair (post-quantum signature). Returns {privateKey, publicKey, seed}.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "privateKey": "mdsa65priv...",\n    "publicKey": "mdsa65pub...",\n    "seed": "random-seed..."\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/server/getNewmlkem768',
        summary:
          'Generate a new ML-KEM-768 keypair (post-quantum KEM). Returns {clientKey, serverKey}.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "clientKey": "mlkem768-client...",\n    "serverKey": "mlkem768-server..."\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/server/getNewVlessEnc',
        summary:
          'Generate VLESS encryption auth options. Returns an auths array each with id, label, encryption, and decryption fields.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "auths": [\n      { "id": 0, "label": "Auth #0", "encryption": "aes-256-gcm", "decryption": "" }\n    ]\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/server/stopXrayService',
        summary: 'Stop the Xray binary. All proxies go offline immediately.',
        errorResponse: '{\n  "success": false,\n  "msg": "Xray is not running"\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/server/restartXrayService',
        summary:
          'Reload Xray with the current config. Typically required after structural inbound or routing changes.',
        errorResponse: '{\n  "success": false,\n  "msg": "Xray config is invalid: ..."\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/server/installXray/:version',
        summary:
          'Download and install the specified Xray version. Pass "latest" for the newest release.',
        params: [
          {
            name: 'version',
            in: 'path',
            type: 'string',
            desc: 'Xray tag (e.g. v25.10.31) or "latest".',
          },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/server/updatePanel',
        summary: 'Self-update the panel to the latest version. The server restarts on success.',
        response: '{\n  "success": true,\n  "obj": {\n    "runId": "1735689600123456789"\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/server/setUpdateChannel',
        summary:
          'Toggle the panel update channel between stable and the rolling per-commit dev release. Only effective on dev builds.',
        params: [
          {
            name: 'dev',
            in: 'body (form)',
            type: 'boolean',
            desc: 'true = dev channel, false = stable.',
          },
        ],
        body: 'dev=true',
      },
      {
        method: 'POST',
        path: '/panel/api/server/updateGeofile',
        summary:
          'Refresh the default GeoIP / GeoSite data files. Body can include a fileName, or use the /:fileName variant.',
        params: [
          {
            name: 'fileName',
            in: 'body (form)',
            type: 'string',
            desc: 'Filename to update (e.g. geoip.dat, geosite.dat). Omit to update all defaults.',
          },
        ],
        body: 'fileName=geoip.dat',
      },
      {
        method: 'POST',
        path: '/panel/api/server/updateGeofile/:fileName',
        summary: 'Refresh a single Geo file by filename (e.g. geoip.dat, geosite.dat).',
        params: [
          {
            name: 'fileName',
            in: 'path',
            type: 'string',
            desc: 'Filename of the data file to refresh.',
          },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/server/logs/:count',
        summary: 'Return the last N lines of the panel\u2019s own log.',
        params: [
          { name: 'count', in: 'path', type: 'number', desc: 'Number of trailing log lines.' },
        ],
        body: '{\n  "level": "info",\n  "syslog": false\n}',
        response:
          '{\n  "success": true,\n  "obj": "2025/01/01 12:00:00 [INFO] Server started\\n2025/01/01 12:00:01 [INFO] Xray is running"\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/server/xraylogs/:count',
        summary: 'Return the last N lines of the Xray process log.',
        params: [
          { name: 'count', in: 'path', type: 'number', desc: 'Number of trailing log lines.' },
          {
            name: 'filter',
            in: 'body (form)',
            type: 'string',
            desc: 'Keyword filter — only lines containing this string.',
          },
          {
            name: 'showDirect',
            in: 'body (form)',
            type: 'string',
            desc: '"true" to include direct (freedom) traffic lines.',
          },
          {
            name: 'showBlocked',
            in: 'body (form)',
            type: 'string',
            desc: '"true" to include blocked (blackhole) traffic lines.',
          },
          {
            name: 'showProxy',
            in: 'body (form)',
            type: 'string',
            desc: '"true" to include proxy traffic lines.',
          },
        ],
        body: 'filter=error&showDirect=false&showBlocked=true&showProxy=true',
        response:
          '{\n  "success": true,\n  "obj": "2025/01/01 12:00:00 rejected  vless  proxy  example.com  reason: no valid user\\n2025/01/01 12:00:01 direct  freedom  ok"\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/server/amneziawglogs/:count',
        summary:
          'Return live AmneziaWG peer activity (handshake, endpoint, transfer) plus the panel’s own AmneziaWG event lines.',
        params: [
          {
            name: 'count',
            in: 'path',
            type: 'number',
            desc: 'Maximum peer rows and event lines to return.',
          },
          {
            name: 'filter',
            in: 'body (form)',
            type: 'string',
            desc: 'Keyword filter — only rows/lines containing this string.',
          },
        ],
        body: 'filter=awg1',
        responseSchema: 'AmneziaWGLogs',
      },
      {
        method: 'POST',
        path: '/panel/api/server/importDB',
        summary:
          'Restore the panel DB from an uploaded backup (multipart form, field name "db"). SQLite panels accept a SQLite database (.db) or a SQLite migration dump (.dump); PostgreSQL panels accept a pg_dump archive (.dump), a SQLite database (.db), or a SQLite migration dump. The panel restarts after restore. Destructive.',
        params: [
          {
            name: 'db',
            in: 'body (multipart)',
            type: 'file',
            desc: 'Database backup or migration file to upload.',
          },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/server/getNewEchCert',
        summary:
          'Generate a new ECH (Encrypted Client Hello) keypair and config list for the given SNI.',
        params: [
          {
            name: 'sni',
            in: 'body (form)',
            type: 'string',
            desc: 'Server Name Indication to generate the ECH config for.',
          },
        ],
        body: 'sni=example.com',
        response:
          '{\n  "success": true,\n  "obj": {\n    "echKeySet": "...",\n    "echServerKeys": [...],\n    "echConfigList": "..."\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/server/getCertHash',
        summary:
          'Compute the hex SHA-256 of a certificate (DER) for pinning (pinnedPeerCertSha256). Provide either a server file path or inline PEM/DER content.',
        params: [
          {
            name: 'certFile',
            in: 'body (form)',
            type: 'string',
            desc: 'Path to a certificate file on the server. Takes precedence over certContent.',
          },
          {
            name: 'certContent',
            in: 'body (form)',
            type: 'string',
            desc: 'Inline PEM (or DER) certificate content, used when certFile is empty.',
          },
        ],
        body: 'certFile=/root/cert.crt',
        response: '{\n  "success": true,\n  "obj": [\n    "e8e2d3..."\n  ]\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/server/getRemoteCertHash',
        summary:
          'Run `xray tls ping` against a remote server and return its live leaf-certificate SHA-256 hash(es) for pinning (pinnedPeerCertSha256).',
        params: [
          {
            name: 'server',
            in: 'body (form)',
            type: 'string',
            desc: 'Remote server as domain or domain:port (default port 443), e.g. cloudflare-dns.com.',
          },
        ],
        body: 'server=cloudflare-dns.com',
        response: '{\n  "success": true,\n  "obj": [\n    "e8e2d3..."\n  ]\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/server/scanRealityTarget',
        summary:
          'Run a live TLS 1.3 probe against a candidate REALITY target and return a feasibility verdict (TLS 1.3 + h2 + X25519 + trusted certificate) plus the certificate SAN DNS names. A target on a private/loopback address is reported with privateTarget=true and probed only when allowPrivate is set.',
        params: [
          {
            name: 'target',
            in: 'body (form)',
            type: 'string',
            desc: 'Candidate target as host or host:port (default port 443), e.g. www.cloudflare.com:443.',
          },
          {
            name: 'sni',
            in: 'body (form)',
            type: 'string',
            optional: true,
            desc: 'SNI the handshake sends and the certificate is verified against (the inbound serverNames). Defaults to the target host, which a fronting proxy answers with its default certificate.',
          },
          {
            name: 'xver',
            in: 'body (form)',
            type: 'number',
            optional: true,
            desc: 'PROXY protocol version the target expects (matches the inbound xver). 0 = none.',
          },
          {
            name: 'allowPrivate',
            in: 'body (form)',
            type: 'boolean',
            optional: true,
            desc: 'Probe a private/internal/loopback target (LAN, Docker service name). Default false (SSRF guard blocks it and the response sets privateTarget=true).',
          },
        ],
        body: 'target=www.cloudflare.com:443',
        responseSchema: 'RealityScanResult',
      },
      {
        method: 'POST',
        path: '/panel/api/server/scanRealityTargets',
        summary:
          'Probe/discover REALITY targets and return each verdict ranked by feasibility then latency. Each comma-separated token may be a domain (validated with SNI), a bare IP, or a CIDR range (discovered without SNI by reading the certificate domain). When empty, a built-in seed list is probed.',
        params: [
          {
            name: 'targets',
            in: 'body (form)',
            type: 'string',
            optional: true,
            desc: 'Optional comma-separated tokens: domain[:port], IP[:port], or CIDR (e.g. 104.16.0.0/24). When omitted, a built-in seed list is probed.',
          },
        ],
        body: 'targets=104.16.0.0/24,www.apple.com:443',
        responseSchema: 'RealityScanResult',
        responseSchemaArray: true,
      },
      {
        method: 'GET',
        path: '/panel/api/server/clientIps',
        summary:
          'Fetch the fully aggregated inbound_client_ips database table. Used by nodes to sync recently active IPs across the cluster.',
        responseSchema: 'InboundClientIps',
        responseSchemaArray: true,
      },
      {
        method: 'POST',
        path: '/panel/api/server/clientIps',
        summary:
          'Submit a list of recently active IP timestamps. The panel merges them with the existing database to maintain a unified global IP-limit view.',
        params: [
          {
            name: 'ips',
            in: 'body (json)',
            type: 'object[]',
            desc: 'Array of InboundClientIps to merge.',
          },
        ],
      },
    ],
  },

  {
    id: 'clients',
    title: 'Clients',
    description:
      'Manage clients as first-class entities that can be attached to one or more inbounds. A single client row drives the settings.clients entry in every inbound it belongs to. Endpoints live under /panel/api/clients.',
    endpoints: [
      {
        method: 'GET',
        path: '/panel/api/clients/list',
        summary:
          'List every client with its attached inbound IDs and traffic record. The reverse field, if set, is returned as a nested JSON object (legacy JSON-encoded-string form is still accepted on write).',
        response:
          '{\n  "success": true,\n  "obj": [\n    {\n      "id": 1,\n      "email": "alice@example.com",\n      "subId": "abcd1234",\n      "uuid": "...",\n      "totalGB": 53687091200,\n      "expiryTime": 1735689600000,\n      "enable": true,\n      "reverse": null,\n      "inboundIds": [3, 5],\n      "traffic": { "up": 1024, "down": 4096, "enable": true }\n    }\n  ]\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/clients/list/paged',
        summary:
          'Filter, sort, and paginate clients on the server. Each item is a slim row (no uuid/password/auth/flow/security/reverse/tgId) so the clients page can ship 25-ish rows in a few KB instead of the full table. The response also includes a summary computed across the full DB row set so dashboard counters stay stable as the user paginates or filters: the *Count fields are exact, while the email arrays beside them stop at 200 entries so the payload does not grow with the panel. Page size capped at 200; fetch /get/:email to obtain the full per-client payload for an edit/info modal.',
        params: [
          {
            name: 'page',
            in: 'query',
            type: 'number',
            desc: '1-indexed page number. Defaults to 1.',
          },
          {
            name: 'pageSize',
            in: 'query',
            type: 'number',
            desc: 'Rows per page. Defaults to 25, capped at 200.',
          },
          {
            name: 'search',
            in: 'query',
            type: 'string',
            desc: 'Case-insensitive substring match on email / subId / comment.',
          },
          {
            name: 'filter',
            in: 'query',
            type: 'string',
            desc: 'Status bucket: online | active | deactive | depleted | expiring.',
          },
          {
            name: 'protocol',
            in: 'query',
            type: 'string',
            desc: 'Match clients attached to at least one inbound of this protocol (vless, vmess, trojan, shadowsocks, ...).',
          },
          {
            name: 'sort',
            in: 'query',
            type: 'string',
            desc: 'Sort key: enable | email | inboundIds | traffic | remaining | expiryTime.',
          },
          { name: 'order', in: 'query', type: 'string', desc: 'ascend or descend.' },
        ],
        response:
          '{\n  "success": true,\n  "obj": {\n    "items": [\n      {\n        "email": "alice@example.com",\n        "subId": "abcd1234",\n        "enable": true,\n        "totalGB": 53687091200,\n        "expiryTime": 1735689600000,\n        "limitIp": 0,\n        "limitHwid": 0,\n        "reset": 0,\n        "inboundIds": [3, 5],\n        "traffic": { "up": 1024, "down": 4096, "enable": true },\n        "createdAt": 1735000000000,\n        "updatedAt": 1735100000000\n      }\n    ],\n    "total": 2000,\n    "filtered": 47,\n    "page": 1,\n    "pageSize": 25,\n    "summary": {\n      "total": 2000,\n      "active": 1850,\n      "onlineCount": 1,\n      "depletedCount": 0,\n      "expiringCount": 0,\n      "deactiveCount": 150,\n      "online": ["alice@example.com"],\n      "depleted": [],\n      "expiring": [],\n      "deactive": ["bob@example.com"]\n    }\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/clients/get/:email',
        summary:
          'Fetch one client by email, including the inbound IDs and external config IDs it is attached to.',
        params: [
          { name: 'email', in: 'path', type: 'string', desc: 'Client email (unique identifier).' },
        ],
        response:
          '{\n  "success": true,\n  "obj": {\n    "client": { "id": 1, "email": "alice@example.com", ... },\n    "inboundIds": [3, 5],\n    "externalLinks": [\n      { "id": 11, "kind": "link", "value": "vless://...", "remark": "DE", "enable": true, "expiryTime": 0 },\n      { "id": 12, "kind": "subscription", "value": "https://provider.example/sub/abc", "remark": "Provider", "enable": false, "expiryTime": 1767225600000, "namePrefix": "[zjh] ", "lastFetchAt": 1767220000000, "lastFetchError": "" }\n    ]\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/clients/get/tgId/:tgId',
        summary:
          'Fetch clients by Telegram user ID. Returns an array since multiple clients can share the same Telegram ID.',
        params: [
          { name: 'tgId', in: 'path', type: 'integer', desc: 'Telegram user ID (numeric).' },
        ],
        response:
          '{\n  "success": true,\n  "obj": [\n    {\n      "client": { "id": 1, "email": "alice@example.com", ... },\n      "inboundIds": [3, 5],\n      "externalLinks": [],\n      "usedTraffic": 1048576\n    }\n  ]\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/add',
        summary:
          'Create a new client and attach it to one or more inbounds in a single call. Body is JSON. Per-protocol secrets are generated server-side when omitted, so callers can send only the universal fields.',
        description:
          'Fields the server fills in when they are omitted — a valid value sent by the caller is never overwritten. Re-adding an email that already exists, with its stored `subId`, reuses the stored `id`, `password`, `auth` and `secret` instead of minting new ones, so the identity stays in sync across its inbounds.\n\n- **VLESS / VMess** — `id`, a fresh UUID\n- **Trojan** — `password`\n- **Shadowsocks** — `password`. On a `2022-blake3-*` inbound a supplied password that does not base64-decode to the key length of the cipher (16 or 32 bytes) is replaced by a generated key and the call still succeeds, so read the client back if you did not let the server pick. Legacy ciphers keep any non-empty password\n- **Hysteria** — `auth`\n- **mtproto** — `secret`, a FakeTLS secret derived from the fronting domain of the inbound, or from `www.cloudflare.com` when it has none\n- **WireGuard** — `privateKey` and `publicKey` when both are blank, or `publicKey` alone when only a `privateKey` was sent, plus `allowedIPs`: one free `/32` taken from the /24 the existing peers of that inbound already sit in, or from `10.0.0.0/24` when it has none\n\nAccepted on the same body but never generated: `preSharedKey` and `keepAlive` (WireGuard), `adTag` (mtproto).\n\nWireGuard is the only one of these that can fail. Allocation widens the search to the containing /16 before giving up with `wireguard: no free address available in <scope>`, and an `allowedIPs` supplied by the caller is validated instead of allocated: `wireguard: allowedIPs entry already used by another client: <address>` when a different client of that same inbound already holds it. The check is per inbound, so the same address on two different inbounds is accepted. The same validation runs on POST /panel/api/clients/{email}/attach, where a client that already carries an address brings it along.',
        params: [
          {
            name: 'client',
            in: 'body (json)',
            type: 'object',
            desc: 'Client fields: email, subId, id (uuid), password, auth, flow, totalGB, expiryTime, limitIp, limitHwid, tgId (numeric Telegram user ID, 0 = none), comment, enable. Protocol-specific: secret and adTag (mtproto), privateKey, publicKey, preSharedKey, allowedIPs and keepAlive (WireGuard).',
          },
          {
            name: 'inboundIds',
            in: 'body (json)',
            type: 'integer[]',
            desc: 'Inbound IDs to attach the client to. At least one required.',
          },
        ],
        body: '{\n  "client": {\n    "email": "alice@example.com",\n    "totalGB": 53687091200,\n    "expiryTime": 1735689600000,\n    "tgId": 0,\n    "limitIp": 0,\n    "limitHwid": 0,\n    "enable": true\n  },\n  "inboundIds": [3, 5]\n}',
        response: '{\n  "success": true,\n  "msg": "Client added"\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/update/:email',
        summary:
          'Update an existing client by email. Changes propagate to every attached inbound. Body is the JSON client payload — supply the full set of fields you want to keep (the server replaces the row, it does not patch).',
        params: [
          {
            name: 'email',
            in: 'path',
            type: 'string',
            desc: 'Current client email (unique identifier).',
          },
        ],
        body: '{\n  "email": "alice@example.com",\n  "totalGB": 107374182400,\n  "expiryTime": 1767225600000,\n  "limitHwid": 2,\n  "tgId": 123456789,\n  "enable": true\n}',
        response: '{\n  "success": true,\n  "msg": "Client updated"\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/del/:email',
        summary:
          'Delete a client by email. Removes it from every attached inbound and drops its traffic record unless keepTraffic=1 is passed.',
        params: [
          { name: 'email', in: 'path', type: 'string', desc: 'Client email (unique identifier).' },
          {
            name: 'keepTraffic',
            in: 'query',
            type: 'integer',
            desc: 'Pass 1 to retain the xray_client_traffic row after deletion.',
          },
        ],
        response: '{\n  "success": true,\n  "msg": "Client deleted"\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/:email/attach',
        summary: 'Attach an existing client to one or more additional inbounds. Body is JSON.',
        description:
          'A WireGuard client brings its stored `allowedIPs` into the new inbound instead of being given a fresh address, so the call fails with `wireguard: allowedIPs entry already used by another client: <address>` when a different client of the target inbound already holds it. Free the address on that inbound first — see POST /panel/api/clients/add for the full rule.',
        params: [
          { name: 'email', in: 'path', type: 'string', desc: 'Client email (unique identifier).' },
          {
            name: 'inboundIds',
            in: 'body (json)',
            type: 'integer[]',
            desc: 'Inbound IDs to attach.',
          },
        ],
        body: '{\n  "inboundIds": [7, 9]\n}',
        response: '{\n  "success": true\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/:email/detach',
        summary: 'Detach a client from one or more inbounds without deleting the client.',
        params: [
          { name: 'email', in: 'path', type: 'string', desc: 'Client email (unique identifier).' },
          {
            name: 'inboundIds',
            in: 'body (json)',
            type: 'integer[]',
            desc: 'Inbound IDs to detach.',
          },
        ],
        body: '{\n  "inboundIds": [5]\n}',
        response: '{\n  "success": true\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/:email/externalLinks',
        summary:
          "Replace a client's external links and external subscriptions. Sends the full set; the server replaces all rows. Disabled rows stay saved for editing but are not emitted in generated subscriptions.",
        params: [
          { name: 'email', in: 'path', type: 'string', desc: 'Client email (unique identifier).' },
          {
            name: 'externalLinks',
            in: 'body',
            type: 'object[]',
            desc: 'Full replacement list; the server replaces all rows. Each row supports { kind, value, remark, enable, expiryTime, namePrefix }. kind=link: value must be a supported share link such as vless://, vmess://, trojan://, ss://, hysteria2://, or wireguard://, and remark overrides the exported node name. kind=subscription: value must be an http(s) subscription URL, and namePrefix is prepended to fetched node names. Omit enable to default true; enable=false or an expired expiryTime keeps the row saved but excludes it from generated subscriptions. expiryTime is a unix millisecond timestamp where 0 means never expire; a negative value is rejected. Rows are matched by kind+value across saves, so id is ignored on write. lastFetchAt and lastFetchError are read-only status fields returned by GET.',
          },
        ],
        body: '{\n  "externalLinks": [\n    { "kind": "link", "value": "vless://uuid@host:443?...#srv", "remark": "DE", "enable": true, "expiryTime": 0 },\n    { "kind": "subscription", "value": "https://provider.example/sub/abc", "remark": "Provider", "enable": false, "expiryTime": 1767225600000, "namePrefix": "[zjh] " }\n  ]\n}',
        response: '{\n  "success": true\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/resetAllTraffics',
        summary:
          'Reset the up/down counters for every client globally. Quotas and expiry are not affected. Triggers an Xray restart if any counter actually moved.',
        response: '{\n  "success": true\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/delDepleted',
        summary:
          'Delete every client whose traffic quota is exhausted (used >= total, when reset is disabled) or whose expiry has passed. Returns the deleted count and triggers an Xray restart when any client was on a running inbound.',
        response: '{\n  "success": true,\n  "obj": {\n    "deleted": 0\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/delOrphans',
        summary:
          'Delete every client that is not attached to any inbound, along with its traffic record, IP log, HWID devices, and external links. Useful for clearing clients left unattached after their inbounds were removed. Returns the deleted count. Cannot be undone.',
        response: '{\n  "success": true,\n  "obj": {\n    "deleted": 0\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/clients/export',
        summary:
          'Return every client as a {client, inboundIds} array — the same shape /bulkCreate and /import accept — so the payload round-trips straight back through /import. Clients with no inbound attachment are included with an empty inboundIds list. The UI shows this in a CodeMirror viewer (copy / download); programmatic callers get the array in obj.',
        response:
          '{\n  "success": true,\n  "obj": [\n    {\n      "client": {\n        "email": "alice@example.com",\n        "id": "...",\n        "totalGB": 53687091200,\n        "expiryTime": 0,\n        "limitHwid": 2,\n        "enable": true,\n        "subId": "..."\n      },\n      "inboundIds": [7, 9]\n    }\n  ]\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/import',
        summary:
          'Import clients from a JSON body { "data": "<json>" }, where data is a string-encoded array produced by /export ([{client, inboundIds}]). Items with inboundIds are created and attached to those inbounds; items with an empty inboundIds list are restored as unattached client records. Existing emails are never overwritten — they are returned in skipped. Triggers a single Xray restart at the end if any target inbound was running.',
        body: '{\n  "data": "[{\\"client\\":{\\"email\\":\\"alice@example.com\\",\\"enable\\":true},\\"inboundIds\\":[7]}]"\n}',
        response:
          '{\n  "success": true,\n  "obj": {\n    "created": 2,\n    "skipped": [\n      { "email": "alice@example.com", "reason": "email already in use: alice@example.com" }\n    ]\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/bulkAdjust',
        summary:
          'Shift expiry and/or traffic quota for many clients in one call. addDays/addBytes may be negative. Clients with unlimited expiry (expiryTime=0) or unlimited traffic (totalGB=0) are skipped for the corresponding field — bulk extend never converts unlimited to limited. A client that was auto-disabled solely because it was depleted (expired or over quota) is automatically re-enabled — locally and on its node — when the adjustment lifts it out of depletion; a manually-disabled or still-depleted client is left disabled. The optional flow directive sets the XTLS flow on every client: "none" clears it, "xtls-rprx-vision"/"xtls-rprx-vision-udp443" set it where the inbound supports it (omit or "" to leave it unchanged). Returns the adjusted count and per-email skip reasons.',
        body: '{\n  "emails": ["alice", "bob"],\n  "addDays": 30,\n  "addBytes": 53687091200,\n  "flow": "xtls-rprx-vision"\n}',
        response:
          '{\n  "success": true,\n  "obj": {\n    "adjusted": 2,\n    "skipped": [\n      { "email": "carol", "reason": "unlimited expiry" }\n    ]\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/bulkEnable',
        summary:
          'Enable many clients in one call. Emails are grouped by inbound and applied with a single read-modify-write per inbound; the running Xray (local or remote node) is updated to add each user. Note that enabling a client whose quota is exhausted or whose expiry has passed only flips the flag — the traffic loop will disable it again on the next tick. Returns the changed count and per-email skip reasons.',
        body: '{\n  "emails": ["alice", "bob"]\n}',
        response:
          '{\n  "success": true,\n  "obj": {\n    "changed": 2,\n    "skipped": [\n      { "email": "carol", "reason": "client not found" }\n    ]\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/bulkDisable',
        summary:
          'Disable many clients in one call. Emails are grouped by inbound and applied with a single read-modify-write per inbound; the running Xray (local or remote node) is updated to remove each user. Returns the changed count and per-email skip reasons.',
        body: '{\n  "emails": ["alice", "bob"]\n}',
        response:
          '{\n  "success": true,\n  "obj": {\n    "changed": 2,\n    "skipped": [\n      { "email": "carol", "reason": "client not found" }\n    ]\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/bulkDel',
        summary:
          'Delete many clients in one call. The server processes the list sequentially so each delete sees the committed state of the previous one — avoids the race the per-email fan-out had on the panel side. Pass keepTraffic=true to retain the xray_client_traffic rows after deletion.',
        body: '{\n  "emails": ["alice", "bob"],\n  "keepTraffic": false\n}',
        response:
          '{\n  "success": true,\n  "obj": {\n    "deleted": 2,\n    "skipped": [\n      { "email": "carol", "reason": "client not found" }\n    ]\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/bulkCreate',
        summary:
          'Create many clients in one call. Body is a JSON array of {client, inboundIds} payloads — the same shape /add accepts. Items are processed sequentially; per-email skip reasons are returned for items that fail (e.g., duplicate email). Triggers a single Xray restart at the end if any inbound was running.',
        body: '[\n  {\n    "client": {\n      "email": "alice@example.com",\n      "totalGB": 53687091200,\n      "expiryTime": 0,\n      "limitHwid": 2,\n      "enable": true\n    },\n    "inboundIds": [7]\n  },\n  {\n    "client": {\n      "email": "bob@example.com",\n      "totalGB": 53687091200,\n      "expiryTime": 0,\n      "limitHwid": 0,\n      "enable": true\n    },\n    "inboundIds": [7, 9]\n  }\n]',
        response:
          '{\n  "success": true,\n  "obj": {\n    "created": 2,\n    "skipped": [\n      { "email": "alice@example.com", "reason": "email already in use" }\n    ]\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/groups/bulkAdd',
        summary:
          "Add many clients to a group in one call. Updates clients.group_name and patches the matching client entry inside every owning inbound's settings JSON in a single transaction. If the group name does not yet exist (in client_groups or as a derived label), it is auto-created as a persistent group. To clear the group label, use /groups/bulkRemove instead.",
        body: '{\n  "emails": ["alice", "bob"],\n  "group": "customer-a"\n}',
        response: '{\n  "success": true,\n  "obj": {\n    "affected": 2\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/groups/bulkRemove',
        summary:
          "Clear the group label on many clients in one call. Inverse of /groups/bulkAdd. Clients themselves are kept — only the group label is cleared from clients.group_name and from each owning inbound's settings JSON. Groups become empty if all their members are removed.",
        body: '{\n  "emails": ["alice", "bob"]\n}',
        response: '{\n  "success": true,\n  "obj": {\n    "affected": 2\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/bulkAttach',
        summary:
          'Attach many existing clients to many inbounds in one call. Each client keeps its identity (email/UUID/password/subId) and a shared traffic row; all clients are added to a target inbound in a single AddInboundClient call. Clients already present on a target are reported under skipped. Returns per-email attached/skipped/errors lists and triggers a single Xray restart if any target inbound was running.',
        params: [
          {
            name: 'emails',
            in: 'body (json)',
            type: 'array',
            desc: 'Emails of existing clients to attach.',
          },
          {
            name: 'inboundIds',
            in: 'body (json)',
            type: 'integer[]',
            desc: 'Target inbound IDs to attach every client to.',
          },
        ],
        body: '{\n  "emails": ["alice", "bob"],\n  "inboundIds": [7, 9]\n}',
        response:
          '{\n  "success": true,\n  "obj": {\n    "attached": ["alice", "bob"],\n    "skipped": ["bob"],\n    "errors": []\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/bulkDetach',
        summary:
          "Mirror of bulkAttach: detach many existing clients from many inbounds in one call. For each email, intersects the client's current inbounds with the requested set and detaches from those only; (email, inbound) pairs where the client is not currently attached are silently no-ops. Emails not attached to any of the requested inbounds are reported under skipped. Client records are kept even if they become orphaned — use bulkDel for full removal. Returns per-email detached/skipped/errors lists and triggers a single Xray restart if any target inbound was running.",
        params: [
          {
            name: 'emails',
            in: 'body (json)',
            type: 'array',
            desc: 'Emails of existing clients to detach.',
          },
          {
            name: 'inboundIds',
            in: 'body (json)',
            type: 'integer[]',
            desc: 'Inbound IDs to detach the clients from.',
          },
        ],
        body: '{\n  "emails": ["alice", "bob"],\n  "inboundIds": [7, 9]\n}',
        response:
          '{\n  "success": true,\n  "obj": {\n    "detached": ["alice", "bob"],\n    "skipped": [],\n    "errors": []\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/bulkResetTraffic',
        summary:
          'Zero up/down counters for many clients in one call. Loops the single-reset path so each client is re-enabled across its attached inbounds and pushed to Xray/remote nodes. Returns the count of successfully reset clients.',
        body: '{\n  "emails": ["alice", "bob"]\n}',
        response: '{\n  "success": true,\n  "obj": {\n    "affected": 2\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/clients/groups',
        summary:
          'List all client groups with their member counts. Merges persisted groups (rows in client_groups, including empty placeholders) with the distinct group_name values currently set on clients. Sorted alphabetically (case-insensitive).',
        response:
          '{\n  "success": true,\n  "obj": [\n    { "name": "customer-a", "clientCount": 5 },\n    { "name": "internal", "clientCount": 0 }\n  ]\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/clients/groups/:name/emails',
        summary:
          'Return just the email list of clients that currently belong to the given group. Useful for fanning a single bulk action over an entire group without round-tripping the full client list.',
        params: [{ name: 'name', in: 'path', type: 'string', desc: 'Group name (URL-encoded).' }],
        response: '{\n  "success": true,\n  "obj": ["alice", "bob", "carol"]\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/groups/create',
        summary:
          'Create a new empty (placeholder) group. The group becomes selectable in client forms and the filter drawer even before any client is added to it. Errors if a group with the same name already exists.',
        body: '{\n  "name": "customer-a"\n}',
        response: '{\n  "success": true,\n  "obj": {\n    "name": "customer-a"\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/groups/rename',
        summary:
          "Rename a group. The new name is applied to the client_groups row AND propagated to every matching client (both clients.group_name and the client entry inside every owning inbound's settings JSON) in a single transaction. Returns the number of clients whose label was updated.",
        body: '{\n  "oldName": "customer-a",\n  "newName": "tier-1"\n}',
        response: '{\n  "success": true,\n  "obj": {\n    "affected": 5\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/groups/delete',
        summary:
          'Remove a group. Deletes the client_groups row and clears the group label from every matching client (both clients.group_name and the inbound settings JSON). The clients themselves are NOT deleted — use /bulkDel after filtering by group for that. Returns the count of clients whose label was cleared.',
        body: '{\n  "name": "customer-a"\n}',
        response: '{\n  "success": true,\n  "obj": {\n    "affected": 5\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/groups/resetTraffic',
        summary:
          "Reset only the group-level traffic counter shown on the groups page. Snapshots the current up/down sum of the group's members as a baseline so the group total reads zero, while leaving each client's own counters (and their quotas) untouched. No Xray restart is triggered. Creates the client_groups row if the group exists only as a derived label.",
        body: '{\n  "name": "customer-a"\n}',
        response: '{\n  "success": true,\n  "obj": {\n    "name": "customer-a"\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/resetTraffic/:email',
        summary:
          'Zero out a single client’s up/down counters. Re-enables the client across every attached inbound and pushes the change to Xray (or the remote node) so depleted users can connect again immediately.',
        params: [{ name: 'email', in: 'path', type: 'string', desc: 'Client email.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/clients/updateTraffic/:email',
        summary:
          'Manually adjust a client’s upload + download counters. Useful for migrations from external accounting systems.',
        params: [{ name: 'email', in: 'path', type: 'string', desc: 'Client email.' }],
        body: '{\n  "upload": 1073741824,\n  "download": 5368709120\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/ips/:email',
        summary:
          'List source IPs that have connected with the given client’s credentials. Returns an array of "ip (timestamp)" strings.',
        params: [{ name: 'email', in: 'path', type: 'string', desc: 'Client email.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/clients/clearIps/:email',
        summary: 'Reset the recorded IP list for a client.',
        params: [{ name: 'email', in: 'path', type: 'string', desc: 'Client email.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/clients/hwids/:email',
        summary: 'List registered HWID devices for a client. Hashes are not exposed.',
        params: [{ name: 'email', in: 'path', type: 'string', desc: 'Client email.' }],
        response:
          '{\n  "success": true,\n  "obj": [\n    {\n      "id": 1,\n      "firstSeen": 1735000000000,\n      "lastSeen": 1735100000000,\n      "userAgent": "Happ/1.0",\n      "deviceOs": "android",\n      "osVersion": "15",\n      "deviceModel": "Pixel 9"\n    }\n  ]\n}',
      },
      {
        method: 'DELETE',
        path: '/panel/api/clients/hwids/:email',
        summary:
          'Clear all registered HWID devices for a client so new devices can register again.',
        params: [{ name: 'email', in: 'path', type: 'string', desc: 'Client email.' }],
      },
      {
        method: 'DELETE',
        path: '/panel/api/clients/hwids/:email/:id',
        summary:
          'Remove a single registered HWID device by its id, freeing one slot under the HWID limit.',
        params: [
          { name: 'email', in: 'path', type: 'string', desc: 'Client email.' },
          { name: 'id', in: 'path', type: 'number', desc: 'Device id, from the list endpoint.' },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/clients/onlines',
        summary:
          'List the emails of currently connected clients (last seen within the heartbeat window), deduped across every node.',
        response: '{\n  "success": true,\n  "obj": ["user1", "user2"]\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/onlinesByGuid',
        summary:
          'Online client emails grouped by the panelGuid of the node that physically hosts each client. The local panel uses its own GUID; each node (at any depth in a chain) uses its GUID. Lets the inbounds page attribute online status to the real node instead of the intermediate one it syncs through.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "a1b2-...": ["user1"],\n    "c3d4-...": ["user1", "user2"]\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/clientIpsByGuid',
        summary:
          'Per-client source IPs grouped by the panelGuid of the node that observed them. Lets the central panel attribute and enforce per-client IP limits using the real visitor IPs each node sees, instead of the address of the intermediate panel it syncs through.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "a1b2-...": {\n      "user1": [\n        { "ip": "1.2.3.4", "timestamp": 1700000000 }\n      ]\n    }\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/activeInbounds',
        summary:
          "Inbound tags that carried traffic within the heartbeat window, grouped by the hosting node's panelGuid. Pairs with onlinesByGuid so the inbounds page only marks a multi-inbound client online on the inbounds it actually used. Nodes that do not report per-inbound activity are absent.",
        response:
          '{\n  "success": true,\n  "obj": {\n    "a1b2-...": ["in-443-tcp", "in-8443-tcp"]\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/clients/lastOnline',
        summary: 'Map of client email → last-seen unix timestamp.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "user1": 1700000000,\n    "user2": 1699999000\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/clients/traffic/:email',
        summary: 'Traffic counters for a client identified by email.',
        params: [
          {
            name: 'email',
            in: 'path',
            type: 'string',
            desc: 'Client email (unique across the panel).',
          },
        ],
        responseSchema: 'ClientTraffic',
      },
      {
        method: 'GET',
        path: '/panel/api/clients/subLinks/:subId',
        summary:
          'Return every protocol URL (vless://, vmess://, trojan://, ss://, hysteria://, hy2://) for clients matching the subscription ID. Same result set as /sub/<subId>, but as a JSON array — no base64. When an inbound has streamSettings.externalProxy set, one URL is emitted per external proxy. Empty array when the subId has no enabled clients.',
        params: [
          {
            name: 'subId',
            in: 'path',
            type: 'string',
            desc: "Subscription ID, taken from the client's subId field.",
          },
        ],
        response:
          '{\n  "success": true,\n  "obj": [\n    "vless://uuid@host:443?security=reality&...#user1",\n    "vmess://eyJ2IjoyLC..."\n  ]\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/clients/links/:email',
        summary:
          'Return every URL for one client across all attached inbounds — the same strings the Copy URL button copies in the panel UI. Supported protocols: vmess, vless, trojan, shadowsocks, hysteria. If streamSettings.externalProxy is set, returns one URL per external proxy. Protocols without a URL form (socks, http, mixed, wireguard, dokodemo, tunnel) contribute nothing.',
        params: [
          { name: 'email', in: 'path', type: 'string', desc: 'Client email (unique identifier).' },
        ],
        response:
          '{\n  "success": true,\n  "obj": [\n    "vless://uuid@host:443?...#user1"\n  ]\n}',
      },
    ],
  },

  {
    id: 'nodes',
    title: 'Nodes',
    description:
      'Manage remote 3x-ui panels acting as nodes for a central panel. All endpoints under /panel/api/nodes.',
    endpoints: [
      {
        method: 'GET',
        path: '/panel/api/nodes/list',
        summary:
          'List every configured node with its connection details, health, and last heartbeat patch.',
        responseSchema: 'NodeView',
        responseSchemaArray: true,
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/mtls/ca',
        summary:
          "This panel's node-auth CA certificate (public, PEM) to paste into a node's mTLS trust setting. Lazily mints the CA and the master client cert on first call. Pair with setting tlsVerifyMode=mtls on the node.",
        response:
          '{\n  "success": true,\n  "obj": {\n    "caCert": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n"\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/mtls/trustCA',
        summary:
          "Set the CA certificate this panel trusts for incoming node-API client certificates (this panel acting as a node). Paste the managing panel's CA (from nodes/mtls/ca). An empty caCert disables it. A non-empty value must be a PEM certificate. Applied on the next panel restart.",
        body: '{\n  "caCert": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n"\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/mtls/reloadClient',
        summary:
          'Validate the stored master mTLS client credential and invalidate cached transports. Each transport closes its old idle pool and rebuilds with the rotated certificate before its next request.',
      },
      {
        method: 'GET',
        path: '/panel/api/nodes/get/:id',
        summary: 'Fetch a single node by ID.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Node ID.' }],
        responseSchema: 'NodeView',
      },
      {
        method: 'GET',
        path: '/panel/api/nodes/webCert/:id',
        summary:
          'Fetch a node\'s own web TLS certificate/key file paths (proxied to the node). Used by the inbound form\'s "Set Cert from Panel" so a node-assigned inbound gets paths that exist on the node, not the central panel.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Node ID.' }],
        response:
          '{\n  "success": true,\n  "obj": {\n    "webCertFile": "/root/cert/example.com/fullchain.pem",\n    "webKeyFile": "/root/cert/example.com/privkey.pem"\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/add',
        summary:
          'Register a new remote node. Provide its URL, write-only apiToken, and optional remark / allowPrivateAddress flag. Responses expose hasApiToken only.',
        body: '{\n  "name": "de-fra-1",\n  "remark": "",\n  "scheme": "https",\n  "address": "node1.example.com",\n  "port": 2053,\n  "basePath": "/",\n  "apiToken": "abcdef...",\n  "clearApiToken": false,\n  "enable": true,\n  "allowPrivateAddress": false\n}',
        responseSchema: 'NodeView',
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/update/:id',
        summary:
          'Replace a node\u2019s connection details. apiToken is write-only: omit it or send an empty string to keep the stored token; set clearApiToken=true to clear it.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Node ID.' }],
        body: '{\n  "name": "de-fra-1",\n  "remark": "",\n  "scheme": "https",\n  "address": "node1.example.com",\n  "port": 2053,\n  "basePath": "/",\n  "apiToken": "",\n  "clearApiToken": false,\n  "enable": true,\n  "allowPrivateAddress": false\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/del/:id',
        summary: 'Delete a node. Inbounds bound to it are not auto-migrated.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Node ID.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/setEnable/:id',
        summary: 'Pause or resume traffic sync with this node.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Node ID.' }],
        body: '{\n  "enable": true\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/test',
        summary:
          'Probe a node without saving it. Uses the body as connection details and returns the same heartbeat snapshot a registered node would have.',
        body: '{\n  "scheme": "https",\n  "address": "node1.example.com",\n  "port": 2053,\n  "basePath": "/",\n  "apiToken": "abcdef..."\n}',
        responseSchema: 'ProbeResultUI',
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/certFingerprint',
        summary:
          "Connect to the node over HTTPS without verifying its certificate and return the leaf certificate's SHA-256 (base64). Used by the Add/Edit Node dialog to fetch and pin a self-signed certificate. Uses the same body as /test.",
        body: '{\n  "scheme": "https",\n  "address": "node1.example.com",\n  "port": 2053,\n  "basePath": "/"\n}',
        response: '{\n  "success": true,\n  "obj": "k3b1...base64-sha256...="\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/inbounds',
        summary:
          'Use unsaved node connection details to list the remote inbounds available for selective import.',
        body: '{\n  "name": "de-fra-1",\n  "scheme": "https",\n  "address": "node1.example.com",\n  "port": 2053,\n  "basePath": "/",\n  "apiToken": "abcdef..."\n}',
        response:
          '{\n  "success": true,\n  "obj": [\n    { "tag": "inbound-443", "remark": "VLESS", "protocol": "vless", "port": 443 }\n  ]\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/probe/:id',
        summary: 'Probe an existing node, updating its cached health state.',
        params: [{ name: 'id', in: 'path', type: 'number', desc: 'Node ID.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/nodes/updatePanel',
        summary:
          'Trigger the official panel self-updater on each given node (downloads the latest release and restarts). Only enabled, online nodes are updated; offline/disabled ones are reported as skipped. Set "dev": true to move the nodes to the rolling per-commit dev channel instead of the latest stable release. Returns a per-node result list.',
        body: '{\n  "ids": [1, 2, 3],\n  "dev": false\n}',
        response:
          '{\n  "success": true,\n  "obj": [\n    { "id": 1, "name": "de-1", "ok": true },\n    { "id": 2, "name": "fr-1", "ok": false, "error": "node is offline" }\n  ]\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/nodes/history/:id/:metric/:bucket',
        summary:
          'Aggregated metric history for a node — same shape as /server/history, scoped to one node.',
        params: [
          { name: 'id', in: 'path', type: 'number', desc: 'Node ID.' },
          { name: 'metric', in: 'path', type: 'string', desc: 'cpu | mem.' },
          {
            name: 'bucket',
            in: 'path',
            type: 'number',
            desc: 'Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.',
          },
        ],
      },
    ],
  },

  {
    id: 'hosts',
    title: 'Hosts',
    description:
      'Per-inbound override endpoints. Each enabled host renders one extra subscription link/proxy with its own address/port/TLS, superseding the legacy externalProxy array. All endpoints under /panel/api/hosts.',
    endpoints: [
      {
        method: 'GET',
        path: '/panel/api/hosts/list',
        summary:
          'List every host across all inbounds, grouped by inbound then ordered by sort order.',
        responseSchema: 'HostGroup',
        responseSchemaArray: true,
      },
      {
        method: 'GET',
        path: '/panel/api/hosts/get/:groupId',
        summary: 'Fetch a single host group by Group ID.',
        params: [{ name: 'groupId', in: 'path', type: 'string', desc: 'Host Group ID.' }],
        responseSchema: 'HostGroup',
      },
      {
        method: 'GET',
        path: '/panel/api/hosts/byInbound/:inboundId',
        summary: "Fetch one inbound's hosts, grouped by host group.",
        params: [{ name: 'inboundId', in: 'path', type: 'number', desc: 'Inbound ID.' }],
        responseSchema: 'HostGroup',
        responseSchemaArray: true,
      },
      {
        method: 'GET',
        path: '/panel/api/hosts/tags',
        summary: 'Distinct, sorted set of tags used across all hosts.',
        response: '{\n  "success": true,\n  "obj": ["CDN", "EU", "FAST"]\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/hosts/add',
        summary: 'Create a host group on inbounds.',
        body: '{\n  "inboundIds": [1],\n  "remark": "cdn-front",\n  "hosts": ["cdn.example.com"],\n  "port": 8443,\n  "security": "same",\n  "tags": ["CDN"]\n}',
        responseSchema: 'Host',
        responseSchemaArray: true,
      },
      {
        method: 'POST',
        path: '/panel/api/hosts/update/:groupId',
        summary: 'Replace a host group’s content.',
        params: [{ name: 'groupId', in: 'path', type: 'string', desc: 'Host Group ID.' }],
        body: '{\n  "inboundIds": [1],\n  "remark": "cdn-front",\n  "hosts": ["cdn.example.com"],\n  "port": 8443,\n  "security": "same",\n  "tags": ["CDN"]\n}',
        responseSchema: 'Host',
        responseSchemaArray: true,
      },
      {
        method: 'POST',
        path: '/panel/api/hosts/del/:groupId',
        summary: 'Delete a host group.',
        params: [{ name: 'groupId', in: 'path', type: 'string', desc: 'Host Group ID.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/hosts/setEnable/:groupId',
        summary: 'Enable or disable a host group.',
        params: [{ name: 'groupId', in: 'path', type: 'string', desc: 'Host Group ID.' }],
        body: '{\n  "enable": true\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/hosts/reorder',
        summary: 'Set host group sort order by the position of each groupId in the array.',
        body: '{\n  "ids": ["abc-123", "def-456"]\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/hosts/bulk/add',
        summary: 'Add a host group to inbounds (same as /add).',
        body: '{\n  "inboundIds": [1, 2],\n  "hosts": ["cdn.example.com", "cdn2.example.com:443"],\n  "remark": "Cloudflare CDN",\n  "port": 0,\n  "security": "same",\n  "isDisabled": false\n}',
        responseSchema: 'Host',
        responseSchemaArray: true,
      },
      {
        method: 'POST',
        path: '/panel/api/hosts/bulk/setEnable',
        summary: 'Enable or disable many host groups in one call.',
        body: '{\n  "ids": ["abc-123", "def-456"],\n  "enable": false\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/hosts/bulk/del',
        summary: 'Delete many host groups in one call.',
        body: '{\n  "ids": ["abc-123", "def-456"]\n}',
      },
    ],
  },

  {
    id: 'backup',
    title: 'Backup',
    description: 'Operations that interact with the configured Telegram bot.',
    endpoints: [
      {
        method: 'POST',
        path: '/panel/api/backuptotgbot',
        summary:
          'Send a fresh DB backup to every Telegram chat configured as an admin recipient. No body, no params.',
      },
    ],
  },

  {
    id: 'settings',
    title: 'Settings',
    description:
      'Panel configuration and user credentials. All endpoints live under /panel/api/setting and require a logged-in session or Bearer token.',
    endpoints: [
      {
        method: 'POST',
        path: '/panel/api/setting/all',
        summary:
          'Return every panel setting: web server, Telegram bot, subscription, security, LDAP. The full JSON blob that the Settings page edits.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "webPort": 2053,\n    "webCertFile": "",\n    "webKeyFile": "",\n    "webBasePath": "/",\n    "subPort": 10882,\n    "subPath": "/sub/",\n    "subClashAutoDetect": false,\n    "subClashUserAgentRegex": "",\n    "subJsonEnable": false,\n    "subJsonAutoDetect": false,\n    "subJsonAlwaysArray": false,\n    "subJsonUserAgentRegex": "",\n    "subJsonPath": "/json/",\n    "subJsonURI": "https://sub.example.com/json/",\n    "subClashEnable": true,\n    "subClashPath": "/clash/",\n    "subClashURI": "https://sub.example.com/clash/",\n    "tgBotEnable": false,\n    "tgBotToken": "",\n    ...\n  }\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/setting/defaultSettings',
        summary:
          'Return the computed default settings based on the request host. Useful to preview what a fresh install would use.',
      },
      {
        method: 'POST',
        path: '/panel/api/setting/factoryDefaults',
        summary:
          'Return the shipped (factory) default value per browser-safe setting key, so clients can tell a stored value apart from the default it would fall back to. Per-install material (secret, panelGuid, mTLS keys) and credential fields are never included.',
      },
      {
        method: 'POST',
        path: '/panel/api/setting/update',
        summary:
          'Persist every setting at once. The body mirrors the shape returned by /all. Invalid values (bad ports, missing cert pairs, etc.) are rejected before write.',
        body: '{\n  "webPort": 2053,\n  "webBasePath": "/",\n  "subPort": 10882,\n  "subPath": "/sub/",\n  "subClashAutoDetect": false,\n  "subClashUserAgentRegex": "",\n  "subJsonEnable": false,\n  "subJsonAutoDetect": false,\n  "subJsonAlwaysArray": false,\n  "subJsonUserAgentRegex": "",\n  "subJsonPath": "/json/",\n  "subJsonURI": "https://sub.example.com/json/",\n  "subClashEnable": true,\n  "subClashPath": "/clash/",\n  "subClashURI": "https://sub.example.com/clash/",\n  "tgBotEnable": false,\n  ...\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/setting/validateRegex',
        summary:
          'Validate any regular expression with the backend Go RE2 compiler without saving it.',
        body: '{\n  "regex": "(?m)^general-purpose$"\n}',
        response: '{\n  "success": true,\n  "msg": ""\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/setting/updateUser',
        summary:
          'Change the panel admin username and password. Requires the current credentials for verification. The session is refreshed with the new values on success.',
        params: [
          { name: 'oldUsername', in: 'body', type: 'string', desc: 'Current admin username.' },
          { name: 'oldPassword', in: 'body', type: 'string', desc: 'Current admin password.' },
          { name: 'newUsername', in: 'body', type: 'string', desc: 'Desired new username.' },
          { name: 'newPassword', in: 'body', type: 'string', desc: 'Desired new password.' },
        ],
        body: '{\n  "oldUsername": "admin",\n  "oldPassword": "admin",\n  "newUsername": "newadmin",\n  "newPassword": "newpass"\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/setting/restartPanel',
        summary:
          'Restart the entire 3x-ui process after a 3-second grace period. The connection drops immediately; the panel comes back online ~5-10 seconds later.',
      },
      {
        method: 'POST',
        path: '/panel/api/setting/testSmtp',
        summary:
          'Test SMTP connection with stage-by-stage reporting (connect, auth, send). Returns structured result with stage and message.',
        response:
          '{\n  "success": true,\n  "stage": "send",\n  "msg": "Test email sent successfully"\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/setting/testTgBot',
        summary: 'Test Telegram bot connection by sending a test message to the configured chat.',
        response: '{\n  "success": true,\n  "msg": "Test message sent to Telegram"\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/setting/getDefaultJsonConfig',
        summary:
          'Return the built-in default Xray JSON config template that ships with this panel version.',
      },
    ],
  },

  {
    id: 'api-tokens',
    title: 'API Tokens',
    description:
      'Manage scoped Bearer tokens for programmatic auth. Tokens grant admin, monitor, or node-sync access, may expire, and are stored as SHA-256 hashes. The plaintext is returned only once at creation.',
    endpoints: [
      {
        method: 'GET',
        path: '/panel/api/setting/apiTokens',
        summary:
          'List every API token, enabled or not. The token value is never returned — only metadata.',
        response:
          '{\n  "success": true,\n  "obj": [\n    {\n      "id": 1,\n      "name": "default",\n      "enabled": true,\n      "createdAt": 1736000000\n    }\n  ]\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/setting/apiTokens/create',
        summary:
          'Mint a scoped API token. The server-generated plaintext is returned only once and stored as a hash.',
        params: [
          {
            name: 'name',
            in: 'body',
            type: 'string',
            desc: 'Human-readable label, e.g. "central-panel-a".',
          },
          {
            name: 'scope',
            in: 'body',
            type: 'string',
            desc: 'admin (default), monitor, or node-sync.',
          },
          {
            name: 'expiresAt',
            in: 'body',
            type: 'number',
            desc: 'Future Unix milliseconds, or 0 for no expiry.',
          },
        ],
        body: '{\n  "name": "central-panel-a",\n  "scope": "node-sync",\n  "expiresAt": 1798761600000\n}',
        responseSchema: 'ApiTokenView',
        errorResponse:
          '{\n  "success": false,\n  "msg": "a token with that name already exists"\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/setting/apiTokens/delete/:id',
        summary:
          'Permanently delete a token. Any caller using it stops authenticating immediately.',
        params: [
          { name: 'id', in: 'path', type: 'number', desc: 'Token row ID.' },
          {
            name: 'expectedScope',
            in: 'body',
            type: 'string',
            desc: 'Stored scope expected by the operator.',
          },
        ],
        body: '{\n  "expectedScope": "node-sync"\n}',
        response: '{\n  "success": true\n}',
      },
      {
        method: 'POST',
        path: '/panel/api/setting/apiTokens/setEnabled/:id',
        summary:
          'Toggle a token enabled/disabled without deleting it. Disabled tokens are rejected by checkAPIAuth on the next request.',
        params: [
          { name: 'id', in: 'path', type: 'number', desc: 'Token row ID.' },
          { name: 'enabled', in: 'body', type: 'boolean', desc: 'New enabled state.' },
          {
            name: 'expectedScope',
            in: 'body',
            type: 'string',
            desc: 'Stored scope expected by the operator.',
          },
        ],
        body: '{\n  "enabled": false,\n  "expectedScope": "node-sync"\n}',
        response: '{\n  "success": true\n}',
      },
    ],
  },

  {
    id: 'xray-settings',
    title: 'Xray Settings',
    description:
      'Xray configuration template, outbound management, Warp/Nord/PIA integration, and config testing. All endpoints under /panel/api/xray.',
    endpoints: [
      {
        method: 'POST',
        path: '/panel/api/xray/',
        summary:
          'Return the Xray config template (JSON string), available inbound tags, client reverse tags, and the configured outbound test URL in one response.',
        response:
          '{\n  "success": true,\n  "obj": {\n    "xraySetting": "{...raw xray config...}",\n    "inboundTags": "[\\"in-443-tcp\\"]",\n    "clientReverseTags": "[]",\n    "outboundTestUrl": "https://www.google.com/generate_204"\n  }\n}',
      },
      {
        method: 'GET',
        path: '/panel/api/xray/getDefaultJsonConfig',
        summary:
          'Return the built-in default Xray config shipped with the panel (identical to /panel/api/setting/getDefaultJsonConfig).',
      },
      {
        method: 'GET',
        path: '/panel/api/xray/getOutboundsTraffic',
        summary:
          'Return traffic statistics for every outbound. Each outbound shows up/down/total counters.',
      },
      {
        method: 'GET',
        path: '/panel/api/xray/getXrayResult',
        summary:
          'Return the most recent Xray process stdout/stderr output. Useful to check for startup errors or runtime warnings.',
      },
      {
        method: 'POST',
        path: '/panel/api/xray/update',
        summary:
          'Save the Xray JSON config template and optionally the outbound test URL. Both are sent as form fields.',
        params: [
          {
            name: 'xraySetting',
            in: 'body (form)',
            type: 'string',
            desc: 'Full Xray JSON config template.',
          },
          {
            name: 'outboundTestUrl',
            in: 'body (form)',
            type: 'string',
            desc: 'URL used for outbound reachability tests. Defaults to https://www.google.com/generate_204.',
          },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/xray/warp/:action',
        summary: 'Manage Cloudflare Warp integration. The action parameter selects the operation.',
        params: [
          {
            name: 'action',
            in: 'path',
            type: 'string',
            desc: 'data — return Warp stats (quota, remaining). del — delete Warp data. config — return current Warp config. reg — register a new Warp endpoint (sends privateKey, publicKey). license — set a Warp+ license key (sends license).',
          },
          {
            name: 'privateKey',
            in: 'body (form)',
            type: 'string',
            desc: 'Required when action=reg.',
          },
          {
            name: 'publicKey',
            in: 'body (form)',
            type: 'string',
            desc: 'Required when action=reg.',
          },
          {
            name: 'license',
            in: 'body (form)',
            type: 'string',
            desc: 'Required when action=license.',
          },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/xray/nord/:action',
        summary: 'Manage NordVPN integration. The action parameter selects the operation.',
        params: [
          {
            name: 'action',
            in: 'path',
            type: 'string',
            desc: 'countries — list available countries. servers — list servers in a country (sends countryId). reg — get NordVPN credentials (sends token). setKey — store NordVPN API key (sends key). data — return current NordVPN connection data. del — delete NordVPN data.',
          },
          {
            name: 'countryId',
            in: 'body (form)',
            type: 'string',
            desc: 'Required when action=servers.',
          },
          { name: 'token', in: 'body (form)', type: 'string', desc: 'Required when action=reg.' },
          { name: 'key', in: 'body (form)', type: 'string', desc: 'Required when action=setKey.' },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/xray/pia/:action',
        summary: 'Manage PIA WireGuard integration. The action parameter selects the operation.',
        params: [
          {
            name: 'action',
            in: 'path',
            type: 'string',
            desc: 'countries — list available countries from the signed PIA server list. servers — list regions and WireGuard servers in a country (sends countryCode). reg — sign in with a PIA username and password (sends username, password). data — return the signed-in account hint. del — delete stored PIA credentials. addKey — register a WireGuard key with the selected server (sends hostname) and return fields to build the outbound.',
          },
          {
            name: 'username',
            in: 'body (form)',
            type: 'string',
            desc: 'Required when action=reg.',
          },
          {
            name: 'password',
            in: 'body (form)',
            type: 'string',
            desc: 'Required when action=reg.',
          },
          {
            name: 'countryCode',
            in: 'body (form)',
            type: 'string',
            desc: 'Required when action=servers.',
          },
          {
            name: 'hostname',
            in: 'body (form)',
            type: 'string',
            desc: 'Required when action=addKey.',
          },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/xray/resetOutboundsTraffic',
        summary: 'Reset traffic counters for a specific outbound by tag.',
        params: [
          {
            name: 'tag',
            in: 'body (form)',
            type: 'string',
            desc: 'Outbound tag to reset (e.g. "proxy", "direct").',
          },
        ],
        body: 'tag=proxy',
      },
      {
        method: 'POST',
        path: '/panel/api/xray/testOutbound',
        summary:
          'Test an outbound configuration. Sends the outbound JSON (required), optionally all outbounds (to resolve sockopt.dialerProxy dependencies), and a mode flag.',
        params: [
          {
            name: 'outbound',
            in: 'body (form)',
            type: 'string',
            desc: 'JSON-encoded single outbound to test (required).',
          },
          {
            name: 'allOutbounds',
            in: 'body (form)',
            type: 'string',
            desc: 'JSON array of all outbounds — used to resolve dialerProxy chains.',
          },
          {
            name: 'mode',
            in: 'body (form)',
            type: 'string',
            desc: '"tcp" for a fast dial-only probe (parallel-safe), "real" for a real-delay probe whose delay is the full request time including tunnel establishment. Default/empty uses a full HTTP probe reporting the warm per-request round-trip. Both HTTP variants run through a temp xray instance.',
          },
        ],
        body: 'outbound={"protocol":"freedom","settings":{}}&mode=tcp',
      },
      {
        method: 'POST',
        path: '/panel/api/xray/testOutbounds',
        summary:
          'Test a batch of outbounds (max 50) through one shared temp xray instance. Returns an array of results in input order, each with the outbound tag, delay, HTTP status and a connect/TLS/TTFB timing breakdown.',
        params: [
          {
            name: 'outbounds',
            in: 'body (form)',
            type: 'string',
            desc: 'JSON array of outbound configs to test (required).',
          },
          {
            name: 'allOutbounds',
            in: 'body (form)',
            type: 'string',
            desc: 'JSON array of all outbounds — used to resolve dialerProxy chains.',
          },
          {
            name: 'mode',
            in: 'body (form)',
            type: 'string',
            desc: '"tcp" for fast dial-only probes (UDP-transport outbounds are still probed over HTTP), "real" for real-delay probes whose delay is the full request time including tunnel establishment. Default/empty routes an HTTP request through each outbound and reports the warm per-request round-trip.',
          },
        ],
        body: 'outbounds=[{"tag":"direct","protocol":"freedom","settings":{}}]&mode=http',
      },
      {
        method: 'POST',
        path: '/panel/api/xray/balancerStatus',
        summary:
          'Live state of routing balancers in the running core (RoutingService.GetBalancerInfo): current override and the targets the strategy prefers. Returns a map keyed by balancer tag.',
        params: [
          {
            name: 'tags',
            in: 'body (form)',
            type: 'string',
            desc: 'Comma-separated balancer tags to query (e.g. "b1,b2").',
          },
        ],
        body: 'tags=b1,b2',
      },
      {
        method: 'POST',
        path: '/panel/api/xray/balancerOverride',
        summary:
          'Force a balancer in the running core to always pick one outbound (RoutingService.OverrideBalancerTarget). Applied live without a restart; cleared automatically when Xray restarts.',
        params: [
          { name: 'tag', in: 'body (form)', type: 'string', desc: 'Balancer tag (required).' },
          {
            name: 'target',
            in: 'body (form)',
            type: 'string',
            desc: 'Outbound tag to force. Empty clears the override and returns control to the strategy.',
          },
        ],
        body: 'tag=b1&target=proxy',
      },
      {
        method: 'POST',
        path: '/panel/api/xray/routeTest',
        summary:
          'Ask the running core which outbound its router would pick for a synthetic connection (RoutingService.TestRoute). No traffic is sent.',
        params: [
          {
            name: 'domain',
            in: 'body (form)',
            type: 'string',
            desc: 'Target domain. Either domain or ip is required.',
          },
          {
            name: 'ip',
            in: 'body (form)',
            type: 'string',
            desc: 'Target IP. Either domain or ip is required.',
          },
          { name: 'port', in: 'body (form)', type: 'number', desc: 'Target port (optional).' },
          { name: 'network', in: 'body (form)', type: 'string', desc: '"tcp" (default) or "udp".' },
          {
            name: 'inboundTag',
            in: 'body (form)',
            type: 'string',
            desc: 'Simulate arrival on this inbound (optional).',
          },
          {
            name: 'protocol',
            in: 'body (form)',
            type: 'string',
            desc: 'Sniffed protocol such as http, tls, bittorrent (optional).',
          },
          {
            name: 'email',
            in: 'body (form)',
            type: 'string',
            desc: 'User attribution for user-based rules (optional).',
          },
        ],
        body: 'domain=example.com&port=443&network=tcp',
      },
      {
        method: 'GET',
        path: '/panel/api/xray/geodata/files',
        summary:
          'List the geo databases (.dat files) in the Xray asset folder, with the layout detected from their contents, size, modification time and category count. A database that fails to parse is still listed, with the reason in "error".',
      },
      {
        method: 'GET',
        path: '/panel/api/xray/geodata/categories',
        summary:
          'One page of a database\'s categories, each with its entry count and the attributes its domains carry (e.g. "ads", "cn").',
        params: [
          {
            name: 'file',
            in: 'query',
            type: 'string',
            desc: 'Database file name inside the asset folder, e.g. geosite.dat (required).',
          },
          {
            name: 'q',
            in: 'query',
            type: 'string',
            optional: true,
            desc: 'Case-insensitive substring filter on the category code.',
          },
          {
            name: 'offset',
            in: 'query',
            type: 'integer',
            optional: true,
            desc: 'Rows to skip. Defaults to 0.',
          },
          {
            name: 'limit',
            in: 'query',
            type: 'integer',
            optional: true,
            desc: 'Rows to return, capped at 500. Omit it to return every category — the index is small and the panel filters it client-side.',
          },
        ],
      },
      {
        method: 'GET',
        path: '/panel/api/xray/geodata/entries',
        summary:
          'One page of the rules inside a category — domain rules typed as domain/full/keyword/regexp for geosite databases, CIDRs for geoip ones.',
        params: [
          {
            name: 'file',
            in: 'query',
            type: 'string',
            desc: 'Database file name inside the asset folder (required).',
          },
          {
            name: 'code',
            in: 'query',
            type: 'string',
            desc: 'Category code, case-insensitive, e.g. google (required).',
          },
          {
            name: 'q',
            in: 'query',
            type: 'string',
            optional: true,
            desc: 'Case-insensitive substring filter on the rule value.',
          },
          {
            name: 'offset',
            in: 'query',
            type: 'integer',
            optional: true,
            desc: 'Rows to skip. Defaults to 0.',
          },
          {
            name: 'limit',
            in: 'query',
            type: 'integer',
            optional: true,
            desc: 'Rows to return, capped at 500. Defaults to the cap.',
          },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/xray/geodata/validate',
        summary:
          'Check routing tokens against the databases on disk and return only the ones that do not resolve. Plain domains and CIDRs are ignored. Each issue carries a reason: syntax, fileMissing or categoryMissing.',
        params: [
          {
            name: 'tokens',
            in: 'body (form)',
            type: 'string',
            desc: 'Comma-separated routing tokens, e.g. "geosite:google,geosite:blabla". Max 500 per request.',
          },
          {
            name: 'kind',
            in: 'body (form)',
            type: 'string',
            desc: '"ip" to parse the tokens as IP rules (geoip:, ext-ip:, leading !). Anything else parses them as domain rules (geosite:, ext-site:).',
          },
        ],
        body: 'kind=domain&tokens=geosite:google,geosite:blabla',
      },
      {
        method: 'GET',
        path: '/panel/api/xray/outbound-subs',
        summary:
          'List all outbound subscriptions (remote URLs that supply additional outbounds), newest first.',
      },
      {
        method: 'POST',
        path: '/panel/api/xray/outbound-subs',
        summary:
          'Create an outbound subscription. The URL is fetched, parsed into outbounds with stable tags, and merged additively into the running Xray config.',
        params: [
          { name: 'remark', in: 'body (form)', type: 'string', desc: 'Optional display label.' },
          {
            name: 'url',
            in: 'body (form)',
            type: 'string',
            desc: 'Subscription URL (required). Must be a public http(s) address; private/internal targets are blocked unless allowPrivate is true.',
          },
          {
            name: 'tagPrefix',
            in: 'body (form)',
            type: 'string',
            desc: 'Prefix for generated outbound tags. Defaults to "sub<id>-".',
          },
          {
            name: 'updateInterval',
            in: 'body (form)',
            type: 'integer',
            desc: 'Seconds between auto-refreshes. Default 600.',
          },
          {
            name: 'enabled',
            in: 'body (form)',
            type: 'boolean',
            desc: 'Whether the subscription is active. Default true.',
          },
          {
            name: 'allowPrivate',
            in: 'body (form)',
            type: 'boolean',
            desc: 'Allow the URL to point at a private/internal/loopback address (localhost/LAN). Default false (SSRF guard blocks private targets).',
          },
          {
            name: 'prepend',
            in: 'body (form)',
            type: 'boolean',
            desc: "Place this subscription's outbounds before the manual template outbounds (so one can become the default). Default false.",
          },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/xray/outbound-subs/:id',
        summary:
          'Update an existing outbound subscription by id. Accepts the same form fields as create.',
        params: [{ name: 'id', in: 'path', type: 'integer', desc: 'Subscription id.' }],
      },
      {
        method: 'DELETE',
        path: '/panel/api/xray/outbound-subs/:id',
        summary: 'Delete an outbound subscription by id.',
        params: [{ name: 'id', in: 'path', type: 'integer', desc: 'Subscription id.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/xray/outbound-subs/:id/del',
        summary:
          'Delete an outbound subscription by id (POST alias of DELETE for clients that cannot send DELETE).',
        params: [{ name: 'id', in: 'path', type: 'integer', desc: 'Subscription id.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/xray/outbound-subs/:id/refresh',
        summary:
          'Force an immediate re-fetch of the subscription and return the parsed outbounds. Signals Xray to reload.',
        params: [{ name: 'id', in: 'path', type: 'integer', desc: 'Subscription id.' }],
      },
      {
        method: 'POST',
        path: '/panel/api/xray/outbound-subs/:id/move',
        summary:
          'Reorder a subscription one step up or down in priority (controls its position in the merged outbounds).',
        params: [
          { name: 'id', in: 'path', type: 'integer', desc: 'Subscription id.' },
          {
            name: 'dir',
            in: 'body (form)',
            type: 'string',
            desc: '"up" to raise priority, anything else to lower it.',
          },
        ],
      },
      {
        method: 'POST',
        path: '/panel/api/xray/outbound-subs/parse',
        summary:
          'Preview a subscription URL: fetch and parse it into outbounds without persisting anything.',
        params: [
          {
            name: 'url',
            in: 'body (form)',
            type: 'string',
            desc: 'Subscription URL to preview (required).',
          },
        ],
      },
    ],
  },

  {
    id: 'sub-balancers',
    title: 'Subscription Balancers',
    description:
      'Client-side balancers for the JSON subscription: each enabled balancer is emitted as one extra config document whose members are the proxy outbounds of the selected inbounds (routing.balancers + burstObservatory). Managed in Settings → Sub Balancers.',
    endpoints: [
      {
        method: 'GET',
        path: '/panel/api/sub-balancers',
        summary: 'List all subscription balancers in sort order (sort_order asc, id asc).',
        responseSchema: 'SubBalancer',
        responseSchemaArray: true,
      },
      {
        method: 'POST',
        path: '/panel/api/sub-balancers',
        summary:
          'Create a subscription balancer. It appears in the JSON subscription of every client that sits on at least one selected inbound.',
        params: [
          {
            name: 'remark',
            in: 'body (form)',
            type: 'string',
            desc: 'Display label, used as the config remarks (required).',
          },
          {
            name: 'strategy',
            in: 'body (form)',
            type: 'string',
            desc: 'Balancer strategy: "leastLoad", "leastPing", "roundRobin" or "random" (xray routing balancer strategies). Default "random".',
          },
          {
            name: 'inboundIds',
            in: 'body (form)',
            type: 'integer[]',
            desc: 'Repeated form keys selecting the member inbounds, e.g. inboundIds=1&inboundIds=3 (required, at least one).',
          },
          {
            name: 'sortOrder',
            in: 'body (form)',
            type: 'integer',
            desc: '1-based position in the subscription list, interleaved with the inbounds subSortIndex. Default 1.',
          },
          {
            name: 'enabled',
            in: 'body (form)',
            type: 'boolean',
            desc: 'Whether the balancer is emitted. Default true.',
          },
        ],
        responseSchema: 'SubBalancer',
      },
      {
        method: 'POST',
        path: '/panel/api/sub-balancers/:id',
        summary:
          'Update a balancer by id. Accepts the same form fields as create (full-row update, including the enabled toggle).',
        params: [{ name: 'id', in: 'path', type: 'integer', desc: 'Balancer id.' }],
        responseSchema: 'SubBalancer',
      },
      {
        method: 'DELETE',
        path: '/panel/api/sub-balancers/:id',
        summary: 'Delete a balancer by id.',
        params: [{ name: 'id', in: 'path', type: 'integer', desc: 'Balancer id.' }],
        responseSchema: 'SubBalancer',
      },
      {
        method: 'POST',
        path: '/panel/api/sub-balancers/:id/del',
        summary:
          'Delete a balancer by id (POST alias of DELETE for clients that cannot send DELETE).',
        params: [{ name: 'id', in: 'path', type: 'integer', desc: 'Balancer id.' }],
        responseSchema: 'SubBalancer',
      },
    ],
  },

  {
    id: 'subscription',
    title: 'Subscription Server',
    description:
      'A separate HTTP/HTTPS server that serves proxy subscription links (standard, JSON, and Clash) to clients. The server listens on its own port (default 10882) and is configured in Settings → Subscription. Paths are configurable; defaults are shown below. All subscription endpoints set response headers for client apps to read traffic/expiry info.',
    subHeader: [
      {
        name: 'Subscription-Userinfo',
        desc: 'Traffic and expiry: <code>upload=N; download=N; total=N; expire=TS</code>',
      },
      { name: 'Profile-Title', desc: 'Base64-encoded subscription display name' },
      { name: 'Profile-Web-Page-Url', desc: 'Link to the subscription info page' },
      { name: 'Support-Url', desc: 'Support contact URL configured in settings' },
      {
        name: 'Profile-Update-Interval',
        desc: 'Suggested polling interval in minutes (e.g. <code>10</code>)',
      },
      { name: 'Announce', desc: 'Base64-encoded announcement string' },
      {
        name: 'Routing-Enable',
        desc: '<code>true</code> or <code>false</code> — whether routing rules are included',
      },
      {
        name: 'Routing',
        desc: 'Global routing rules for client apps that support them (e.g. Happ)',
      },
    ],
    endpoints: [
      {
        method: 'GET',
        path: '/{subPath}:subid',
        summary:
          'Return base64-encoded subscription links for all enabled clients matching the subscription ID. When the request has an Accept: text/html header or ?html=1, renders a styled info page instead. With ?format=info, returns the page view-model as JSON (traffic, expiry, online status; no links) for live polling. Default path: /sub/:subid.',
        params: [
          { name: 'subid', in: 'path', type: 'string', desc: 'Client subscription ID.' },
          {
            name: 'format',
            in: 'query',
            type: 'string',
            optional: true,
            desc: 'Set to "info" to get the subscription status view-model as JSON instead of the links.',
          },
        ],
      },
      {
        method: 'GET',
        path: '/{jsonPath}:subid',
        summary:
          'Return subscription as a JSON array of proxy configs (one per enabled client). Only when JSON subscription is enabled in settings. Default path: /json/:subid.',
        params: [{ name: 'subid', in: 'path', type: 'string', desc: 'Client subscription ID.' }],
      },
      {
        method: 'GET',
        path: '/{clashPath}:subid',
        summary:
          'Return subscription as a Clash/Mihomo-compatible YAML config, including configured global Clash routing rules. Only when Clash subscription is enabled in settings. Default path: /clash/:subid.',
        params: [{ name: 'subid', in: 'path', type: 'string', desc: 'Client subscription ID.' }],
      },
    ],
  },

  {
    id: 'websocket',
    title: 'WebSocket',
    description:
      'Real-time status updates via WebSocket. Connect once at <code>ws://<panel>/ws</code> to receive a stream of JSON messages without polling. Requires an authenticated session cookie (Bearer token auth is not supported). Each message has a <code>type</code> field that identifies the payload shape.',
    endpoints: [
      {
        method: 'GET',
        path: '/ws',
        summary:
          'Upgrade an HTTP connection to a WebSocket. Requires an authenticated session cookie (Bearer token auth is not supported here). Returns 101 Switching Protocols on success. The server then pushes JSON messages described below.',
      },
      {
        method: 'WS',
        path: '→ type: status',
        summary:
          'Server health snapshot pushed every 2 seconds. Contains CPU, memory, swap, disk, network IO, load, and Xray state — same shape as <code>GET /panel/api/server/status</code>.',
        response:
          '{\n  "type": "status",\n  "data": { "cpu": 12.5, "mem": { "current": 2147483648, "total": 8589934592 }, "xray": { "state": "running" } }\n}',
      },
      {
        method: 'WS',
        path: '→ type: xrayState',
        summary:
          'Xray process state change. Fired when Xray starts, stops, or encounters an error.',
        response: '{\n  "type": "xrayState",\n  "data": "running"\n}',
      },
      {
        method: 'WS',
        path: '→ type: notification',
        summary:
          'In-panel toast notification. Fired on Xray stop/restart, DB import, panel restart, etc.',
        response:
          '{\n  "type": "notification",\n  "title": "Xray service restarted",\n  "body": "Xray has been restarted successfully",\n  "severity": "success"\n}',
      },
      {
        method: 'WS',
        path: '→ type: invalidate',
        summary:
          'Instructs the UI to re-fetch a resource. Fired when another admin session modifies data (e.g. toggling inbound enable).',
        response: '{\n  "type": "invalidate",\n  "resource": "inbounds"\n}',
      },
    ],
  },
];