xinyin025/3x-ui
1
0
Fork 0
mirror of https://github.com/MHSanaei/3x-ui.git synced 2026-08-25 12:27:13 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
f204997c986d38eda2ec484067e4240649a36339
3x-ui/docs/public/openapi.json
T
Kuzz007 effcccceac feat(amneziawg): add native AmneziaWG protocol support (#6105) 
* feat(amneziawg): add native AmneziaWG protocol backend

AmneziaWG (WireGuard plus DPI-resistant obfuscation) needs no Docker
here — it runs as a genuine kernel interface via awg-quick/awg, managed
the same way internal/mtproto manages mtg: one Inbound row is one
desired Instance, and a Manager reconciles running interfaces toward
the database every 10s (internal/web/job/amneziawg_job.go) plus
immediately after a client edit (applyLocalAmneziaWG).

Clients reuse model.Client verbatim (the same PrivateKey/PublicKey/
PreSharedKey/AllowedIPs fields WireGuard already uses), so bulk
operations, the QR/share-link modal and subscriptions come from the
shared inbound infrastructure instead of a parallel implementation.
internal/amneziawg owns the obfuscation param generator/validator
(ported from coinman-dev/3ax-ui, upgraded to AmneziaWG 2.0's S3/S4
padding and I1 signature packet) and the exec wrapper around
awg-quick/awg, with fingerprint-based reconcile (noop / reload-via-
syncconf / full restart) mirroring mtproto.Manager so a same-protocol
edit doesn't force an unnecessary interface bounce that would drop
every peer's connection.

Frontend and install.sh's DKMS/awg-tools setup are tracked separately;
this is backend-only.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat(amneziawg): add frontend support and fix a Go->Zod generator gap

Wires the amneziawg protocol through the panel UI the same way every
other protocol is registered: a Zod settings schema (nested
{server, clients}, matching the Go JSON exactly), the protocol enum,
the inbound-form's per-protocol fields component and its
tab-visibility allowlist, the default-settings factory, the client
schema dispatcher, and the sniffing-capability exclusion (no Xray
inbound exists for amneziawg, same as mtproto).

Client key/allowedIPs fields are reused rather than duplicated: since
AmneziaWG clients are wire-identical to WireGuard clients (same
model.Client fields), ClientFormModal renders one shared field block
for both, switching only the visible label by which protocol is
active. The private-key input also gets a live public-key sync via a
new useEffect, because unlike WireGuard's Xray-native inbound (which
re-derives its public key at runtime and never stores one),
AmneziaWG's server.publicKey is a real persisted field the Go backend
reads directly — free-typing a new private key without this would
silently save a mismatched keypair.

Adds a downloadable per-client .conf (amneziawgConfig.ts, mirroring
wireguardConfig.ts) with the obfuscation lines, and an
InboundOption.AwgServer field on the Go side so the config builder
gets the full server block in one round trip.

Along the way, running tools/openapigen surfaced a real bug: it
doesn't flatten anonymously-embedded Go structs the way encoding/json
does, so ServerSettings embedding Obfuscation20 produced a Zod schema
with a nested `obfuscation20` key that never matches the real wire
JSON. Fixed by un-embedding (flat fields + an accessor method) and
registering internal/amneziawg in the generator's own package list,
which had been silently emitting a dangling schema reference.

English and Russian translations are complete; the other 10 locale
files still fall back to English for the new keys.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat(amneziawg): complete frontend parity for the Inbounds list page

The Clients page (form, CRUD, QR/config) already worked from the
prior commit; this closes the remaining gap on the Inbounds side and
in a couple of protocol allowlists that a plain search for existing
wireguard/mtproto handling turned up.

lib/xray/inbound-link.ts gets amneziawg-specific link/config builders
(genAmneziaWGLink/genAmneziaWGConfig, plus the *s fan-out variants)
mirroring the wireguard ones — AmneziaWG has no legacy peers-array to
fall back to, so these read settings.clients directly and add the
obfuscation lines every client must share with the server. Wired into
genInboundLinks generically, and into three consumers that call the
wireguard builders directly rather than through that dispatcher:
QrCodeModal, InboundInfoModal, and InboundsPage's bulk export.

ClientInfoModal, ClientBulkAddModal, and the bulk attach/detach modals
each had their own protocol allowlist that needed amneziawg added
alongside wireguard/mtproto.

Two real gaps surfaced by grepping every remaining 'wireguard' /
Protocols.WIREGUARD hit in frontend/src rather than trusting the
checklist was exhaustive:
- useInbounds.ts's TRACKED_PROTOCOLS gates the deactive/depleted/
  expiring/online client counts shown per inbound on the list page;
  without amneziawg those counts would silently read zero.
- inbound-tag.ts is an explicit client-side mirror of the Go backend's
  port_conflict.go (the file says so itself: "Keep in sync"). It still
  only special-cased wireguard for UDP, so an amneziawg inbound would
  have fallen through to the TCP default and disagreed with the
  backend's own port-conflict math.

Also finishes translating the AmneziaWG UI strings into the 11 locale
files that were still falling back to English (ar-EG, es-ES, fa-IR,
id-ID, ja-JP, pt-BR, tr-TR, uk-UA, vi-VN, zh-CN, zh-TW), matching
en-US/ru-RU key-for-key (26 new keys, verified by count in every file).

Not run anywhere: npm run typecheck / build. This machine has neither
Node nor npm, so nothing here has compiled — reviewed by hand plus
brace/paren balance checks and cross-referencing the generated Zod/TS
types. Treat this as needing a real typecheck before shipping.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* docs(install): note that AmneziaWG kernel module install is still manual

Tracked separately (not yet ported into this script) — see
coinman-dev/3ax-ui's install_amneziawg for the reference approach
(ppa:amnezia/ppa). Also serves as a real, path-filter-matching change
to get the previous empty commit's CI trigger to actually fire —
release.yml's push trigger is paths-scoped and an empty commit changes
no files, so it never matched.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat(amneziawg): add a button to randomize obfuscation parameters

Mirrors the existing key-regenerate button next to the private key
field. Client-side randomization matches the ranges/constraints of
GenerateObfuscation20's "default" preset (internal/amneziawg/params.go)
closely enough for a form suggestion — the user can still hand-edit any
field afterward.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat(install): auto-install the AmneziaWG DKMS module + amneziawg-tools

Ports install_amneziawg from coinman-dev/3ax-ui's install.sh, adapted to
this script's broader distro coverage and NONINTERACTIVE convention:

- Ubuntu/Debian/Armbian: ppa:amnezia/ppa (primary, tested path), with a
  reachability pre-check for the Launchpad PPA host — often blocked by
  hosting providers, especially Russian VPS — so a flaky network skips
  the feature instead of hanging apt through several retries.
- Fedora/RHEL-family, Arch/Manjaro/Parch: best-effort fallback to plain
  wireguard-tools (+ AUR amneziawg-dkms via yay/paru when available),
  with a manual-install pointer.
- Everything else: manual-install pointer only.

Also installs ndppd and persists IPv4/IPv6 forwarding (for the future
IPv6/NDP phase, not yet wired into the panel) and adds a Secure Boot
warning at the end of the run, since a DKMS-built module is unsigned
and won't load while it's enabled — a common trap on cloud VPS images.

Never fatal: the panel installs and runs fine either way, an AmneziaWG
inbound just won't bring up its tunnel until the module is present.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(amneziawg): resolve all 3 real CI failures (typecheck/lint/codegen)

Found by checking the fork's Actions tab after the last two pushes —
the release build passed (it doesn't run these checks) but the
separate CI workflow caught three real issues:

- golangci-lint (noctx): every internal/amneziawg/manager.go exec.Command
  call is now exec.CommandContext with a 30s timeout, so a hung
  awg-quick/awg invocation can't block the reconcile job indefinitely
  (mirrors internal/mtproto/process.go's own CommandContext usage).
- tsc --noEmit: frontend/src/schemas/client.ts's hand-maintained
  InboundOptionSchema (used by the useClients hook, separate from the
  auto-generated one in generated/) never got an awgServer field added
  when the AmneziaWG frontend work was done — every read of
  inbound.awgServer.* in amneziawgConfig.ts was typing as {}. Added
  AwgServerOptionSchema, nested (not flattened like wg*) to match what
  amneziawgConfig.ts already expects. Also guarded server.publicKey in
  inbound-link.ts's genAmneziaWGLink against the schema's optional type.
- codegen staleness: frontend/public/openapi.json is produced by a Node
  script (gen:api) this machine can't run; hand-applied the exact diff
  the CI failure log already showed (amneziawg protocol enum entry,
  ServerSettings schema, InboundOption.awgServer, one example payload),
  verified as valid JSON.

Also confirmed independently by this run: install_amneziawg (previous
commit) installed and loaded the DKMS module successfully on both amd64
and arm64 CI runners. The two "Deploy Smoke Tests" failures are
unrelated to this change — this fork has only ever published the
dev-latest pre-release, and GitHub's /releases/latest API deliberately
excludes pre-releases, so the smoke test's no-argument install path
(which resolves "latest") has nothing to find. Not a regression; needs
an actual tagged release whenever that's wanted.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat(amneziawg): Phase 2a — IPv6 support + NDP proxy

Adds native dual-stack IPv6 to AmneziaWG inbounds, ported from
coinman-dev/3ax-ui's approach:

- ServerSettings gets ipv6Enabled/ipv6Subnet/ipv6ExternalInterface;
  Instance carries the server's own IPv6 address (first host of the
  subnet) alongside its IPv4 one.
- defaultAmneziaWGClients allocates an IPv6 host address per client
  (second AllowedIPs entry) when the server has IPv6 enabled, reusing
  allocateWireguardAddress — which needed a real fix along the way: it
  always suffixed "/32" regardless of address family, which is wrong
  for an IPv6 host address (needs /128). Now family-aware.
- generateServerConfig's PostUp/PostDown gains IPv6 forward-accept
  rules, proxy_ndp sysctl, and one `ip -6 neigh add/del proxy` entry per
  enabled peer with an IPv6 address — the lightweight per-client
  method, not the ndppd-daemon whole-subnet method (not worth the
  config-file-management complexity at this scale; ndppd itself is
  still installed by install.sh in case that changes later).
- ValidateIPv6Subnet rejects a malformed subnet before save.
- Frontend: ipv6Enabled/ipv6Subnet/ipv6ExternalInterface fields on the
  AmneziaWG inbound form, EN+RU translations, openapi.json/generated/*
  regenerated (the latter via `go run ./tools/openapigen`, pure Go).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(amneziawg): fill in IPv6 fields missed by the Phase 2a commit

Two real gaps the CI caught (both new fields, both my miss):

- inbound-defaults.ts's createDefaultAmneziawgInboundSettings() built a
  server object literal predating ipv6Enabled/ipv6Subnet/
  ipv6ExternalInterface — AmneziawgServer's inferred type now requires
  them (zod .default() fields are non-optional post-parse), so this
  didn't typecheck at all.
- openapi.json's ipv6Enabled property was missing the description the
  real generator attaches (the Go doc comment covering all three IPv6
  fields is attached to the first one) — a one-line diff, but git
  diff --exit-code doesn't care how small.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat(amneziawg): Phase 2b — per-client port-forwarding

Admins can now set a per-client ForwardedPorts string (e.g. "80, 443,
8000-8100") that gets DNAT'd + FORWARD'd to that peer's tunnel address
via iptables rules in PostUp/PostDown, ported and simplified from
coinman-dev/3ax-ui's shared/portfwd.

Two decisions worth flagging for future readers:

- The iptables --comment tag on each rule is awg-fwd-<fnv32a(email)>,
  not the raw client email. Email is admin/API-supplied free text that
  ends up embedded in a shell-executed PostUp/PostDown line; a hash
  can never carry a shell metacharacter through where raw
  interpolation could.
- The reconcile manager gained a third fingerprint (portFwdFP, next to
  the existing structural/peers ones). `awg syncconf` only touches the
  WireGuard peer table — it never re-applies PostUp/PostDown iptables
  rules — so a port-forward-only change has to force a full
  awg-quick down+up bounce, same as a structural change, rather than
  the lighter sync a plain peer add/remove can use.

Also fixes a real pre-existing bug found while wiring up IPv6 client
allocation in the previous commit's spirit: allocateWireguardAddress
always suffixed "/32" regardless of address family, which produced
invalid host bits for IPv6 (needs "/128").

ForwardedPorts flows through model.Client -> model.ClientRecord
(gorm column wg_forwarded_ports, auto-migrated) -> ToRecord/ToClient/
MergeClientRecord, mirroring the awgServer field's earlier lesson
that new fields need checking against a second, hand-maintained
persistence-layer struct.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat(amneziawg): route a client's traffic through Xray via the Routing page

Every enabled AmneziaWG inbound gets its own Xray TPROXY bridge
automatically, with no toggle to enable first: a loopback
dokodemo-door inbound (sockopt.tproxy) tagged with the AmneziaWG
inbound's own real tag, so it's already selectable in the existing
Routing page's inbound-tag picker — the same trick the mtproto
sidecar's own bridge already relies on (InboundService.GetInboundTags
is a plain, protocol-blind SELECT over every inbound row's tag, no
dedicated UI plumbing needed).

internal/amneziawg's defaultPostUpDown TPROXYs every peer's traffic
into that bridge unconditionally; the bridge's port is derived
deterministically from the inbound's id (EgressPortForInbound) so the
kernel-side reconcile loop and the Xray-config generator never need to
negotiate a runtime value between them.

injectAmneziawgEgress never generates a routing rule itself — whether
a client's traffic goes anywhere beyond Xray's default routing is
entirely up to whatever rules the admin adds through the existing
Routing UI (pick the AmneziaWG inbound's tag as source, optionally a
specific peer's IP via that page's own Source-IP field, and an
outbound), exactly the same workflow as routing any other protocol.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(amneziawg): recover orphaned interfaces after an ungraceful exit

Two gaps left an AmneziaWG interface stuck outside the manager's
control after a crash (kill -9/OOM/panic skips StopAll):

- ensureRestart's teardown was gated on the in-memory `exists` map,
  which is always empty on a fresh process, so a survived interface
  never got interfaceDown before interfaceUp tried `ip link add`
  against a name the kernel already had — failing forever and never
  populating m.ifaces, so traffic accounting silently stopped and the
  inbound could never be removed. Gate on isInterfaceUp instead, which
  checks real kernel state rather than this process's own bookkeeping.

- An inbound deleted from the database entirely while the panel was
  down has no entry in `desired` ever again, so it never reaches the
  per-id cleanup loop in Reconcile (which only walks m.ifaces). Add a
  one-time sweepOrphansLocked scan of configDir, mirroring
  mtproto.Manager.sweepOrphansLocked, that tears down and removes any
  leftover interface/config not in the current desired set.

Found by the automated review on MHSanaei/3x-ui#6105 (Finding 1).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* i18n(amneziawg): backfill IPv6/obfuscation/port-forwarding keys in 11 locales

Only en-US/ru-RU ever got these 9 keys as each AmneziaWG feature landed
(the regenerate-obfuscation button, then Phase 2a's IPv6 fields, then
Phase 2b's per-client ForwardedPorts) — the other 11 locale files were
never backfilled, so i18next has been silently falling back to English
for all of them since Phase 1. Cosmetic-only (never broke anything),
but now closed for every shipped locale.

* fix(amneziawg): resolve 7 Medium findings from the automated PR review

Each is independently reproducible; fixed together since one review pass
found all of them.

- manager.go: the shared "ip rule add fwmark" policy route had no
  existence check, so it duplicated in "ip rule show" on every interface
  bounce (which hostRulesFingerprint forces on any client add/remove/
  re-IP). Now checked via "ip rule list | grep -q ..." first. (Finding 2)

- params.go: ExternalInterface, IPv6ExternalInterface, and subnetIp/
  subnetCidr are interpolated unescaped into a shell-executed PostUp/
  PostDown line, but only obfuscation and the IPv6 subnet were validated
  before save. Added ValidateInterfaceName (a strict charset+length
  pattern) and ValidateSubnetIPv4 (netip.ParsePrefix), wired into
  normalizeAmneziaWGSettings. (Finding 3)

- amneziawg_job.go: IsAwgInstalled() existed but nothing ever called it,
  so a host without awg/awg-quick (the Docker image, RHEL, Arch, a failed
  install.sh PPA step) logged a reconcile failure every 10s forever. Now
  checked once an inbound actually needs it, warning once instead of
  spamming. (Finding 4)

- client_inbound_apply.go: the WireGuard/AmneziaWG credential
  carry-forward (added so a metadata-only client edit doesn't rotate
  keys) never covered ForwardedPorts, so a partial edit -- an API call or
  Telegram-bot toggle that omits the field -- silently wiped a client's
  port-forwarding spec. Carried forward and written back the same way the
  key fields already are. (Finding 5)

- manager.go: hostRulesFingerprint keyed each peer on its IPv4 address
  only, and structuralFingerprint omitted IPv6Enabled/IPv6ExternalInterface
  entirely, so an IPv6-only change could pick the syncconf reload path
  (which never re-runs PostUp, leaving a stale NDP-proxy entry) or be a
  complete no-op. Both fingerprints now cover the IPv6 fields. (Finding 6)

- port_conflict.go: the AmneziaWG egress bridge (injectAmneziawgEgress)
  binds 127.0.0.1:63100+id with no collision check anywhere, since it
  isn't a database row the ordinary port-conflict query can see -- same
  blind spot the reserved Xray API port already has its own check for.
  Added the equivalent check for the AmneziaWG bridge port. (Finding 7)

- install.sh: install_amneziawg ran unconditionally for every install/
  update, building a DKMS kernel module and enabling host-wide IPv4/IPv6
  forwarding whether or not the feature is ever used. Gated behind a new
  should_install_amneziawg (XUI_INSTALL_AMNEZIAWG=true/false, or an
  interactive y/N prompt defaulting to no). Also replaced the deprecated
  apt-key adv with a dedicated keyring + signed-by= on the Debian branch,
  and guarded its sources.list appends against duplication on a retried
  install. (Finding 8)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat(amneziawg): make the Xray TPROXY bridge a per-inbound opt-in

Addresses Finding 10 from the automated PR review: an always-on TPROXY
bridge makes every AmneziaWG tunnel hard-depend on Xray being up (all
traffic, including DNS, drops whenever Xray restarts), and forces a full
awg-quick down+up bounce on any client add/remove/re-IP, permanently
losing the syncconf fast path.

Adds ServerSettings.RouteThroughXray (off by default):

- defaultPostUpDown only emits the TPROXY/policy-route rules when it's
  on; a plain AmneziaWG tunnel now has zero Xray dependency out of the
  box.
- structuralFingerprint covers it (toggling it changes whether PostUp/
  PostDown contain any TPROXY rules at all -- structural, not a
  per-peer host-rule). hostRulesFingerprint's IPv4 tracking is now
  itself conditional on RouteThroughXray (and IPv6 tracking on
  IPv6Enabled), so an instance that never uses either keeps the
  syncconf fast path for a plain peer re-IP.
- injectAmneziawgEgress only creates a bridge for inbounds that opted
  in; checkAmneziawgEgressConflict (the Finding-7 fix) now parses each
  candidate through InstanceFromInbound so a non-routed inbound's port
  is correctly never treated as reserved.
- New inbound-level Switch in the AmneziaWG form; the actual outbound
  decision is still made entirely through the panel's stock Routing
  page, same as before -- only whether the bridge exists at all is now
  a choice.

Translation keys added to all 13 locales in the same commit this time,
not backfilled later (see Finding 9's lesson).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(amneziawg): resolve 4 Low findings from the automated PR review

- manager.go: serverAddress assumed subnetIp always ends in ".0"; a
  base like "10.8.1.5" was used verbatim as the server's own address,
  eventually colliding with peer allocation (which starts at .2
  upward). Now derives the first host of the actual subnetIp/subnetCidr
  network via netip, matching serverAddressV6's own approach. A /32
  base (no host bits at all) is still used as-is. (Finding 12, partial
  -- the /16 pool-widening half of this finding only exists on the
  upstream-pr/amneziawg branch's merged client_wireguard.go, not here;
  handled separately on that branch.)

- manager.go: ensureLocked carried the previous per-peer traffic
  counters (`last`) forward even through a full restart, but
  awg-quick down+up resets the kernel's own counters to zero -- the
  next CollectTraffic computed a large negative delta (clamped to 0),
  silently discarding real traffic. Extracted the decision into
  nextTrafficBaseline: only a reload (syncconf) preserves the
  baseline. (Finding 13)

- portfwd.go: exported ForwardedPortsInclude; inbound_amneziawg.go's
  new checkForwardedPortsConflict uses it to reject, at save time, a
  client's forwardedPorts that would DNAT the panel's own port or
  another enabled inbound's port to the tunnel client --
  portForwardLines has no destination restriction, so this collision
  was previously silent. Wired into both the single-client update path
  and the add-client path (client_inbound_apply.go), plus
  normalizeAmneziaWGSettings for the whole-inbound save path. (Finding 14)

- inbound.go: InboundOption.AwgServer sent the whole ServerSettings
  struct including PrivateKey to GetInboundOptions callers -- a
  shared, admin-wide dropdown-filling endpoint the frontend's own
  AwgServerOptionSchema never reads that field from. Redacted it
  before assigning. (Finding 11)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(amneziawg): don't widen the peer address pool past AmneziaWG's own subnet

Completes Finding 12 from the automated PR review (the serverAddress half
of this finding was already fixed on main and cherry-picked here). This
half is specific to this branch: allocateWireguardAddress's /16
pool-widening fallback is an independent addition from upstream's own
main that this branch inherited during the cherry-pick rebase -- it
doesn't exist on the fork's own main at all, so this fix can't be
cherry-picked the normal way and is committed directly here.

Widening is safe for WireGuard's own Xray-native inbound (AllowedIPs
isn't tied to a strict kernel interface subnet), but AmneziaWG's kernel
interface Address is exactly the configured subnet -- an address
allocated from the containing /16 once the /24 fills up would be
silently unroutable. allocateWireguardAddress now takes an explicit
allowWidening bool: WireGuard's own caller passes true (unchanged
behavior), AmneziaWG's passes false (fails loudly on exhaustion instead).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* docs(docker): note that AmneziaWG doesn't work in this image

Investigated: the image is Alpine-based, and AmneziaWG's own packaging
(DKMS module + amneziawg-tools) doesn't target Alpine/musl at all --
unlike the Debian/Ubuntu/Fedora/Arch paths install.sh already handles,
there's no package to apk add even with full host network/capabilities.
The panel already degrades gracefully (IsAwgInstalled() logs one warning
instead of retrying forever), so no code change is needed -- just made
the reason explicit at the point where a user would reach for cap_add/
network_mode to try to work around it.

* fix(sub): include amneziawg inbounds in subscription links

getInboundsBySubId's SQL protocol allowlist never had 'amneziawg' added,
so every AmneziaWG client was silently excluded from all three
subscription formats (plain/individual links, JSON, Clash) and from the
Telegram bot's QR/individual-link buttons, which fetch through the same
path. genAmneziaWGLink itself was already fully implemented and already
wired into GetLink's dispatch switch -- it just never got a chance to
run. Same bug shape as the earlier TRACKED_PROTOCOLS frontend gap: a
hardcoded protocol list one entry short.

Found while investigating whether the Telegram bot needed AmneziaWG-
specific client-management code -- it doesn't (the bot itself is fully
protocol-agnostic), but this is the actual root cause of "can't share
an AmneziaWG client's config via the bot."

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(inbound): enforce node-eligibility server-side, not just in the UI

Investigated multi-node interaction with AmneziaWG: the master's own
reconcile (DesiredAmneziaWGInstances) and Xray config generation
(injectAmneziawgEgress, the GenXrayInboundConfig protocol skip) all
correctly filter on NodeID IS NULL, so a node-assigned AmneziaWG (or
MTProto) inbound would never be managed by the master. But nothing
stopped one from being created that way: NODE_ELIGIBLE_PROTOCOLS
(frontend/src/pages/inbounds/form/InboundFormModal.tsx) only hides the
node picker client-side -- a direct API call could set nodeId on an
AmneziaWG inbound, which every node then reconciles as an ordinary
local inbound (nodes run the identical binary, full cron suite
included), leaving it running unmanaged and untracked by the master's
own AmneziaWG bookkeeping.

Added isNodeEligibleProtocol (inbound_protocol.go), mirroring the
frontend's allowlist, and enforced it in both AddInbound (the actually
exploitable path -- nodeId comes straight from the request) and
UpdateInbound (defense in depth; NodeID is already restored from the
stored row there before this check, so it mainly guards against a
protocol change on an existing node-hosted inbound).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(amneziawg): allow TPROXY-marked traffic through a default-deny INPUT chain

TPROXY never rewrites a packet's own destination address, only the routing
decision. A default-deny firewall whose INPUT chain sanity-checks "is this
destination actually local" (UFW's ufw-not-local, via addrtype --dst-type
LOCAL, is a concrete example) silently drops the redirected packet before
Xray's socket ever sees it -- RouteThroughXray looked fully configured
(TPROXY rule present and counting, Xray listening with IP_TRANSPARENT set)
yet every peer's traffic vanished with no trace on either side.

Adds an idempotent, never-torn-down "iptables -I INPUT 1 -m mark --mark
<fwmark> -j ACCEPT" alongside the existing shared policy route, so this
works regardless of which firewall manager owns the rest of the INPUT chain.

* fix(frontend): give AmneziaWG the same UDP tag and its own tag color

The Inbounds list only special-cased isWireguard/isHysteria for the "UDP"
network badge, so an AmneziaWG row showed just the bare protocol tag with
no transport badge next to it. Added the missing isAmneziawg flag (mirrors
isWireguard exactly) and wired it into the same branch.

Client-row protocol-color maps in ClientsPage/HostList had no amneziawg
entry, silently falling back to grey -- ClientInfoModal already had
amneziawg: 'yellow' from earlier work, these two just never got it.

* feat(logs): show which AmneziaWG client an access-log line belongs to

The dokodemo-door TPROXY bridge every AmneziaWG peer's traffic is routed
through has no per-user identity, so Xray's own access log never carries an
"email:" token for these lines -- the Access Logs modal showed a blank
Email column for every in-*-udp row, even though every other protocol's
rows show the client normally.

The peer's decapsulated tunnel IP does survive as the log's "from" address,
and that IP deterministically maps to exactly one configured peer. Builds a
"<inbound tag>|<ip>" -> email index from the same AmneziaWG inbounds already
parsed elsewhere (amneziawg.InstanceFromInbound), and fills in Email from it
whenever the raw log line didn't have one.

* fix(amneziawg): enable sniffing on the TPROXY bridge

Domain-based Routing rules could never match RouteThroughXray traffic: an
AmneziaWG peer resolves DNS itself, through the tunnel, before ever sending
a packet, so the decapsulated traffic TPROXY hands to the bridge is already
a bare destination IP with no domain name attached at the network layer.
Every other inbound recovers this via sniffing (confirmed working for the
stock wireguard inbound, which does have it configured); the bridge never
got a sniffing block at all, so only tag/IP/network-based rules could ever
match it -- any domain rule above it in the list was silently unreachable.

* docs: add an AmneziaWG config page and list it as a supported protocol

Closes the PR checklist gap: the feature shipped with zero mention on
the docs site. Mirrors reality.mdx's structure (key settings, setup
steps, config excerpt) and notes the Docker/multi-node/Telegram-bot
caveats the PR itself is honest about not having confirmed.

* fix: address the fresh review round on PR #6105 (8 findings)

1. hostRulesFingerprint didn't account for ForwardedPorts when
   RouteThroughXray was off, so re-IPing a peer with port-forwarding
   configured left stale DNAT rules pointing at an address the next
   peer could be handed.
2. Server/client config values (keys, email, I1) were never validated
   for control characters before being written into the generated
   .conf; a newline could smuggle a PostUp hook into awg-quick's
   parser. Added ValidateConfigValue at save time and a
   sanitizeConfigValue backstop at render time.
3. checkForwardedPortsConflict didn't scope to node_id IS NULL, so a
   port used only on a different node produced a false collision; also
   hoisted the panel-port/inbounds lookup out of the per-client loop
   (portConflictContext) so N clients cost one query, not N.
4. PostDown commands were ";"-joined and abort on the first failure;
   appendOrTrue makes teardown best-effort so an external firewall
   flush can't leave DNAT rules to accumulate across bounces.
5. The "ip rule list | grep -q" existence check could SIGPIPE under
   pipefail and re-add a duplicate rule; switched to grep -c >/dev/null.
6. Ported the vpn:// share-link format (base64url of the plain .conf
   text, matching the real AmneziaVPN app) onto this branch -- it had
   only ever landed on our own fork's main, so this PR branch was still
   on the old amneziawg://+query-params scheme our own docs no longer
   described. Also corrected the docs' install.sh claim (opt-in/
   interactive, not automatic) and stale pre-opt-in comments in
   route_egress.go.
7. install.sh: Arch's ndppd install used pacman -Syu (full system
   upgrade) instead of -Sy like every other call in the script; and
   should_install_amneziawg re-prompted on every `x-ui update` even
   when awg was already installed.
8. CollectTraffic could clobber a concurrent restart's freshly-reset
   (empty) traffic baseline with stale pre-restart counters, since
   getPeerStats runs lock-free; now checks pointer identity before
   writing back. sweepOrphansLocked permanently disabled itself on a
   transient os.ReadDir failure instead of allowing a retry.

go build/vet/test and frontend typecheck/lint/build/vitest all pass.

* fix(install.sh): check the live sysctl value, not sysctl.conf text

Reviewer feedback (cherts, PR #6105): grepping /etc/sysctl.conf for the
setting name is unreliable -- many distros split sysctl config across
/etc/sysctl.d/*.conf, and /etc/sysctl.conf can be a symlink into that
directory, so the check can miss an already-active setting (harmless
duplicate append) or match a disabled/commented line (forwarding
silently stays off). Query the live value via `sysctl -n` instead,
which is accurate regardless of which file set it. Applied the same
fix to both the IPv6 and IPv4 checks for consistency.

* fix: update inbound_amneziawg.go to the split buildInboundForLocalRuntime

Same fork-only-file blind spot as the one caught on our own main after
the 3.6.0 sync: upstream split buildRuntimeInboundForAPI into
buildInboundForNodePush / buildInboundForLocalRuntime (part of the
node-sync client-deletion fix, 5bc81dfd), updating every call site it
could see. This file doesn't exist upstream, so it kept calling the
old name even after the branch merged in that commit.

* fix(frontend): recognize AmneziaWG's vpn:// scheme in share-link labels

The shared link-tag/label helper (used by the client info modal, QR
modal, and subscription page) had no entry for the vpn:// scheme
AmneziaWG links use, so it fell through to the generic fallback: a
plain "Vpn" tag with no color, and an empty remark/port that made the
row's title fall back to "Link N" instead of the inbound's actual
name:port — unlike every other protocol, which shows its real tag and
label.

vpn:// links are base64url of a plain .conf text (matching the real
AmneziaVPN app's own share-link format), not a structured URL, so
there's no query string or #hash to read a remark/port from. Decode
the payload and pull the remark/endpoint back out of the .conf text
directly instead.

* fix(xray): force a full restart for TPROXY inbounds, never hot-add them

Real incident: an AmneziaWG inbound with RouteThroughXray enabled lost
all internet on that connection after a migration. Root-caused on the
live box -- iptables TPROXY counters were incrementing (packets
correctly redirected to 127.0.0.1:63110), but nothing was actually
listening there (ss showed nothing on that port) until a full
`systemctl restart x-ui`, after which the bridge came up immediately.

Xray-core's gRPC AddInbound reports success for a new sockopt.tproxy
inbound (internal/amneziawg's own Xray egress bridge is the only kind
this fork ever generates) but doesn't reliably bind a working listener
for it outside of process startup -- the bridge silently never comes
up, and RouteThroughXray traffic goes nowhere until the next full
restart happens to occur for an unrelated reason.

diffInbounds already has this exact defensive pattern for REALITY
inbounds ("a gRPC remove+add does not reliably rebuild the REALITY
authenticator"), just never extended to TPROXY, and only in the
already-existing-then-changed branch -- the "brand new inbound" branch
had no such guard at all, which is exactly the path a freshly-enabled
RouteThroughXray bridge takes. Added inboundUsesTproxy and wired it
into both branches.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(amneziawg): flag Xray for resync when a peer edit changes qualifying state

Real production bug, root-caused on iiadmin-vps: updateAmneziaWGInbound/
AddInbound/DelInbound only ever updated the kernel interface via
amneziawg.GetManager() -- they never called SetNeedRestart the way every
other protocol's mutation path does (client_crud.go, inbound.go, etc. all
do). injectAmneziawgEgress's TPROXY bridge inbound depends on
InstanceFromInbound finding at least one qualifying peer plus
RouteThroughXray, so an edit that flips that (first peer added, last one
removed, RouteThroughXray toggled on) previously required a full panel
restart before the bridge actually got created, with no error anywhere:
the kernel interface would handshake fine, but traffic redirected into the
bridge's TPROXY port went nowhere because nothing was listening there.

diffInbounds/inboundUsesTproxy already correctly force a full restart for
a brand new TPROXY inbound (bdee0a20) -- that part was never the bug. The
gap was entirely upstream: nothing ever told Xray a resync was even needed.

* fix(clients): reject AllowedIPs already used on another WireGuard/AmneziaWG inbound

defaultWireguardClients/defaultAmneziaWGClients only ever checked uniqueness
against their own inbound's client list, so two inbounds sharing a subnet
(same protocol or not) could silently hand out or accept the same address --
the exact scenario behind a real duplicate-IP incident where a WireGuard and
an AmneziaWG client both ended up on the same address. otherTunnelAllowedIPs
now collects every address already claimed on every other tunnel inbound and
folds it into both the auto-allocation pool and the manual-entry collision
check, naming the other inbound in the error when it fires.

* fix(frontend): add the missing AmneziaWG config download on the sub page

The subscription page already gave WireGuard links their own "Config"
block (copy/download/QR of the actual .conf, via wireguardConfigFromLink
reversing the wireguard:// query params) but had no equivalent for
AmneziaWG's vpn:// links -- its isWireguardLink gate never matched them,
and no reverse-parse helper existed for this page specifically. Every
other surface (InboundInfoModal, ClientInfoModal, ClientQrModal) already
had this parity; this was the one page that didn't.

Fixed by adding amneziawgConfigFromLink (inbound-link.ts), simpler than
its WireGuard counterpart since a vpn:// payload already *is* the plain
.conf text -- just base64url-decode it, no query-param reconstruction
needed -- and wiring it into SubPage.tsx alongside the existing WireGuard
block, reusing the same pages.clients.amneziaWgConfig label the other
three surfaces already use.

* fix(xray): force a full restart for password-auth SOCKS5 hot-apply

Real production incident: editing a client under an AmneziaWG inbound
left its embedded SOCKS5 relay's settings byte-different (a new account
list), and Xray's gRPC remove+add hot swap silently dropped the account
for a peer whose email contained non-ASCII characters -- its tunnel kept
handshaking fine but all its traffic got rejected at the SOCKS5 layer,
while every other peer on the same relay was unaffected. A full restart
(reading the same JSON straight from disk) always produced the correct
account list. socks isn't in userDiffableProtocols (that only covers
vless/vmess/trojan's clients+email shape, not accounts+user), so any
settings drift on this inbound fell through to the generic remove+add
path. Forces a restart instead, the same defensive choice already made
for REALITY and TPROXY -- scoped to auth:"password" specifically so the
other, noauth SOCKS5 bridges (panel/node/mtproto egress) keep the cheaper
hot path.

* Fix Attach reusing one identity's address across wg/awg inbounds

ClientService.Attach deliberately copies one identity's stored
AllowedIPs into every WireGuard/AmneziaWG inbound it's attached to
in the same call, so the same person gets the same tunnel address
on every protocol they use. Its loop calls addInboundClient once per
inbound, and each of those independently computes
otherTunnelAllowedIPs -- so by the second inbound in the batch, the
first inbound's just-written copy of this identity's own address
looked like a cross-inbound collision against itself.

Real production symptom this caused: detaching then re-attaching a
client to both wg and awg failed with "wireguard: allowedIPs entry
X is already used by a client on inbound 'awg' (#N)" -- the exact
address the identity is supposed to keep, rejected as if it belonged
to someone else.

Add a selfEmails exclusion to otherTunnelAllowedIPs and populate it
from the client(s) being processed at the one real call site. Safe
unconditionally: ClientRecord.Email is globally unique, so a match
can only ever be this same identity's own entry on a sibling inbound,
never a genuine different client's address.

Reproduced the underlying mechanism live (manual entry correctly
rejected as a cross-inbound collision; fresh auto-allocation
correctly avoided a used address) before writing the fix, to confirm
the guard itself works and the bug is specifically in how Attach's
per-inbound calls interact with it.

* Attach: allocate fresh when re-attaching with no active tunnel

The previous fix (82cc69f5) made Attach's own address-reuse
correctly not collide with itself across inbounds -- but it still
always reused an identity's stored AllowedIPs verbatim, even when
that identity currently has zero WireGuard/AmneziaWG attachments at
all. A real report from testing this live: an identity fully
detached from both its wg and awg inbounds, then re-attached, got
its old address back even though several lower addresses were free
-- because nothing about being fully detached ever cleared the
stored value Attach copies from.

Add hasTunnelAttachment, checked once against the identity's CURRENT
inbound set before Attach's loop runs: if none of its current
inbounds is WireGuard/AmneziaWG, clear the stored AllowedIPs so this
attach allocates fresh (matching what a brand-new client would get)
instead of resurrecting an address nothing reserves anymore. Left
alone when the identity already has an active tunnel elsewhere, so
extending it to a second protocol still keeps a consistent address.

* Fix TestOtherTunnelAllowedIPsExcludesSelfEmail's own test setup

CI caught this: the "genuinely different client" (other@wg) was
seeded onto the SAME inbound passed as excludeID, which
otherTunnelAllowedIPs already excludes entirely regardless of the
selfEmails fix -- so the assertion that its address is still
reported could never have passed, proving nothing either way. Move
it onto the sibling inbound alongside shared@id, which is what the
test actually needs to exercise (two clients on one sibling, one
excluded by email, one not).

* Attach: never inherit an address that doesn't fit the target inbound

hasTunnelAttachment (from the earlier fix, commit 51067f16) only
asked "does this identity have ANY tunnel attachment", treating that
as license to reuse its stored address verbatim on every inbound
being attached. Real production case this missed: an identity's
stored address came from WireGuard's own fallback subnet
(10.0.0.0/24, used when that inbound has no other clients to infer a
base from), then got attached to a second, AmneziaWG inbound
configured for a completely different subnet (10.8.1.0/24).
defaultAmneziaWGClients's already-set-AllowedIPs branch only checks
for collisions, never subnet membership, so the mismatched address
was accepted silently -- producing a peer that can never actually
connect, since an AmneziaWG address must fall inside the kernel
interface's own configured subnet to be routable at all.

Add addressesFitAmneziaWGInbound, checked per inbound inside Attach's
loop: if the inherited address doesn't fit the SPECIFIC inbound being
attached, clear it just for that one so it gets a fresh, valid
allocation instead, while other already-attached inbounds keep their
existing values. WireGuard has no equivalent strict subnet
requirement (allocateWireguardAddress can widen to a fallback pool
for it), so this only ever constrains AmneziaWG targets.

* Give WireGuard an explicit, admin-configurable subnet field

WireGuard previously had no configurable subnet at all -- only an
implicit one, either inferred from existing clients' own addresses
(wireguardAllocationBase) or a hardcoded 10.0.0.0/24 fallback when
none exist yet. AmneziaWG, by contrast, has always had a real
server.subnetIp/subnetCidr field in its settings, editable in the
UI. User request: give WireGuard the same treatment.

Backend: explicitWireguardSubnetBase reads an optional subnetIp/
subnetCidr pair from the inbound's own settings JSON (mirroring
AmneziaWG's defaultAmneziaWGSubnetBases). defaultWireguardClients
checks it first; only when unset does it fall back to today's
inference-from-existing-clients behavior, so an inbound saved before
this field existed keeps working exactly as it always has.

Frontend: subnetIp/subnetCidr added to WireguardInboundSettingsSchema
and the inbound form (mirroring AmneziaWG's own field layout/labels),
with a real default (10.0.0.0/24, the same value the backend already
fell back to) seeded for newly created inbounds so the field starts
populated and editable rather than blank. Translated across all 13
locales.

This also structurally closes the class of bug fixed in
82cc69f5/291c47b3: with wg and awg subnets explicit and
independently controllable, an admin who wants matching addresses
across both protocols can configure them to actually agree, instead
of one silently inheriting the other's incompatible range.

* Split the client edit form's AllowedIPs into per-protocol fields

A client attached to both WireGuard and AmneziaWG shared one AllowedIPs
form field with a dynamically-switching label, so its two genuinely
different addresses could never both be shown or edited correctly.
Worse, Update/Create broadcast that one shared value to every attached
wg/awg inbound with no subnet-fit check, so an ordinary edit save could
silently overwrite one protocol's address with the other's -- the same
bug class already fixed for Attach, but reachable from any client edit.

model.Client gains an optional AllowedIPsByInbound map so a caller can
send distinct values per inbound; Update/Create honor it and, when it's
absent, clear a shared value that doesn't fit an AmneziaWG inbound's own
subnet instead of writing it through. A new TunnelAllowedIPsByInbound
read path feeds the real per-inbound address to the client edit form via
GET, which now renders two separate, correctly-labeled fields whenever
both protocols are attached (unchanged single dynamic field otherwise).

* Regenerate openapi.json for the new allowedIPsByInbound field

Follow-up to 878ee839: gen:zod (frontend/src/generated) was already
regenerated and committed, but gen:api (frontend/public/openapi.json)
wasn't, so CI's codegen drift check failed.

* Fix build breakage from merging upstream main: Update() gained a limitHwid param

Two of our own AllowedIPs tests (not present upstream, so the merge never
flagged them as conflicting) still called the old 3-arg Update(inboundSvc,
id, client) -- upstream's hardware-ID-limit feature added a required
limitHwid parameter that every other caller in this package already
passes. Also drop createDefaultInboundSettings from InboundsPage.tsx: the
merge conflict resolution kept the import, but upstream's clone-payload
refactor (buildClonePayload, inbound-clone.ts) already calls it
internally now -- this file doesn't need it directly anymore.

* Fix real bug: AmneziaWG clients rejected as "empty client ID" in 3 places

Three switch statements on inbound.Protocol handle "wireguard" explicitly
(checking client.PublicKey) but fall through to the default case for
"amneziawg" (checking client.ID, which AmneziaWG clients never set --
they use PublicKey/Email like WireGuard, not the VMess/VLESS UUID field).
This is what the 4 AllowedIPs tests were actually catching:
UpdateInboundClient's newClientId derivation hit this same default branch,
so every Update() on an AmneziaWG client returned "empty client ID"
before ever reaching the AllowedIPs logic being tested.

Fixed by adding "amneziawg" alongside "wireguard" in each switch:
addInboundClient's per-client validation, UpdateInboundClient's
newClientId derivation, and AddInbound's per-client validation (the
third one wasn't hit by these tests, but has the identical bug -- creating
a brand-new AmneziaWG inbound with a client attached would fail the
same way).

* refactor(amneziawg): rename Obfuscation20 to Obfuscation31, drop the dead mobile preset

Mechanical rename ahead of the AmneziaWG 3.1 parameter work: the type,
generator and prose all said 2.0, and the "mobile" generator preset was
reachable only from its own test. No behavior change.

* feat(amneziawg): AmneziaWG 3.1 obfuscation parameters (backend + generated schemas)

Adds the 3.1 parameter surface to the inbound settings and both Go config
emitters: I2-I5 signature packets, HeaderProtectionKey (base64 32-byte,
shared server<->client), ContentPaddingAddition, the five handshake-timing
randomization ranges (RekeyAfterTime/RekeyTimeout/RejectAfterTime/
KeepaliveTimeout/MaxHandshakeAttempts), and the RandomTrailers/
DisableCookies switches. Freshly generated sets fill everything except
I2-I5 (matching Amnezia's own generator) with jittered ranges bracketing
WireGuard's stock timing constants; every reject window starts >= 30s
above the rekey window by construction. Empty fields stay off the wire,
so blanking a field disables just that feature.

Validation generalizes the H1-H4 range checker for the new uint32-range
fields, requires min 1 on timers, cross-checks rekey-vs-reject, and
demands a real 32-byte base64 header-protection key. The manager warns
once per process when the installed awg tools predate 3.1 but an inbound
uses 3.1 parameters (awg-quick rejects unknown keys with a generic
error otherwise); apply still proceeds.

Requires amneziawg-tools v3.1.20260812+ / module or amneziawg-go
v3.1.20260814+ on the host.

* feat(amneziawg): emit and randomize 3.1 parameters in the frontend

Both client-config emitters (the vpn:// link builder and the clients-page
.conf builder) now carry the 3.1 [Interface] lines in the same order as
the Go emitters. The obfuscation randomizer moves out of InboundFormModal
into a shared lib/xray/amneziawg-obfuscation.ts that also fills the new
fields, and createDefaultAmneziawgInboundSettings switches from static
values to that generator — a fresh inbound now really gets the unique
fingerprint the docs promise instead of the same jc=5/jmin=10 set on
every install.

Schema parse-time defaults for the new fields stay ''/false on purpose:
real values come only from the generator, so resaving an inbound never
mutates its stored parameters. A new parity test pins the hand-written
AmneziawgServerSchema to the generated ServerSettings key set, so a field
added on one side can no longer silently vanish from configs.

* feat(amneziawg): 3.1 form fields and translations

Inbound form gains inputs for I2-I5, HeaderProtectionKey (filled by the
existing obfuscation Regenerate button), ContentPaddingAddition, the five
timing ranges, and the RandomTrailers/DisableCookies switches; the MTU
input picks up the min=1 its schema already enforced. All 13 locales get
the 19 new keys and drop the "2.0" branding from the s3/s4/i1 labels.

* docs(amneziawg): document 3.1 parameters; install.sh kernel/version notes

The AmneziaWG page's obfuscation section moves from the 2.0 to the 3.1
parameter set: table rows for I2-I5, HeaderProtectionKey,
ContentPaddingAddition, the timing-randomization ranges and the
RandomTrailers/DisableCookies switches, a requirements callout (tools
v3.1.20260812+, module/awg-go v3.1.20260814+, Linux 6.7+ for the DKMS
path), and a sample client .conf that matches what the panel actually
emits (including the DNS defaults and PersistentKeepalive it always had).

install.sh warns before a DKMS build on a pre-6.7 kernel and after any
install that left pre-3.1 amneziawg-tools on PATH.

Also updates the hosts API operation paths ({id} -> {groupId}) in the
stale ru/zh/fa reference pages: syncing docs/public/openapi.json for the
new AmneziaWG schema fields surfaced that rename, which had never been
copied over, and the docs build fails on paths missing from the spec.

* fix(amneziawg): reject control characters and canonicalize 3.1 range values

Adversarial review of the 3.1 work surfaced a validation gap:
base64.DecodeString silently ignores CR/LF, so a header-protection key
that picked up a line wrap in transit decoded to a valid 32 bytes,
passed validation, and was emitted verbatim into every client config —
where the orphan second line breaks the import while the server (whose
emitter strips control chars) keeps running with the correct key. The
key and range validators now reject control characters outright.

Also from the same review: range values are canonicalized on save
("110 - 140" -> "110-140", whitespace-only collapses to feature-off,
closing a case where the server conf rendered an invalid blank-value
line the client emitters omitted); the rekey/reject invariant is now
enforced against WireGuard's 120s/180s defaults when only one side is
set; and the structural fingerprint joins on "\n" instead of "|",
which is a legal I1-I5 character and made adjacent free-text fields
join-ambiguous.

* fix(install): resolve latest release tag via web redirect to dodge API rate limits

The non-interactive install smoke test resolved the release version through
the unauthenticated GitHub API (api.github.com/.../releases/latest), which
allows only 60 requests/hour per IP. The test installs twice in one run, and
on shared CI runner IPs the second call gets rate-limited, returns no
tag_name, and install.sh treats an empty version as fatal (exit 1) — the same
"Failed to fetch x-ui version" real users hit behind CGNAT/shared addresses.

resolve_latest_tag() now reads the tag from the github.com releases/latest
web redirect (not subject to the API rate limit), falling back to the API
only if the redirect yields nothing. Verified with the real
deploy/test/smoke-noninteractive.sh (two installs, both green).

* fix(amneziawg): three review findings on #6105, plus a comment trim

1. A peer's allowedIPs reached the generated .conf unvalidated and
   unsanitized, unlike email/publicKey/preSharedKey which
   normalizeAmneziaWGSettings already guards. A newline in an entry let a
   following "[Interface]" re-open the interface section, whose "PostUp = ..."
   awg-quick then runs as root on the next apply. Reproduced end to end
   against generateServerConfig. The save path now rejects and canonicalizes
   through normalizeWireguardAllowedIPs, and the render path sanitizes as a
   backstop for rows predating the validation (an upgrade, a restored backup,
   a direct DB edit). H1-H4 get the same render-time sanitize, and the two NIC
   name fields a plausibility check, since stripping control characters alone
   would still let a shell metacharacter into a root-executed PostUp line.

2. EgressPortForInbound is 63100 + inbound id, so an id past 2435 derives a
   port above 65535 -- and Xray rejects the whole generated config over one
   invalid port, taking every other protocol down with it. It now reports
   ok=false past the range, and both the Xray bridge and its TPROXY rules are
   skipped instead of emitting an impossible port.

3. The downloadable AmneziaWG .conf read ClientRecord.allowedIPs, a single
   shared column that holds the WireGuard address for an identity attached to
   both protocols -- the exact ambiguity tunnelAllowedIPs was added to resolve
   for the edit form. The info and QR modals already hydrate that field, so
   they now pass this inbound's own address to the builder.

Also trims the comment blocks in the files touched here to the 2-line
guidance in CLAUDE.md: internal/amneziawg alone carried 423 comment lines in
over-long blocks against 118 for the comparable internal/mtproto, and is now
at 110. Every non-obvious constraint is kept (the kernel S1/S2 rule, why
PostDown is best-effort, why grep -c and not -q, why the fingerprints split
three ways); the narration is gone. Two hot_diff.go comments pointed at an
internal/amneziawgnet package and an injectAmneziawgnetSocks function that
exist nowhere in the tree; the checks themselves are unchanged.

* feat(logs): add an AmneziaWG log view to the overview

The overview has an access-log view for Xray but nothing for AmneziaWG, so
when a tunnel misbehaves there is no way to see it from the panel at all. A
kernel tunnel logs no per-request lines, so the equivalent view is built from
the two things it does expose:

- Live per-peer activity from `awg show <iface> dump`, joined to the client
  email through the desired peer set: last handshake, endpoint, allowed IPs,
  cumulative transfer and online state, newest handshake first.
- The panel's own AmneziaWG event lines (interface up/down, awg-quick
  failures, the pre-3.1 tools warning), which are what actually explain a peer
  being absent from the table.

POST /panel/api/server/amneziawglogs/:count serves both, with the same
count + filter contract GetXrayLogs uses, and the modal mirrors XrayLogModal's
toolbar, auto-update, mobile cards and download. The action-bar button is
gated on a new status.amneziawg.configured, which stays true while an inbound
exists but its interface is down -- exactly when the event lines matter.

Verified against a running panel: the endpoint returns the peer table and
real event lines ("awg/awg-quick not found on PATH", "create config dir:
permission denied"), and count and filter both narrow as documented.

One of those lines surfaced a Debugf that had been rendering as
"for inbound1:amneziawg:"; fixed here since it is now user-visible.

* fix(amneziawg): stop double-counting a routed inbound's traffic

injectAmneziawgEgress tags its Xray bridge with the AmneziaWG inbound's own
tag, so the stock Routing page can target it. Xray therefore reports that
bridge's bytes under the inbound's tag, and XrayTrafficJob feeds them to
AddTraffic -- which accumulates -- on top of the same bytes AmneziaWGJob
already reported from `awg show dump`. An inbound with routeThroughXray on
counted roughly twice its real traffic, which also inflates the quota checks
that read the same counters.

The awg counters are the complete measure: every peer, whether or not TPROXY
routed it, and the same wire bytes the per-client totals are built from, so
they stay and the Xray rows are dropped. Per-client stats were never affected
-- a dokodemo-door bridge has no per-user identity, so Xray emits no
user>>>email rows for it.

Filtering happens before every consumer, so the DB totals, the external
traffic inform and the dashboard's live speed all read one source per inbound.
The set of bridge tags now comes from a predicate shared with
injectAmneziawgEgress itself, with a test that pins the two together -- naming
one tag too few doubles the traffic again, one too many makes real traffic
vanish.

* fix(amneziawg): align the three .conf emitters on one peer field order

The panel builds an AmneziaWG client .conf in three independent places, and
they disagreed: buildAmneziaWGClientConfig put PresharedKey right after
PublicKey (wg-quick(8)'s own order, and what both WireGuard emitters on the
clients side already use), while genAmneziaWGConfig and the Go
amneziaWGConfigText put it after Endpoint. A user comparing a subscription
link against a downloaded .conf sees the difference immediately, and the
generators are exactly the kind of parallel implementation CLAUDE.md warns
about drifting.

Moves the two outliers onto the wg-quick order. Also drops the stray trailing
newline that only appeared when PersistentKeepalive was set, so a config now
always ends on its last set field whichever that is -- the same shape all
three emitters produce for the same client.

Parsing is unaffected either way (the format is order-insensitive, and the
AmneziaVPN app reads it as a flat key-value bag), so this changes only the
rendered text. Adds a test on each side that pins the peer block's field
order, since nothing previously asserted it.

* refactor(amneziawg): switch to the embedded amneziawg-go/gVisor architecture

Replaces the kernel-module (DKMS) + awg-quick + TPROXY backend with the
fork's own embedded design: amneziawg-go runs in-process over a userspace
gVisor netstack, and each peer's decapsulated traffic relays into its own
loopback Xray SOCKS5 inbound, so Xray's native stats/sniffing/routing work
for free instead of through hand-rolled bridges. No kernel module, no DKMS,
no Secure Boot conflicts, works the same in a container as on bare metal.

- internal/amneziawgnet: new package (Device/UAPI, gVisor netstack, TCP/UDP
  forwarding, SOCKS5 relay, peer identity, IPv6 host-alias egress identity,
  per-client port-forwarding) - amneziawg-go v3.1.20260814 + gvisor.
- internal/amneziawg: keep the reusable protocol-shape types/validation
  (Instance/Peer/Obfuscation, InstanceFromInbound); drop the OS-shellout
  half (awg-quick, TPROXY policy routing, NDP proxy, peer-stats parsing).
- internal/web/service: rewire the 5 integration points (job, runtime,
  client-apply, web shutdown, xray config) from the old manager to the new
  one; the AmneziaWG log view is rebuilt on the embedded Device's own UAPI
  dump (extended to carry endpoint/AllowedIPs) instead of `awg show dump`.
- install.sh: drop DKMS/ndppd/TPROXY/Secure-Boot installer code (~250
  lines) - an entire recurring class of installer fragility goes away.
- frontend: drop the now-meaningless routeThroughXray toggle (the relay is
  always on); keep the field in the Zod schema, unexposed, so it isn't
  silently stripped from stored settings on next save - two regression
  tests deliberately depend on the Go struct still carrying it.
- docs/i18n: rewrite amneziawg.mdx for the new architecture; drop the
  dead routeThroughXray translation keys across all 13 locales.

Real production throughput (embedded core datapath, isolated bench, same
box the kernel-module path was measured on): ~296 Mbit/s up, ~640 Mbit/s
down, vs. 414.69 MB/s (~3.3 Gbit/s) for the kernel module on the same
hardware - a real gap, tempered by this being single-stream/no-SOCKS5-hop
and most VPN traffic being latency-bound rather than throughput-saturating.

* fix(amneziawg): restore the branch's own Obfuscation31 shape + 2 CodeQL findings

The previous push's wholesale-copy of types.go/params.go from the fork's
main branch pulled in that branch's own independent (and incompatible)
naming for the same AWG 3.1 feature set: Obfuscation20/GenerateObfuscation20
instead of this branch's already-shipped Obfuscation31/GenerateObfuscation31,
and a missing CanonicalizeUintRange -- broke every Go CI job (the whole
matrix fails to compile when any one package doesn't, which is why govulncheck/
golangci/postgres-durable-first/race all failed identically, not just go-test).

Restores params.go/params_test.go verbatim from this branch's own last
commit (a strict superset of validation: it already cross-checks rekey vs.
reject timing windows, which the copied version never did) and folds the
3.0/3.1 fields (HeaderProtectionKey, ContentPaddingAddition, the 5 timing
fields, RandomTrailers/DisableCookies) into Obfuscation31 itself, matching
the original struct exactly instead of as separate top-level Instance
fields. instance.go, the two amneziawgnet call sites, and 7 amneziawgnet
test files updated to match. Also drops the one test (sanitizeConfigValue)
that only ever served the retired kernel-module .conf writer -- correctly
not ported, so the test testing it shouldn't have been copied either.

Also fixes 2 CodeQL findings the same push surfaced: a clamped uint64->int64
conversion for the new log view's live byte counters (server.go), and an
unneeded len+len sum feeding a slice pre-size in the v6-egress outbound
merge (xray.go) -- append already grows correctly without it.

* chore(amneziawg): regenerate frontend schemas for updated doc comments

npm run gen was missed after the previous commit's types.go doc-comment
edits (Obfuscation20 -> Obfuscation31, ValidateHeaderProtection ->
ValidateObfuscation in the prose) -- openapigen bakes those comments
into the generated schema's description field, so the committed
frontend/src/generated/schemas.ts and openapi.json still had the old
wording. codegen's git-diff-exit-code check caught it correctly.

* fix(amneziawg): narrow 2 test fixtures that collided with MaxForwardedPorts

TestCheckForwardedPortsConflict_CollidesWithEnabledInboundPort and
..._NoCollisionWhenPortsDontOverlap used "8000-8100"/"9000-9100" as their
ForwardedPorts fixture -- 101 ports each, one over MaxForwardedPorts (100).
The cap check (checkForwardedPortsConflict, added this session alongside
the SOCKS-phantom-port check) fires first, so both tests got "more than
100 forwarded ports" instead of ever reaching the collision logic they're
actually testing. The cap itself has its own dedicated boundary test
already; these two just needed a narrower range that still covers/misses
port 8080 as intended -- 8075-8085 and 9075-9085, 11 ports each.

* fix(amneziawg): checkAmneziawgnetSocksConflict had no receiver in its new home

My merge-conflict resolution kept this as a method call (s.checkAmneziawgnetSocksConflict)
inside checkPortConflictTx, a plain function with no *InboundService receiver --
upstream's #6225 fix moved the port-conflict check out of the (s *InboundService)
method and into this new tx-scoped free function, and I didn't notice the call
site needed to change shape too. CI caught it immediately (undefined: s); nothing
in this specific package can be locally verified past internal/database's own
unrelated, pre-existing CGO build issue on this dev machine.

Since the signature had to change either way, folded in the fix already flagged
as a separate follow-up: checkAmneziawgnetSocksConflict now takes the caller's
db handle instead of fetching its own via database.GetDB(), so it actually runs
inside the same serialized transaction #6225 introduced -- previously it sat
right next to that race fix without benefiting from it.

* fix: address the review findings on the embedded AmneziaWG PR

5 blocking findings:

- Floor S3/S4 at 12 in both obfuscation generators (Go and frontend) and
  reject a hand-edited value below that when HeaderProtectionKey is set --
  IpcSet requires it, and ~39% of previously-generated sets violated it
  silently.
- Guard PrivateKey/PrimaryDNS/SecondaryDNS/remark against newline injection
  in the AmneziaWG .conf builder (both the Go subscription-link path and
  the frontend downloadable-config path) -- unguarded, any of them could
  inject an arbitrary config line into a subscriber's client.
- Bound the derived AmneziaWG SOCKS relay port to <= 65535 once an
  inbound's id is known, and check the reverse direction (does the relay
  port collide with an existing inbound's port) on both create and update
  -- previously only port -> relay collisions were checked, not relay ->
  port.
- Gate injectAmneziawgV6Egress on the same V6AliasesActive predicate
  desiredV6Aliases already uses, so the two can't disagree about whether a
  peer's IPv6 identity is actually active at the OS level.

2 minor findings:

- Fix the forwarded-ports cap check's off-by-one (a spec covering exactly
  the cap was rejected as if it were over it).
- Correct docker-compose.yml's stale comment describing the retired
  DKMS/kernel-module architecture.

* chore: retrigger CI

build (armv5) failed on a transient Go module proxy network error
(INTERNAL_ERROR stream reset on sagernet/sing), unrelated to this PR's
changes.

* docs: fix doc comments still describing the retired DKMS/awg-quick design

A few doc comments (and one illustrative test log line) survived the
embedded-architecture cutover unchanged and now contradict the code
they sit next to:

- internal/amneziawg/types.go's package comment claimed this package
  still owns a Manager that reconciles OS-level interfaces via
  awg-quick/DKMS -- that Manager was removed; the reconcile loop lives
  in internal/amneziawgnet now, and this package is protocol-shape-only.
- internal/amneziawg/params.go's ValidateObfuscation/ValidateConfigValue
  comments cited "awg-quick up" / "awg-quick executes as root" as the
  reason to validate -- the server itself never calls awg-quick in this
  architecture; the same value still reaches a real rendered .conf that
  a client app or an admin's own awg-quick CLI applies downstream, so
  the validation is still warranted, just for a different consumer.
  Mirrored the same fix in inbound_amneziawg.go's matching comment and
  its test's comment.
- internal/amneziawgnet/manager.go's Manager doc comments (x3) pointed
  readers at "internal/amneziawg.Manager" for comparison -- that type no
  longer exists in this diff at all. Repointed at internal/mtproto.Manager,
  the pattern this was actually modeled on and the one that's still real.
- Swapped one test's illustrative "awg-quick up awg2 failed" log line for
  a message shaped like this architecture's actual amneziawgnet logging,
  so a reader skimming the test doesn't wonder whether the server still
  shells out to awg-quick.

No behavior change.

* fix(docs): re-run codegen for xray-settings.mdx after conflict merge

The automated conflict-resolution hand-merge for this generated file
was content-correct but didn't byte-match a real regen (different
YAML long-string folding style). Re-ran npm run gen + docs' gen:api
and kept that canonical output instead.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(amneziawg): drop the dead access-log email backfill

amneziawgEmailIndex keyed peers by "<tag>|<tunnel IP>", a scheme built
for the retired TPROXY bridge where the peer's decapsulated tunnel
address survived as the access log's from-address. The embedded
architecture relays through a loopback SOCKS5 dial, so every AmneziaWG
log line's from-address is 127.0.0.1:<ephemeral> and the lookup could
never match: the index was rebuilt on every log view just to miss.
Remove the index, its GetXrayLogs wiring and its test. If per-line
emails are wanted back, the relay would have to publish a
local-port->email registry for the viewer to resolve loopback sources.

* fix(api): generate AmneziaWGLogs/PeerActivity schemas instead of hand-writing them

The amneziawglogs endpoint's response structs were missing from
openapigen's StructAllow, so they were silently absent from every
generated schema/example, the endpoints.ts entry carried a hand-written
response, and AmneziaWGLogModal.tsx duplicated the shapes as local
interfaces - the exact drift the allowlist rule exists to prevent.
Allowlist both structs with example tags, point the endpoint at the
generated schema, import the generated types in the modal, and sync
docs/public/openapi.json.

* chore(amneziawg): drop the unreferenced quiccapture package

Nothing imports internal/amneziawg/quiccapture and no route exposes it;
its package doc justifies the code as a port of
frontend/src/lib/xray/i1Generators.ts, which does not exist in this
repository, and promises an API round-trip that also does not exist.
1,110 lines of unreachable code with misleading provenance claims.
Revert this commit to bring the package back when the live-capture I1
feature and its frontend counterpart actually land.

* fix(clients): re-run cross-inbound conflict checks on the serialized writer

The new client-level checks - cross-inbound AllowedIPs collisions and
AmneziaWG forwardedPorts conflicts - read a fresh DB snapshot, decide,
and only then enter runSerializedTx, while lockInbound only serializes
writers on the SAME inbound. Two concurrent client creates on two
different tunnel inbounds both passed the read and both committed,
yielding two peers with one address: the exact check-then-claim race
81cfd857 (#6225) closed for AddInbound, which this PR's own
checkAmneziawgnetSocksReverseConflict already cites. Keep the pre-tx
pass for fail-fast UX and re-validate inside the transaction, where the
single writer makes the answer authoritative. The race test drives two
goroutines at two inbounds and demands exactly one winner; it fails
with committed=2 when the in-tx re-check is removed.

* fix(amneziawg): hot-apply depletion disables like mtproto does

applyTrafficMutationBatch special-cases MTProto so a quota/expiry
depletion cuts the sidecar immediately, but AmneziaWG fell through to
runtime AddUser/RemoveUser - explicit no-ops for this protocol - so a
depleted peer kept tunneling until the next 10s reconcile tick. Route
it through applyLocalAmneziaWG, whose own contract (re-read committed
settings, filter depleted clients, push to the interface) is exactly
this case; the comment claiming it mirrors applyLocalMtproto is now
true for the depletion path too.

* fix(amneziawg): persist cleared DNS fields instead of resurrecting defaults

PrimaryDNS/SecondaryDNS marshaled with omitempty, so clearing them
persisted settings with no key at all - and the frontend re-parses
stored settings through a Zod schema whose .default('8.8.8.8') /
.default('8.8.4.4') fire on missing keys, silently repopulating the
form on every load and re-persisting the defaults on the next save.
Blank is a documented, meaningful state (no DNS line in client
configs); drop omitempty so a cleared value survives the round-trip.
The regression test normalizes a server block with cleared DNS and
fails when the keys are dropped.

* fix(amneziawg): accept cleared numeric obfuscation/subnet fields in the form

AntD InputNumber emits null when cleared, Zod .default() only replaces
undefined, and unlike wireguard.ts - whose optionalClearedInt comment
documents exactly this failure mode - the AmneziaWG schema declared
subnetCidr and jc/jmin/jmax/s1-s4 as bare z.number() defaults. Clearing
any of the eight fields made safeParse reject the null and block the
save until the user retyped a value. Absorb null into undefined while
keeping each field's schema default, so a cleared field refills its
documented default and legacy blobs with absent keys behave as before.

* fix(amneziawg): guard the third .conf emitter against newline injection

The review-round fix added the newline guard to amneziaWGConfigText (Go)
and buildAmneziaWGClientConfig, but genAmneziaWGConfig in inbound-link.ts
- the third of the three emitters its own comment says must not drift -
still rendered privateKey/primaryDns/secondaryDns/remark unescaped, so a
newline there injected a config line (e.g. a rogue PostUp) into the
inbound form's downloaded .conf. Add the same guard, plus the regression
tests the original fix shipped without: all four fields on the Go and
both frontend emitters go red if any guard is removed.

* test(amneziawg): pin the S3/S4 floors the TS drift guard claims to mirror

The test's docstring says it mirrors internal/amneziawg/params_test.go,
but it asserted S3>=8/S4>=4 while the Go test and both generators pin
12/12 - the floor ValidateObfuscation enforces whenever a header
protection key is set, which this generator always sets. A regression
narrowing the TS floors into 8-11/4-11 would have passed the drift
guard and produced configs the backend rejects on save.

* docs: restore the pia repo-map entry and document the AmneziaWG subsystem

Merging main dropped CLAUDE.md's internal/pia/ bullet (added by #6272)
while resolving the repo-map conflict - the package itself is untouched.
Restore it, add the missing map entries for the two packages this branch
introduces (internal/amneziawg/, internal/amneziawgnet/), bump the cron
count, and give amneziawg_job its row in architecture.md's 5.4 table.

* chore(amneziawg): correct comments stranded by the architecture pivot

ae77c7e9's cutover to the embedded gVisor path deleted the kernel-module
code but left several comments describing it in the present tense:
hot_diff.go cited the removed service.amneziawgEgressStreamSettings and
wrongly claimed AmneziaWG is the only sockopt.tproxy source (tunnel's
TProxy mode is the live one the guard protects), socks_config.go pointed
at the deleted EgressBasePort/EgressPortForInbound, manager.go referred
to the deleted Manager and its fingerprinting as live code, web.go's
cron registration claimed the job scrapes traffic (its own doc says it
does not), and types.go capped ContentPaddingAddition at uint16 when
validation and upstream both use uint32.

* style(lint): satisfy gofumpt/goimports so make verify is green

json_service.go's two 'Tag: "proxy"}' literals came in with main's own
cc245a90 formatting commit and fail the repo's gofumpt gate for everyone;
the import grouping in inbound_amneziawg.go is from the serialized-writer
fix on this branch.

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
2026-08-24 02:41:15 +02:00

12963 lines
375 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"openapi": "3.0.3",
"info": {
"title": "3X-UI Panel API",
"version": "3.x",
"description": "Programmatic interface to a 3X-UI panel. Authenticate either by logging in (cookie) or with an API token from Settings → Security → API Token (Bearer). All endpoints under /panel/api/* honour both modes — an API token is a full-admin credential, so treat it like the panel password."
},
"servers": [
{
"url": "/",
"description": "Current panel (basePath aware)"
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>`."
},
"cookieAuth": {
"type": "apiKey",
"in": "cookie",
"name": "3x-ui",
"description": "Session cookie set by POST /login. Browser-only."
}
},
"schemas": {
"AllSetting": {
"properties": {
"datepicker": {
"type": "string"
},
"expireDiff": {
"minimum": 0,
"type": "integer"
},
"externalTrafficInformEnable": {
"type": "boolean"
},
"externalTrafficInformURI": {
"type": "string"
},
"ipLimitAllowlist": {
"type": "string"
},
"ldapAutoCreate": {
"type": "boolean"
},
"ldapAutoDelete": {
"type": "boolean"
},
"ldapBaseDN": {
"type": "string"
},
"ldapBindDN": {
"type": "string"
},
"ldapDefaultExpiryDays": {
"minimum": 0,
"type": "integer"
},
"ldapDefaultLimitIP": {
"minimum": 0,
"type": "integer"
},
"ldapDefaultTotalGB": {
"minimum": 0,
"type": "integer"
},
"ldapEnable": {
"type": "boolean"
},
"ldapFlagField": {
"type": "string"
},
"ldapHost": {
"type": "string"
},
"ldapInboundTags": {
"type": "string"
},
"ldapInsecureSkipVerify": {
"type": "boolean"
},
"ldapInvertFlag": {
"type": "boolean"
},
"ldapPassword": {
"type": "string"
},
"ldapPort": {
"maximum": 65535,
"minimum": 0,
"type": "integer"
},
"ldapSyncCron": {
"type": "string"
},
"ldapTruthyValues": {
"type": "string"
},
"ldapUseTLS": {
"type": "boolean"
},
"ldapUserAttr": {
"type": "string"
},
"ldapUserFilter": {
"type": "string"
},
"ldapVlessField": {
"type": "string"
},
"outboundDownThreshold": {
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"pageSize": {
"maximum": 1000,
"minimum": 0,
"type": "integer"
},
"panelOutbound": {
"type": "string"
},
"remarkTemplate": {
"type": "string"
},
"restartXrayOnClientDisable": {
"type": "boolean"
},
"sessionMaxAge": {
"maximum": 525600,
"minimum": 1,
"type": "integer"
},
"smtpCpu": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"smtpEnable": {
"type": "boolean"
},
"smtpEnabledEvents": {
"type": "string"
},
"smtpEncryptionType": {
"type": "string"
},
"smtpFrom": {
"type": "string"
},
"smtpFromName": {
"type": "string"
},
"smtpHost": {
"type": "string"
},
"smtpMemory": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"smtpPassword": {
"type": "string"
},
"smtpPort": {
"maximum": 65535,
"minimum": 1,
"type": "integer"
},
"smtpTo": {
"type": "string"
},
"smtpUsername": {
"type": "string"
},
"subAnnounce": {
"type": "string"
},
"subCertFile": {
"type": "string"
},
"subClashAutoDetect": {
"type": "boolean"
},
"subClashEnable": {
"type": "boolean"
},
"subClashEnableRouting": {
"type": "boolean"
},
"subClashPath": {
"type": "string"
},
"subClashRules": {
"type": "string"
},
"subClashURI": {
"type": "string"
},
"subClashUserAgentRegex": {
"type": "string"
},
"subDomain": {
"type": "string"
},
"subEnable": {
"type": "boolean"
},
"subEnableRouting": {
"type": "boolean"
},
"subEncrypt": {
"type": "boolean"
},
"subHideSettings": {
"type": "boolean"
},
"subIncyEnableRouting": {
"type": "boolean"
},
"subIncyRoutingRules": {
"type": "string"
},
"subJsonAlwaysArray": {
"type": "boolean"
},
"subJsonAutoDetect": {
"type": "boolean"
},
"subJsonEnable": {
"type": "boolean"
},
"subJsonFinalMask": {
"type": "string"
},
"subJsonMux": {
"type": "string"
},
"subJsonObservatory": {
"type": "string"
},
"subJsonPath": {
"type": "string"
},
"subJsonRules": {
"type": "string"
},
"subJsonURI": {
"type": "string"
},
"subJsonUserAgentRegex": {
"type": "string"
},
"subKeyFile": {
"type": "string"
},
"subListen": {
"type": "string"
},
"subPath": {
"type": "string"
},
"subPort": {
"maximum": 65535,
"minimum": 1,
"type": "integer"
},
"subProfileUrl": {
"type": "string"
},
"subRoutingRules": {
"type": "string"
},
"subShowIdentityOnAllLinks": {
"type": "boolean"
},
"subSupportUrl": {
"type": "string"
},
"subThemeDir": {
"type": "string"
},
"subTitle": {
"type": "string"
},
"subURI": {
"type": "string"
},
"subUpdates": {
"maximum": 525600,
"minimum": 0,
"type": "integer"
},
"tgBotAPIServer": {
"type": "string"
},
"tgBotBackup": {
"type": "boolean"
},
"tgBotChatId": {
"type": "string"
},
"tgBotEnable": {
"type": "boolean"
},
"tgBotProxy": {
"type": "string"
},
"tgBotToken": {
"type": "string"
},
"tgCpu": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"tgEnabledEvents": {
"type": "string"
},
"tgLang": {
"type": "string"
},
"tgMemory": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"tgRunTime": {
"type": "string"
},
"timeLocation": {
"type": "string"
},
"trafficDiff": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"trustedProxyCIDRs": {
"type": "string"
},
"twoFactorEnable": {
"type": "boolean"
},
"twoFactorToken": {
"type": "string"
},
"warpUpdateInterval": {
"minimum": 0,
"type": "integer"
},
"webBasePath": {
"type": "string"
},
"webCertFile": {
"type": "string"
},
"webDomain": {
"type": "string"
},
"webKeyFile": {
"type": "string"
},
"webListen": {
"type": "string"
},
"webPort": {
"maximum": 65535,
"minimum": 1,
"type": "integer"
}
},
"required": [
"datepicker",
"expireDiff",
"externalTrafficInformEnable",
"externalTrafficInformURI",
"ipLimitAllowlist",
"ldapAutoCreate",
"ldapAutoDelete",
"ldapBaseDN",
"ldapBindDN",
"ldapDefaultExpiryDays",
"ldapDefaultLimitIP",
"ldapDefaultTotalGB",
"ldapEnable",
"ldapFlagField",
"ldapHost",
"ldapInboundTags",
"ldapInsecureSkipVerify",
"ldapInvertFlag",
"ldapPassword",
"ldapPort",
"ldapSyncCron",
"ldapTruthyValues",
"ldapUseTLS",
"ldapUserAttr",
"ldapUserFilter",
"ldapVlessField",
"outboundDownThreshold",
"pageSize",
"panelOutbound",
"remarkTemplate",
"restartXrayOnClientDisable",
"sessionMaxAge",
"smtpCpu",
"smtpEnable",
"smtpEnabledEvents",
"smtpEncryptionType",
"smtpFrom",
"smtpFromName",
"smtpHost",
"smtpMemory",
"smtpPassword",
"smtpPort",
"smtpTo",
"smtpUsername",
"subAnnounce",
"subCertFile",
"subClashAutoDetect",
"subClashEnable",
"subClashEnableRouting",
"subClashPath",
"subClashRules",
"subClashURI",
"subClashUserAgentRegex",
"subDomain",
"subEnable",
"subEnableRouting",
"subEncrypt",
"subHideSettings",
"subIncyEnableRouting",
"subIncyRoutingRules",
"subJsonAlwaysArray",
"subJsonAutoDetect",
"subJsonEnable",
"subJsonFinalMask",
"subJsonMux",
"subJsonObservatory",
"subJsonPath",
"subJsonRules",
"subJsonURI",
"subJsonUserAgentRegex",
"subKeyFile",
"subListen",
"subPath",
"subPort",
"subProfileUrl",
"subRoutingRules",
"subShowIdentityOnAllLinks",
"subSupportUrl",
"subThemeDir",
"subTitle",
"subURI",
"subUpdates",
"tgBotAPIServer",
"tgBotBackup",
"tgBotChatId",
"tgBotEnable",
"tgBotProxy",
"tgBotToken",
"tgCpu",
"tgEnabledEvents",
"tgLang",
"tgMemory",
"tgRunTime",
"timeLocation",
"trafficDiff",
"trustedProxyCIDRs",
"twoFactorEnable",
"twoFactorToken",
"warpUpdateInterval",
"webBasePath",
"webCertFile",
"webDomain",
"webKeyFile",
"webListen",
"webPort"
],
"type": "object"
},
"AllSettingView": {
"properties": {
"datepicker": {
"type": "string"
},
"expireDiff": {
"minimum": 0,
"type": "integer"
},
"externalTrafficInformEnable": {
"type": "boolean"
},
"externalTrafficInformURI": {
"type": "string"
},
"hasApiToken": {
"type": "boolean"
},
"hasLdapPassword": {
"type": "boolean"
},
"hasNordSecret": {
"type": "boolean"
},
"hasSmtpPassword": {
"type": "boolean"
},
"hasTgBotToken": {
"type": "boolean"
},
"hasTwoFactorToken": {
"type": "boolean"
},
"hasWarpSecret": {
"type": "boolean"
},
"ipLimitAllowlist": {
"type": "string"
},
"ldapAutoCreate": {
"type": "boolean"
},
"ldapAutoDelete": {
"type": "boolean"
},
"ldapBaseDN": {
"type": "string"
},
"ldapBindDN": {
"type": "string"
},
"ldapDefaultExpiryDays": {
"minimum": 0,
"type": "integer"
},
"ldapDefaultLimitIP": {
"minimum": 0,
"type": "integer"
},
"ldapDefaultTotalGB": {
"minimum": 0,
"type": "integer"
},
"ldapEnable": {
"type": "boolean"
},
"ldapFlagField": {
"type": "string"
},
"ldapHost": {
"type": "string"
},
"ldapInboundTags": {
"type": "string"
},
"ldapInsecureSkipVerify": {
"type": "boolean"
},
"ldapInvertFlag": {
"type": "boolean"
},
"ldapPassword": {
"type": "string"
},
"ldapPort": {
"maximum": 65535,
"minimum": 0,
"type": "integer"
},
"ldapSyncCron": {
"type": "string"
},
"ldapTruthyValues": {
"type": "string"
},
"ldapUseTLS": {
"type": "boolean"
},
"ldapUserAttr": {
"type": "string"
},
"ldapUserFilter": {
"type": "string"
},
"ldapVlessField": {
"type": "string"
},
"outboundDownThreshold": {
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"pageSize": {
"maximum": 1000,
"minimum": 0,
"type": "integer"
},
"panelOutbound": {
"type": "string"
},
"remarkTemplate": {
"type": "string"
},
"restartXrayOnClientDisable": {
"type": "boolean"
},
"sessionMaxAge": {
"maximum": 525600,
"minimum": 1,
"type": "integer"
},
"smtpCpu": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"smtpEnable": {
"type": "boolean"
},
"smtpEnabledEvents": {
"type": "string"
},
"smtpEncryptionType": {
"type": "string"
},
"smtpFrom": {
"type": "string"
},
"smtpFromName": {
"type": "string"
},
"smtpHost": {
"type": "string"
},
"smtpMemory": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"smtpPassword": {
"type": "string"
},
"smtpPort": {
"maximum": 65535,
"minimum": 1,
"type": "integer"
},
"smtpTo": {
"type": "string"
},
"smtpUsername": {
"type": "string"
},
"subAnnounce": {
"type": "string"
},
"subCertFile": {
"type": "string"
},
"subClashAutoDetect": {
"type": "boolean"
},
"subClashEnable": {
"type": "boolean"
},
"subClashEnableRouting": {
"type": "boolean"
},
"subClashPath": {
"type": "string"
},
"subClashRules": {
"type": "string"
},
"subClashURI": {
"type": "string"
},
"subClashUserAgentRegex": {
"type": "string"
},
"subDomain": {
"type": "string"
},
"subEnable": {
"type": "boolean"
},
"subEnableRouting": {
"type": "boolean"
},
"subEncrypt": {
"type": "boolean"
},
"subHideSettings": {
"type": "boolean"
},
"subIncyEnableRouting": {
"type": "boolean"
},
"subIncyRoutingRules": {
"type": "string"
},
"subJsonAlwaysArray": {
"type": "boolean"
},
"subJsonAutoDetect": {
"type": "boolean"
},
"subJsonEnable": {
"type": "boolean"
},
"subJsonFinalMask": {
"type": "string"
},
"subJsonMux": {
"type": "string"
},
"subJsonObservatory": {
"type": "string"
},
"subJsonPath": {
"type": "string"
},
"subJsonRules": {
"type": "string"
},
"subJsonURI": {
"type": "string"
},
"subJsonUserAgentRegex": {
"type": "string"
},
"subKeyFile": {
"type": "string"
},
"subListen": {
"type": "string"
},
"subPath": {
"type": "string"
},
"subPort": {
"maximum": 65535,
"minimum": 1,
"type": "integer"
},
"subProfileUrl": {
"type": "string"
},
"subRoutingRules": {
"type": "string"
},
"subShowIdentityOnAllLinks": {
"type": "boolean"
},
"subSupportUrl": {
"type": "string"
},
"subThemeDir": {
"type": "string"
},
"subTitle": {
"type": "string"
},
"subURI": {
"type": "string"
},
"subUpdates": {
"maximum": 525600,
"minimum": 0,
"type": "integer"
},
"tgBotAPIServer": {
"type": "string"
},
"tgBotBackup": {
"type": "boolean"
},
"tgBotChatId": {
"type": "string"
},
"tgBotEnable": {
"type": "boolean"
},
"tgBotProxy": {
"type": "string"
},
"tgBotToken": {
"type": "string"
},
"tgCpu": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"tgEnabledEvents": {
"type": "string"
},
"tgLang": {
"type": "string"
},
"tgMemory": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"tgRunTime": {
"type": "string"
},
"timeLocation": {
"type": "string"
},
"trafficDiff": {
"maximum": 100,
"minimum": 0,
"type": "integer"
},
"trustedProxyCIDRs": {
"type": "string"
},
"twoFactorEnable": {
"type": "boolean"
},
"twoFactorToken": {
"type": "string"
},
"warpUpdateInterval": {
"minimum": 0,
"type": "integer"
},
"webBasePath": {
"type": "string"
},
"webCertFile": {
"type": "string"
},
"webDomain": {
"type": "string"
},
"webKeyFile": {
"type": "string"
},
"webListen": {
"type": "string"
},
"webPort": {
"maximum": 65535,
"minimum": 1,
"type": "integer"
}
},
"required": [
"datepicker",
"expireDiff",
"externalTrafficInformEnable",
"externalTrafficInformURI",
"hasApiToken",
"hasLdapPassword",
"hasNordSecret",
"hasSmtpPassword",
"hasTgBotToken",
"hasTwoFactorToken",
"hasWarpSecret",
"ipLimitAllowlist",
"ldapAutoCreate",
"ldapAutoDelete",
"ldapBaseDN",
"ldapBindDN",
"ldapDefaultExpiryDays",
"ldapDefaultLimitIP",
"ldapDefaultTotalGB",
"ldapEnable",
"ldapFlagField",
"ldapHost",
"ldapInboundTags",
"ldapInsecureSkipVerify",
"ldapInvertFlag",
"ldapPassword",
"ldapPort",
"ldapSyncCron",
"ldapTruthyValues",
"ldapUseTLS",
"ldapUserAttr",
"ldapUserFilter",
"ldapVlessField",
"outboundDownThreshold",
"pageSize",
"panelOutbound",
"remarkTemplate",
"restartXrayOnClientDisable",
"sessionMaxAge",
"smtpCpu",
"smtpEnable",
"smtpEnabledEvents",
"smtpEncryptionType",
"smtpFrom",
"smtpFromName",
"smtpHost",
"smtpMemory",
"smtpPassword",
"smtpPort",
"smtpTo",
"smtpUsername",
"subAnnounce",
"subCertFile",
"subClashAutoDetect",
"subClashEnable",
"subClashEnableRouting",
"subClashPath",
"subClashRules",
"subClashURI",
"subClashUserAgentRegex",
"subDomain",
"subEnable",
"subEnableRouting",
"subEncrypt",
"subHideSettings",
"subIncyEnableRouting",
"subIncyRoutingRules",
"subJsonAlwaysArray",
"subJsonAutoDetect",
"subJsonEnable",
"subJsonFinalMask",
"subJsonMux",
"subJsonObservatory",
"subJsonPath",
"subJsonRules",
"subJsonURI",
"subJsonUserAgentRegex",
"subKeyFile",
"subListen",
"subPath",
"subPort",
"subProfileUrl",
"subRoutingRules",
"subShowIdentityOnAllLinks",
"subSupportUrl",
"subThemeDir",
"subTitle",
"subURI",
"subUpdates",
"tgBotAPIServer",
"tgBotBackup",
"tgBotChatId",
"tgBotEnable",
"tgBotProxy",
"tgBotToken",
"tgCpu",
"tgEnabledEvents",
"tgLang",
"tgMemory",
"tgRunTime",
"timeLocation",
"trafficDiff",
"trustedProxyCIDRs",
"twoFactorEnable",
"twoFactorToken",
"warpUpdateInterval",
"webBasePath",
"webCertFile",
"webDomain",
"webKeyFile",
"webListen",
"webPort"
],
"type": "object"
},
"AmneziaWGLogs": {
"description": "AmneziaWGLogs is what the overview's AmneziaWG log view renders: the live\nper-peer activity of every running embedded interface, plus the panel's\nown recent AmneziaWG lifecycle log lines that explain a peer being absent\nfrom Peers at all.",
"properties": {
"events": {
"example": [
"2025/01/01 12:00:00 amneziawg: started interface awg1 for inbound 1"
],
"items": {
"type": "string"
},
"type": "array"
},
"peers": {
"items": {
"$ref": "#/components/schemas/PeerActivity"
},
"type": "array"
},
"running": {
"example": true,
"type": "boolean"
}
},
"required": [
"events",
"peers",
"running"
],
"type": "object"
},
"ApiToken": {
"properties": {
"createdAt": {
"format": "int64",
"type": "integer"
},
"enabled": {
"type": "boolean"
},
"expiresAt": {
"format": "int64",
"type": "integer"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"scope": {
"type": "string"
},
"token": {
"description": "SHA-256 hash; the plaintext is shown only once at creation",
"type": "string"
}
},
"required": [
"createdAt",
"enabled",
"expiresAt",
"id",
"name",
"scope",
"token"
],
"type": "object"
},
"ApiTokenView": {
"properties": {
"createdAt": {
"example": 1736000000,
"format": "int64",
"type": "integer"
},
"enabled": {
"example": true,
"type": "boolean"
},
"expiresAt": {
"example": 0,
"format": "int64",
"type": "integer"
},
"id": {
"example": 2,
"type": "integer"
},
"name": {
"example": "central-panel-a",
"type": "string"
},
"scope": {
"example": "admin",
"type": "string"
},
"token": {
"example": "new-token-string",
"type": "string"
}
},
"required": [
"createdAt",
"enabled",
"expiresAt",
"id",
"name",
"scope"
],
"type": "object"
},
"Client": {
"description": "Client represents a client configuration for Xray inbounds with traffic limits and settings.",
"properties": {
"adTag": {
"example": "0123456789abcdef0123456789abcdef",
"type": "string"
},
"allowedIPs": {
"items": {
"type": "string"
},
"type": "array"
},
"allowedIPsByInbound": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "AllowedIPsByInbound optionally overrides AllowedIPs on a per-inbound\nbasis, keyed by inbound id. Lets one identity attached to both\nWireGuard and AmneziaWG carry two genuinely different addresses in a\nsingle Create/Update call instead of the shared AllowedIPs field\nbeing broadcast to every attached tunnel inbound. Absent/unset for a\ngiven inbound id falls back to the shared AllowedIPs exactly as\nbefore -- fully backward compatible for callers that never set this.",
"type": "object"
},
"auth": {
"description": "Auth password (Hysteria)",
"type": "string"
},
"comment": {
"description": "Client comment",
"type": "string"
},
"created_at": {
"description": "Creation timestamp",
"format": "int64",
"type": "integer"
},
"email": {
"description": "Client email identifier",
"type": "string"
},
"enable": {
"description": "Whether the client is enabled",
"type": "boolean"
},
"expiryTime": {
"description": "Expiration timestamp",
"format": "int64",
"type": "integer"
},
"flow": {
"description": "Flow control (XTLS)",
"type": "string"
},
"forwardedPorts": {
"description": "AmneziaWG per-client port-forwarding spec, e.g. \"80,443,8000-8100\"",
"type": "string"
},
"group": {
"description": "Logical grouping label",
"type": "string"
},
"id": {
"description": "Unique client identifier",
"type": "string"
},
"keepAlive": {
"type": "integer"
},
"limitIp": {
"description": "IP limit for this client",
"type": "integer"
},
"password": {
"description": "Client password",
"type": "string"
},
"preSharedKey": {
"type": "string"
},
"privateKey": {
"type": "string"
},
"publicKey": {
"type": "string"
},
"reset": {
"description": "Reset period in days",
"type": "integer"
},
"resetDay": {
"description": "Calendar renewal day 1-31, 0 = interval mode",
"type": "integer"
},
"resetMax": {
"description": "Max auto-renew count, 0 = unlimited",
"type": "integer"
},
"reverse": {
"allOf": [
{
"$ref": "#/components/schemas/ClientReverse"
}
],
"description": "VLESS simple reverse proxy settings",
"nullable": true
},
"secret": {
"example": "ee1234567890abcdef1234567890abcd7777772e636c6f7564666c6172652e636f6d",
"type": "string"
},
"security": {
"description": "Security method (e.g., \"auto\", \"aes-128-gcm\")",
"type": "string"
},
"subId": {
"description": "Subscription identifier",
"type": "string"
},
"tgId": {
"description": "Telegram user ID for notifications",
"format": "int64",
"type": "integer"
},
"totalGB": {
"description": "Total traffic limit in GB",
"format": "int64",
"type": "integer"
},
"trafficReset": {
"description": "Per-client traffic reset cycle, independent of the inbound's own (#5497).",
"enum": [
"never",
"hourly",
"daily",
"weekly",
"monthly"
],
"type": "string"
},
"trafficResetDay": {
"maximum": 31,
"minimum": 1,
"type": "integer"
},
"updated_at": {
"description": "Last update timestamp",
"format": "int64",
"type": "integer"
}
},
"required": [
"comment",
"email",
"enable",
"expiryTime",
"limitIp",
"reset",
"resetDay",
"resetMax",
"security",
"subId",
"tgId",
"totalGB"
],
"type": "object"
},
"ClientInbound": {
"properties": {
"clientId": {
"type": "integer"
},
"createdAt": {
"format": "int64",
"type": "integer"
},
"flowOverride": {
"type": "string"
},
"inboundId": {
"type": "integer"
}
},
"required": [
"clientId",
"createdAt",
"flowOverride",
"inboundId"
],
"type": "object"
},
"ClientRecord": {
"properties": {
"adTag": {
"type": "string"
},
"allowedIPs": {
"type": "string"
},
"auth": {
"type": "string"
},
"comment": {
"type": "string"
},
"createdAt": {
"format": "int64",
"type": "integer"
},
"email": {
"type": "string"
},
"enable": {
"type": "boolean"
},
"expiryTime": {
"format": "int64",
"type": "integer"
},
"flow": {
"type": "string"
},
"forwardedPorts": {
"type": "string"
},
"group": {
"type": "string"
},
"id": {
"type": "integer"
},
"keepAlive": {
"type": "integer"
},
"limitHwid": {
"type": "integer"
},
"limitIp": {
"type": "integer"
},
"password": {
"type": "string"
},
"preSharedKey": {
"type": "string"
},
"privateKey": {
"type": "string"
},
"publicKey": {
"type": "string"
},
"reset": {
"type": "integer"
},
"resetDay": {
"type": "integer"
},
"resetMax": {
"type": "integer"
},
"reverse": {},
"secret": {
"type": "string"
},
"security": {
"type": "string"
},
"subId": {
"type": "string"
},
"tgId": {
"format": "int64",
"type": "integer"
},
"totalGB": {
"format": "int64",
"type": "integer"
},
"trafficReset": {
"type": "string"
},
"trafficResetDay": {
"type": "integer"
},
"updatedAt": {
"format": "int64",
"type": "integer"
},
"uuid": {
"type": "string"
}
},
"required": [
"adTag",
"allowedIPs",
"auth",
"comment",
"createdAt",
"email",
"enable",
"expiryTime",
"flow",
"forwardedPorts",
"group",
"id",
"keepAlive",
"limitHwid",
"limitIp",
"password",
"preSharedKey",
"privateKey",
"publicKey",
"reset",
"resetDay",
"resetMax",
"reverse",
"secret",
"security",
"subId",
"tgId",
"totalGB",
"trafficReset",
"trafficResetDay",
"updatedAt",
"uuid"
],
"type": "object"
},
"ClientReverse": {
"properties": {
"tag": {
"type": "string"
}
},
"required": [
"tag"
],
"type": "object"
},
"ClientTraffic": {
"description": "ClientTraffic represents traffic statistics and limits for a specific client.\nIt tracks upload/download usage, expiry times, and online status for inbound clients.",
"properties": {
"down": {
"example": 2097152,
"format": "int64",
"type": "integer"
},
"email": {
"example": "user1",
"type": "string"
},
"enable": {
"example": true,
"type": "boolean"
},
"expiryTime": {
"example": 1735689600000,
"format": "int64",
"type": "integer"
},
"id": {
"example": 14825,
"type": "integer"
},
"inboundId": {
"example": 1,
"type": "integer"
},
"lastOnline": {
"example": 1735680000000,
"format": "int64",
"type": "integer"
},
"lastSubFetch": {
"example": 1735680000000,
"format": "int64",
"type": "integer"
},
"reset": {
"example": 0,
"type": "integer"
},
"resetCount": {
"description": "ResetCount is how many have fired, so a prepaid plan stops on its own.",
"example": 0,
"type": "integer"
},
"resetDay": {
"description": "ResetDay renews on that day of each calendar month instead of every\nReset days; 0 keeps the interval behaviour.",
"example": 0,
"type": "integer"
},
"resetMax": {
"description": "ResetMax caps how many times auto-renew may fire; 0 means no cap.",
"example": 0,
"type": "integer"
},
"subId": {
"example": "i7tvdpeffi0hvvf1",
"type": "string"
},
"total": {
"example": 10737418240,
"format": "int64",
"type": "integer"
},
"up": {
"example": 1048576,
"format": "int64",
"type": "integer"
},
"uuid": {
"example": "e18c9a96-71bf-48d4-933f-8b9a46d4290c",
"type": "string"
}
},
"required": [
"down",
"email",
"enable",
"expiryTime",
"id",
"inboundId",
"lastOnline",
"lastSubFetch",
"reset",
"resetCount",
"resetDay",
"resetMax",
"subId",
"total",
"up",
"uuid"
],
"type": "object"
},
"FallbackParentInfo": {
"description": "FallbackParentInfo carries everything the frontend needs to rewrite a\nchild inbound's client link: where to connect (the master's address\nand port) and which path matched on the master's fallbacks array.\nThe frontend already has the master inbound in its dbInbounds list,\nso we only ship identifiers + the match path here.",
"properties": {
"masterId": {
"type": "integer"
},
"path": {
"type": "string"
}
},
"required": [
"masterId"
],
"type": "object"
},
"GeoCategory": {
"description": "GeoCategory is one code inside a database, such as geosite's \"google\".",
"properties": {
"attributes": {
"example": [
"ads",
"cn"
],
"items": {
"type": "string"
},
"type": "array"
},
"code": {
"example": "google",
"type": "string"
},
"entries": {
"example": 1284,
"type": "integer"
}
},
"required": [
"attributes",
"code",
"entries"
],
"type": "object"
},
"GeoCategoryPage": {
"description": "GeoCategoryPage is one page of categories plus the unpaged total.",
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/GeoCategory"
},
"type": "array"
},
"total": {
"example": 1043,
"type": "integer"
}
},
"required": [
"items",
"total"
],
"type": "object"
},
"GeoEntry": {
"description": "GeoEntry is a single rule inside a category: a domain rule for geosite\ndatabases, a CIDR for geoip ones.",
"properties": {
"kind": {
"example": "domain",
"type": "string"
},
"value": {
"example": "google.com",
"type": "string"
}
},
"required": [
"kind",
"value"
],
"type": "object"
},
"GeoEntryPage": {
"description": "GeoEntryPage is one page of category entries plus the unpaged total.",
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/GeoEntry"
},
"type": "array"
},
"total": {
"example": 1284,
"type": "integer"
}
},
"required": [
"items",
"total"
],
"type": "object"
},
"GeoFile": {
"description": "GeoFile describes one .dat database found in the asset directory.",
"properties": {
"categories": {
"example": 1043,
"type": "integer"
},
"error": {
"type": "string"
},
"kind": {
"example": "site",
"type": "string"
},
"modifiedAt": {
"example": 1769558400000,
"format": "int64",
"type": "integer"
},
"name": {
"example": "geosite.dat",
"type": "string"
},
"size": {
"example": 1467392,
"format": "int64",
"type": "integer"
}
},
"required": [
"categories",
"kind",
"modifiedAt",
"name",
"size"
],
"type": "object"
},
"GeodataTokenIssue": {
"description": "GeodataTokenIssue reports a routing token the running core would reject,\nor would silently match nothing against.",
"properties": {
"code": {
"example": "blabla",
"type": "string"
},
"file": {
"example": "geosite.dat",
"type": "string"
},
"reason": {
"example": "categoryMissing",
"type": "string"
},
"token": {
"example": "geosite:blabla",
"type": "string"
}
},
"required": [
"reason",
"token"
],
"type": "object"
},
"HistoryOfSeeders": {
"description": "HistoryOfSeeders tracks which database seeders have been executed to prevent re-running.",
"properties": {
"id": {
"type": "integer"
},
"seederName": {
"type": "string"
}
},
"required": [
"id",
"seederName"
],
"type": "object"
},
"Host": {
"properties": {
"address": {
"example": "cdn.example.com",
"type": "string"
},
"allowInsecure": {
"type": "boolean"
},
"alpn": {
"items": {
"type": "string"
},
"type": "array"
},
"createdAt": {
"format": "int64",
"type": "integer"
},
"echConfigList": {
"type": "string"
},
"excludeFromSubTypes": {
"items": {
"type": "string"
},
"type": "array"
},
"finalMask": {
"description": "FinalMask is a JSON object of xray finalmask masks (tcp/udp/quicParams),\nmerged into this host's JSON-subscription stream. Empty = no override.",
"type": "string"
},
"fingerprint": {
"type": "string"
},
"groupId": {
"type": "string"
},
"hostHeader": {
"type": "string"
},
"id": {
"example": 1,
"type": "integer"
},
"inboundId": {
"example": 1,
"type": "integer"
},
"isDisabled": {
"type": "boolean"
},
"isHidden": {
"type": "boolean"
},
"keepSniBlank": {
"type": "boolean"
},
"mihomoIpVersion": {
"enum": [
"dual",
"ipv4",
"ipv6",
"ipv4-prefer",
"ipv6-prefer"
],
"type": "string"
},
"mihomoX25519": {
"type": "boolean"
},
"muxParams": {},
"nodeGuids": {
"items": {
"type": "string"
},
"type": "array"
},
"overrideSniFromAddress": {
"type": "boolean"
},
"path": {
"type": "string"
},
"pinnedPeerCertSha256": {
"items": {
"type": "string"
},
"type": "array"
},
"port": {
"example": 8443,
"maximum": 65535,
"minimum": 0,
"type": "integer"
},
"remark": {
"example": "cdn-front",
"maxLength": 256,
"type": "string"
},
"security": {
"enum": [
"same",
"tls",
"none",
"reality"
],
"example": "same",
"type": "string"
},
"serverDescription": {
"maxLength": 64,
"type": "string"
},
"shuffleHost": {
"type": "boolean"
},
"sni": {
"type": "string"
},
"sockoptParams": {},
"sortOrder": {
"type": "integer"
},
"tags": {
"items": {
"type": "string"
},
"type": "array"
},
"updatedAt": {
"format": "int64",
"type": "integer"
},
"verifyPeerCertByName": {
"type": "string"
},
"vlessRoute": {
"description": "Single VLESS route value (0-65535) baked into the subscription UUID's 3rd\ngroup (bytes 6-7), which xray reads via net.PortFromBytes(id[6:8]). Empty = none.",
"example": "443",
"type": "string"
}
},
"required": [
"address",
"allowInsecure",
"alpn",
"createdAt",
"echConfigList",
"excludeFromSubTypes",
"finalMask",
"fingerprint",
"groupId",
"hostHeader",
"id",
"inboundId",
"isDisabled",
"isHidden",
"keepSniBlank",
"mihomoIpVersion",
"mihomoX25519",
"muxParams",
"overrideSniFromAddress",
"path",
"pinnedPeerCertSha256",
"port",
"remark",
"security",
"serverDescription",
"shuffleHost",
"sni",
"sockoptParams",
"sortOrder",
"tags",
"updatedAt",
"verifyPeerCertByName",
"vlessRoute"
],
"type": "object"
},
"HostGroup": {
"properties": {
"allowInsecure": {
"type": "boolean"
},
"alpn": {
"items": {
"type": "string"
},
"type": "array"
},
"echConfigList": {
"type": "string"
},
"excludeFromSubTypes": {
"items": {
"type": "string"
},
"type": "array"
},
"finalMask": {
"type": "string"
},
"fingerprint": {
"type": "string"
},
"groupId": {
"type": "string"
},
"hostHeader": {
"type": "string"
},
"hosts": {
"items": {
"type": "string"
},
"type": "array"
},
"inboundIds": {
"items": {
"type": "integer"
},
"type": "array"
},
"isDisabled": {
"type": "boolean"
},
"isHidden": {
"type": "boolean"
},
"keepSniBlank": {
"type": "boolean"
},
"mihomoIpVersion": {
"enum": [
"dual",
"ipv4",
"ipv6",
"ipv4-prefer",
"ipv6-prefer"
],
"type": "string"
},
"mihomoX25519": {
"type": "boolean"
},
"muxParams": {
"type": "string"
},
"nodeGuids": {
"items": {
"type": "string"
},
"type": "array"
},
"overrideSniFromAddress": {
"type": "boolean"
},
"path": {
"type": "string"
},
"pinnedPeerCertSha256": {
"items": {
"type": "string"
},
"type": "array"
},
"port": {
"maximum": 65535,
"minimum": 0,
"type": "integer"
},
"remark": {
"maxLength": 256,
"type": "string"
},
"security": {
"enum": [
"same",
"tls",
"none",
"reality"
],
"type": "string"
},
"serverDescription": {
"maxLength": 64,
"type": "string"
},
"shuffleHost": {
"type": "boolean"
},
"sni": {
"type": "string"
},
"sockoptParams": {
"type": "string"
},
"sortOrder": {
"type": "integer"
},
"tags": {
"items": {
"type": "string"
},
"type": "array"
},
"verifyPeerCertByName": {
"type": "string"
},
"vlessRoute": {
"type": "string"
}
},
"required": [
"allowInsecure",
"alpn",
"echConfigList",
"excludeFromSubTypes",
"finalMask",
"fingerprint",
"groupId",
"hostHeader",
"hosts",
"inboundIds",
"isDisabled",
"isHidden",
"keepSniBlank",
"mihomoIpVersion",
"mihomoX25519",
"muxParams",
"nodeGuids",
"overrideSniFromAddress",
"path",
"pinnedPeerCertSha256",
"port",
"remark",
"security",
"serverDescription",
"shuffleHost",
"sni",
"sockoptParams",
"sortOrder",
"tags",
"verifyPeerCertByName",
"vlessRoute"
],
"type": "object"
},
"Inbound": {
"description": "Inbound represents an Xray inbound configuration with traffic statistics and settings.",
"properties": {
"clientStats": {
"description": "Client traffic statistics",
"items": {
"$ref": "#/components/schemas/ClientTraffic"
},
"type": "array"
},
"disableFlow": {
"example": false,
"type": "boolean"
},
"down": {
"description": "Download traffic in bytes",
"format": "int64",
"type": "integer"
},
"enable": {
"description": "Whether the inbound is enabled",
"example": true,
"type": "boolean"
},
"expiryTime": {
"description": "Expiration timestamp",
"format": "int64",
"type": "integer"
},
"fallbackParent": {
"allOf": [
{
"$ref": "#/components/schemas/FallbackParentInfo"
}
],
"description": "FallbackParent is populated by the API layer when this inbound is\nattached as a fallback child of a VLESS/Trojan TCP-TLS master.\nThe frontend uses it to rewrite client-share links so they advertise\nthe master's externally reachable endpoint instead of the child's\nloopback listen. Not persisted.",
"nullable": true
},
"id": {
"description": "Unique identifier",
"example": 1,
"type": "integer"
},
"lastTrafficResetTime": {
"description": "Last traffic reset timestamp",
"format": "int64",
"type": "integer"
},
"listen": {
"description": "Xray configuration fields",
"type": "string"
},
"nodeId": {
"nullable": true,
"type": "integer"
},
"originNodeGuid": {
"description": "OriginNodeGuid is the panelGuid of the node that physically hosts this\ninbound, propagated up across hops (#4983). Empty for an inbound that\nlives on this panel's own xray; set to the originating node's GUID when\nthe inbound was synced from a node (kept as-is across further hops). Lets\nthe master attribute a deeply nested inbound to the real node instead of\nthe intermediate one it was fetched through.",
"type": "string"
},
"port": {
"example": 443,
"maximum": 65535,
"minimum": 0,
"type": "integer"
},
"protocol": {
"enum": [
"vmess",
"vless",
"trojan",
"shadowsocks",
"wireguard",
"hysteria",
"http",
"mixed",
"tunnel",
"tun",
"mtproto",
"amneziawg"
],
"example": "vless",
"type": "string"
},
"remark": {
"description": "Human-readable remark",
"example": "VLESS-443",
"type": "string"
},
"settings": {},
"shareAddr": {
"type": "string"
},
"shareAddrStrategy": {
"enum": [
"node",
"listen",
"custom"
],
"type": "string"
},
"sniffing": {},
"streamSettings": {},
"subSortIndex": {
"description": "1-based sort order of this inbound's links in subscription output only (lower first; ties by id)",
"example": 1,
"minimum": 1,
"type": "integer"
},
"tag": {
"example": "in-443-tcp",
"type": "string"
},
"total": {
"description": "Total traffic limit in bytes",
"format": "int64",
"type": "integer"
},
"trafficReset": {
"description": "Traffic reset schedule",
"enum": [
"never",
"hourly",
"daily",
"weekly",
"monthly"
],
"type": "string"
},
"trafficResetDay": {
"description": "Day of month for monthly traffic resets",
"example": 1,
"maximum": 31,
"minimum": 1,
"type": "integer"
},
"up": {
"description": "Upload traffic in bytes",
"format": "int64",
"type": "integer"
}
},
"required": [
"clientStats",
"disableFlow",
"down",
"enable",
"expiryTime",
"id",
"lastTrafficResetTime",
"listen",
"port",
"protocol",
"remark",
"settings",
"shareAddr",
"shareAddrStrategy",
"sniffing",
"streamSettings",
"subSortIndex",
"tag",
"total",
"trafficReset",
"trafficResetDay",
"up"
],
"type": "object"
},
"InboundClientIps": {
"description": "InboundClientIps stores IP addresses associated with inbound clients for access control.",
"properties": {
"clientEmail": {
"type": "string"
},
"id": {
"type": "integer"
},
"ips": {}
},
"required": [
"clientEmail",
"id",
"ips"
],
"type": "object"
},
"InboundFallback": {
"properties": {
"alpn": {
"type": "string"
},
"childId": {
"type": "integer"
},
"dest": {
"type": "string"
},
"id": {
"type": "integer"
},
"masterId": {
"type": "integer"
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"sortOrder": {
"type": "integer"
},
"xver": {
"type": "integer"
}
},
"required": [
"alpn",
"childId",
"dest",
"id",
"masterId",
"name",
"path",
"sortOrder",
"xver"
],
"type": "object"
},
"InboundOption": {
"properties": {
"awgServer": {
"allOf": [
{
"$ref": "#/components/schemas/ServerSettings"
}
],
"description": "AwgServer carries the full AmneziaWG server block (keys, subnet,\nobfuscation params) so the clients page can render a downloadable\nper-client .conf without a second round trip.",
"nullable": true
},
"enable": {
"example": true,
"type": "boolean"
},
"id": {
"example": 1,
"type": "integer"
},
"listen": {
"type": "string"
},
"mtprotoDomain": {
"type": "string"
},
"nodeAddress": {
"description": "Share-host resolution inputs, mirroring the subscription's\nresolveInboundAddress so the clients page renders a node-managed WireGuard\nEndpoint that points at the node, not the master panel. NodeAddress is the\nhosting node's externally reachable address (empty for this panel's own\ninbounds); Listen and ShareAddrStrategy/ShareAddr feed the same\nnode→listen→custom fallback the share/QR links already use.",
"type": "string"
},
"nodeId": {
"description": "Hosting node; nil for this panel's own inbounds. Lets the clients\npage map a node filter onto inbound IDs (#4997).",
"nullable": true,
"type": "integer"
},
"port": {
"example": 443,
"type": "integer"
},
"protocol": {
"example": "vless",
"type": "string"
},
"remark": {
"example": "VLESS-443",
"type": "string"
},
"shareAddr": {
"type": "string"
},
"shareAddrStrategy": {
"type": "string"
},
"ssMethod": {
"type": "string"
},
"tag": {
"example": "in-443-tcp",
"type": "string"
},
"tlsFlowCapable": {
"example": true,
"type": "boolean"
},
"wgDns": {
"type": "string"
},
"wgMtu": {
"type": "integer"
},
"wgPublicKey": {
"type": "string"
}
},
"required": [
"enable",
"id",
"port",
"protocol",
"remark",
"ssMethod",
"tag",
"tlsFlowCapable"
],
"type": "object"
},
"Msg": {
"properties": {
"msg": {
"type": "string"
},
"obj": {},
"success": {
"type": "boolean"
}
},
"required": [
"msg",
"obj",
"success"
],
"type": "object"
},
"Node": {
"description": "Node represents a remote 3x-ui panel registered with the central panel.\nThe central panel polls each node's existing /panel/api/server/status\nendpoint over HTTP using the per-node ApiToken to populate the runtime\nstatus fields below.",
"properties": {
"activeCount": {
"example": 23,
"type": "integer"
},
"address": {
"example": "node1.example.com",
"type": "string"
},
"allowPrivateAddress": {
"type": "boolean"
},
"basePath": {
"example": "/",
"type": "string"
},
"clientCount": {
"example": 27,
"type": "integer"
},
"configDirty": {
"type": "boolean"
},
"configDirtyAt": {
"format": "int64",
"type": "integer"
},
"cpuPct": {
"example": 23.5,
"type": "number"
},
"createdAt": {
"example": 1700000000,
"format": "int64",
"type": "integer"
},
"depletedCount": {
"example": 1,
"type": "integer"
},
"disabledCount": {
"example": 3,
"type": "integer"
},
"enable": {
"example": true,
"type": "boolean"
},
"guid": {
"description": "Guid is the remote panel's stable self-identifier (its panelGuid),\nlearned from each heartbeat. It is the globally stable node identity used\nto attribute online clients/inbounds to the physical node across a chain\nof nodes (#4983); panel-local autoincrement ids don't survive a hop.\nObserved-state only — never user-edited.",
"type": "string"
},
"id": {
"example": 1,
"type": "integer"
},
"inboundCount": {
"example": 5,
"type": "integer"
},
"inboundSyncMode": {
"enum": [
"all",
"selected"
],
"type": "string"
},
"inboundTags": {
"items": {
"type": "string"
},
"type": "array"
},
"lastError": {
"type": "string"
},
"lastHeartbeat": {
"description": "unix seconds, 0 = never",
"example": 1700000000,
"format": "int64",
"type": "integer"
},
"latencyMs": {
"example": 42,
"type": "integer"
},
"memPct": {
"example": 45.1,
"type": "number"
},
"name": {
"example": "de-fra-1",
"type": "string"
},
"netDown": {
"example": 2097152,
"format": "int64",
"type": "integer"
},
"netUp": {
"example": 1048576,
"format": "int64",
"type": "integer"
},
"onlineCount": {
"example": 3,
"type": "integer"
},
"outboundTag": {
"type": "string"
},
"panelVersion": {
"example": "v3.x.x",
"type": "string"
},
"parentGuid": {
"description": "ParentGuid + Transitive are set only when a node is surfaced as part of a\nnode tree (#4983): direct nodes carry the master panel's own GUID, a\ntransitive sub-node carries its parent node's GUID. Transitive nodes are\nread-only projections (Id == 0, not persisted) — never edited or deployed.",
"type": "string"
},
"pinnedCertSha256": {
"type": "string"
},
"port": {
"example": 2053,
"maximum": 65535,
"minimum": 1,
"type": "integer"
},
"remark": {
"type": "string"
},
"scheme": {
"enum": [
"http",
"https"
],
"example": "https",
"type": "string"
},
"status": {
"description": "Heartbeat-updated fields. UpdatedAt advances on every probe even when\nthe row is otherwise unchanged so the UI's \"last seen\" tooltip is\ntruthful without us having to read LastHeartbeat separately.\nonline|offline|unknown",
"example": "online",
"type": "string"
},
"tlsVerifyMode": {
"enum": [
"verify",
"skip",
"pin",
"mtls"
],
"type": "string"
},
"transitive": {
"type": "boolean"
},
"updatedAt": {
"example": 1700000000,
"format": "int64",
"type": "integer"
},
"uptimeSecs": {
"example": 86400,
"format": "int64",
"type": "integer"
},
"xrayError": {
"type": "string"
},
"xrayState": {
"description": "XrayState and XrayError are captured from the remote node's /panel/api/server/status\nduring heartbeats. They let the central panel distinguish \"panel API reachable\"\n(status=online) from \"Xray core itself has failed on the node\" for monitoring.",
"type": "string"
},
"xrayVersion": {
"example": "25.10.31",
"type": "string"
}
},
"required": [
"activeCount",
"address",
"allowPrivateAddress",
"basePath",
"clientCount",
"configDirty",
"configDirtyAt",
"cpuPct",
"createdAt",
"depletedCount",
"disabledCount",
"enable",
"guid",
"id",
"inboundCount",
"inboundSyncMode",
"inboundTags",
"lastError",
"lastHeartbeat",
"latencyMs",
"memPct",
"name",
"netDown",
"netUp",
"onlineCount",
"outboundTag",
"panelVersion",
"pinnedCertSha256",
"port",
"remark",
"scheme",
"status",
"tlsVerifyMode",
"updatedAt",
"uptimeSecs",
"xrayError",
"xrayState",
"xrayVersion"
],
"type": "object"
},
"NodeMutationRequest": {
"description": "NodeMutationRequest is the node write/probe contract. ApiToken is accepted\nonly as input. On update, nil means keep the stored token; replacement and\nclearing are explicit and mutually exclusive.",
"properties": {
"address": {
"type": "string"
},
"allowPrivateAddress": {
"type": "boolean"
},
"apiToken": {
"nullable": true,
"type": "string"
},
"basePath": {
"type": "string"
},
"clearApiToken": {
"type": "boolean"
},
"enable": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"inboundSyncMode": {
"enum": [
"all",
"selected"
],
"type": "string"
},
"inboundTags": {
"items": {
"type": "string"
},
"type": "array"
},
"name": {
"type": "string"
},
"outboundTag": {
"type": "string"
},
"pinnedCertSha256": {
"type": "string"
},
"port": {
"maximum": 65535,
"minimum": 1,
"type": "integer"
},
"remark": {
"type": "string"
},
"scheme": {
"enum": [
"http",
"https"
],
"type": "string"
},
"tlsVerifyMode": {
"enum": [
"verify",
"skip",
"pin",
"mtls"
],
"type": "string"
}
},
"required": [
"address",
"allowPrivateAddress",
"basePath",
"enable",
"id",
"inboundSyncMode",
"inboundTags",
"name",
"outboundTag",
"pinnedCertSha256",
"port",
"remark",
"scheme",
"tlsVerifyMode"
],
"type": "object"
},
"NodeView": {
"description": "NodeView is the browser/API read contract for nodes. Credentials are\nwrite-only: responses expose only whether a node has a token configured.",
"properties": {
"activeCount": {
"example": 20,
"type": "integer"
},
"address": {
"example": "node.example.com",
"type": "string"
},
"allowPrivateAddress": {
"example": false,
"type": "boolean"
},
"basePath": {
"example": "/",
"type": "string"
},
"clientCount": {
"example": 25,
"type": "integer"
},
"configDirty": {
"example": false,
"type": "boolean"
},
"configDirtyAt": {
"example": 0,
"format": "int64",
"type": "integer"
},
"cpuPct": {
"example": 12.5,
"type": "number"
},
"createdAt": {
"example": 1700000000,
"format": "int64",
"type": "integer"
},
"depletedCount": {
"example": 1,
"type": "integer"
},
"disabledCount": {
"example": 2,
"type": "integer"
},
"enable": {
"example": true,
"type": "boolean"
},
"guid": {
"example": "node-guid",
"type": "string"
},
"hasApiToken": {
"example": true,
"type": "boolean"
},
"id": {
"example": 1,
"type": "integer"
},
"inboundCount": {
"example": 3,
"type": "integer"
},
"inboundSyncMode": {
"example": "all",
"type": "string"
},
"inboundTags": {
"example": [
"in-443-tcp"
],
"items": {
"type": "string"
},
"type": "array"
},
"lastError": {
"type": "string"
},
"lastHeartbeat": {
"example": 1700000000,
"format": "int64",
"type": "integer"
},
"latencyMs": {
"example": 42,
"type": "integer"
},
"memPct": {
"example": 45.2,
"type": "number"
},
"name": {
"example": "edge-1",
"type": "string"
},
"netDown": {
"example": 1048576,
"format": "int64",
"type": "integer"
},
"netUp": {
"example": 2097152,
"format": "int64",
"type": "integer"
},
"onlineCount": {
"example": 5,
"type": "integer"
},
"outboundTag": {
"example": "direct",
"type": "string"
},
"panelVersion": {
"example": "v3.x.x",
"type": "string"
},
"parentGuid": {
"type": "string"
},
"pinnedCertSha256": {
"type": "string"
},
"port": {
"example": 2053,
"type": "integer"
},
"remark": {
"example": "Primary edge",
"type": "string"
},
"scheme": {
"example": "https",
"type": "string"
},
"status": {
"example": "online",
"type": "string"
},
"tlsVerifyMode": {
"example": "verify",
"type": "string"
},
"transitive": {
"example": false,
"type": "boolean"
},
"updatedAt": {
"example": 1700003600,
"format": "int64",
"type": "integer"
},
"uptimeSecs": {
"example": 86400,
"format": "int64",
"type": "integer"
},
"xrayError": {
"type": "string"
},
"xrayState": {
"example": "running",
"type": "string"
},
"xrayVersion": {
"example": "25.10.31",
"type": "string"
}
},
"required": [
"activeCount",
"address",
"allowPrivateAddress",
"basePath",
"clientCount",
"configDirty",
"configDirtyAt",
"cpuPct",
"createdAt",
"depletedCount",
"disabledCount",
"enable",
"guid",
"hasApiToken",
"id",
"inboundCount",
"inboundSyncMode",
"inboundTags",
"lastError",
"lastHeartbeat",
"latencyMs",
"memPct",
"name",
"netDown",
"netUp",
"onlineCount",
"outboundTag",
"panelVersion",
"pinnedCertSha256",
"port",
"remark",
"scheme",
"status",
"tlsVerifyMode",
"updatedAt",
"uptimeSecs",
"xrayError",
"xrayState",
"xrayVersion"
],
"type": "object"
},
"OutboundTraffics": {
"description": "OutboundTraffics tracks traffic statistics for Xray outbound connections.",
"properties": {
"down": {
"format": "int64",
"type": "integer"
},
"id": {
"type": "integer"
},
"tag": {
"type": "string"
},
"total": {
"format": "int64",
"type": "integer"
},
"up": {
"format": "int64",
"type": "integer"
}
},
"required": [
"down",
"id",
"tag",
"total",
"up"
],
"type": "object"
},
"PanelUpdateStatus": {
"description": "PanelUpdateStatus reports the outcome of the most recently launched panel\nself-update. RunID lets the caller confirm this status belongs to the\nupdate it started rather than a stale result left over from an earlier\nrun; State is one of \"pending\", \"success\", or \"failed\". RunID is a decimal\nstring, not a JSON number: it's a formatted UnixNano timestamp, and\nJavaScript's number type can't represent that precisely (it exceeds\nNumber.MAX_SAFE_INTEGER), which would let two different runs round to the\nsame value on the wire and defeat the whole point of this field.",
"properties": {
"exitCode": {
"example": 0,
"type": "integer"
},
"finishedAt": {
"example": 1735689612,
"format": "int64",
"type": "integer"
},
"runId": {
"example": "1735689600123456789",
"type": "string"
},
"state": {
"example": "success",
"type": "string"
}
},
"required": [
"exitCode",
"finishedAt",
"runId",
"state"
],
"type": "object"
},
"PeerActivity": {
"description": "PeerActivity is one peer's live embedded-Device-reported state, the\ncounterpart of an Xray access-log entry: a tunnel logs no requests, only\nhandshakes and bytes.",
"properties": {
"allowedIPs": {
"example": "10.8.1.2/32",
"type": "string"
},
"down": {
"example": 4194304,
"format": "int64",
"type": "integer"
},
"email": {
"example": "peer@example.com",
"type": "string"
},
"endpoint": {
"example": "203.0.113.9:51820",
"type": "string"
},
"handshake": {
"description": "Handshake is unix milliseconds, 0 when the peer has never connected.",
"example": 1735732800000,
"format": "int64",
"type": "integer"
},
"inboundId": {
"example": 1,
"type": "integer"
},
"interface": {
"example": "awg1",
"type": "string"
},
"online": {
"example": true,
"type": "boolean"
},
"tag": {
"example": "inbound-51820",
"type": "string"
},
"up": {
"example": 1048576,
"format": "int64",
"type": "integer"
}
},
"required": [
"allowedIPs",
"down",
"email",
"endpoint",
"handshake",
"inboundId",
"interface",
"online",
"tag",
"up"
],
"type": "object"
},
"ProbeResultUI": {
"properties": {
"cpuPct": {
"example": 12.5,
"type": "number"
},
"error": {
"type": "string"
},
"latencyMs": {
"example": 42,
"type": "integer"
},
"memPct": {
"example": 45.2,
"type": "number"
},
"panelVersion": {
"example": "v3.x.x",
"type": "string"
},
"status": {
"example": "online",
"type": "string"
},
"uptimeSecs": {
"example": 86400,
"format": "int64",
"type": "integer"
},
"xrayError": {
"type": "string"
},
"xrayState": {
"description": "XrayState/XrayError are populated on successful probes even when the node's\nXray core is not healthy. The UI uses them for a distinct \"panel ok, xray failed\" indicator.",
"type": "string"
},
"xrayVersion": {
"example": "25.10.31",
"type": "string"
}
},
"required": [
"cpuPct",
"error",
"latencyMs",
"memPct",
"panelVersion",
"status",
"uptimeSecs",
"xrayError",
"xrayState",
"xrayVersion"
],
"type": "object"
},
"RealityScanResult": {
"properties": {
"alpn": {
"example": "h2",
"type": "string"
},
"certChainValid": {
"description": "CertChainValid ignores the name: a trusted chain presented for other names\nstill has serverNames the panel can offer instead of the failing SNI.",
"example": true,
"type": "boolean"
},
"certIssuer": {
"example": "Google Trust Services",
"type": "string"
},
"certSubject": {
"example": "cloudflare.com",
"type": "string"
},
"certValid": {
"example": true,
"type": "boolean"
},
"curveID": {
"example": "X25519",
"type": "string"
},
"feasible": {
"example": true,
"type": "boolean"
},
"h2": {
"example": true,
"type": "boolean"
},
"host": {
"example": "www.cloudflare.com",
"type": "string"
},
"ip": {
"example": "104.16.124.96",
"type": "string"
},
"latencyMs": {
"example": 180,
"type": "integer"
},
"notAfter": {
"example": "2026-08-01T00:00:00Z",
"type": "string"
},
"port": {
"example": 443,
"type": "integer"
},
"privateTarget": {
"description": "PrivateTarget marks a target that resolves to a loopback/private/link-local\naddress: blocked before the probe unless the caller opted in, then flagged.",
"example": false,
"type": "boolean"
},
"reason": {
"type": "string"
},
"serverNames": {
"items": {
"type": "string"
},
"type": "array"
},
"target": {
"example": "www.cloudflare.com:443",
"type": "string"
},
"tls13": {
"example": true,
"type": "boolean"
},
"tlsVersion": {
"example": "1.3",
"type": "string"
},
"x25519": {
"example": true,
"type": "boolean"
}
},
"required": [
"alpn",
"certChainValid",
"certIssuer",
"certSubject",
"certValid",
"curveID",
"feasible",
"h2",
"host",
"ip",
"latencyMs",
"notAfter",
"port",
"privateTarget",
"reason",
"serverNames",
"target",
"tls13",
"tlsVersion",
"x25519"
],
"type": "object"
},
"ServerSettings": {
"description": "ServerSettings is the \"server\" block of an AmneziaWG inbound's Settings\nJSON: the interface-level configuration shared by every client/peer. The\nlisten port is deliberately not duplicated here — it lives on the inbound\nrow itself (Inbound.Port), like every other protocol.",
"properties": {
"contentPaddingAddition": {
"type": "string"
},
"disableCookies": {
"type": "boolean"
},
"externalInterface": {
"description": "ExternalInterface, IPv6Enabled, and IPv6ExternalInterface are live\nagain as of Phase 3.5 -- see the matching fields on Instance for what\nthey gate (internal/amneziawgnet's IPv6-address-alias mechanism).\nIPv6Subnet was never actually vestigial either: InstanceFromInbound\nalready consumes it (via serverAddressV6) to build the server's own\ntunnel address, same as always. Only RouteThroughXray, below, remains\ngenuinely vestigial as of the hard cutover to the embedded path\n(internal/amneziawgnet) -- read from existing stored settings for\nbackward compatibility, but not acted on by anything.",
"type": "string"
},
"h1": {
"type": "string"
},
"h2": {
"type": "string"
},
"h3": {
"type": "string"
},
"h4": {
"type": "string"
},
"headerProtectionKey": {
"description": "HeaderProtectionKey and ContentPaddingAddition are AmneziaWG 3.0\nfields, flat and top-level for the same tools/openapigen reason as\nthe block above; Obfuscation() below folds them back into\nObfuscation31's own identically named fields.\nHeaderProtectionKey is a base64 32-byte key; empty (the default)\ndisables AWG 3.0 header protection. A non-empty value requires\nevery one of S1-S4 above to be >= 12 -- ValidateObfuscation\nenforces this at save time, not just at IpcSet time.\nContentPaddingAddition is a \"low-high\" range or bare integer, the\nsame grammar and uint32 cap as H1-H4.",
"type": "string"
},
"i1": {
"type": "string"
},
"i2": {
"type": "string"
},
"i3": {
"type": "string"
},
"i4": {
"type": "string"
},
"i5": {
"type": "string"
},
"ipv6Enabled": {
"type": "boolean"
},
"ipv6ExternalInterface": {
"type": "string"
},
"ipv6Subnet": {
"type": "string"
},
"jc": {
"description": "Obfuscation31's fields, repeated flat (not embedded) rather than\nnested under their own key: encoding/json would happily inline an\nembedded Obfuscation31 the same way, but the frontend's Go->Zod/TS\ngenerator (tools/openapigen) does not — it emits a genuinely nested\n`obfuscation31` object, which would silently diverge from the real\nwire JSON. See Obfuscation() below for the manager-facing conversion.",
"type": "integer"
},
"jmax": {
"type": "integer"
},
"jmin": {
"type": "integer"
},
"keepaliveTimeout": {
"type": "string"
},
"maxHandshakeAttempts": {
"type": "string"
},
"mtu": {
"type": "integer"
},
"primaryDns": {
"description": "PrimaryDNS/SecondaryDNS seed client configs' DNS line. Blank is\nmeaningful, so no omitempty: a dropped key resurrects frontend defaults.",
"type": "string"
},
"privateKey": {
"type": "string"
},
"publicKey": {
"type": "string"
},
"randomTrailers": {
"description": "RandomTrailers/DisableCookies mirror Instance's identically named\nAmneziaWG 3.1 fields -- see that type's own doc comment for the real\nprotocol/interop details. Both real bool fields (not omitempty):\nbuildUAPIConfig always emits both lines explicitly so the\nreconfigure-in-place diff correctly notices a true->false edit, not\njust false->true.",
"type": "boolean"
},
"rejectAfterTime": {
"type": "string"
},
"rekeyAfterTime": {
"description": "RekeyAfterTime/RekeyTimeout/RejectAfterTime/KeepaliveTimeout/\nMaxHandshakeAttempts mirror Instance's identically named fields --\nsee that type's own doc comment for the grammar/width/real-default\ndetails. Flat and top-level for the same tools/openapigen reason as\nthe rest of this struct.",
"type": "string"
},
"rekeyTimeout": {
"type": "string"
},
"routeThroughXray": {
"type": "boolean"
},
"s1": {
"type": "integer"
},
"s2": {
"type": "integer"
},
"s3": {
"type": "integer"
},
"s4": {
"type": "integer"
},
"secondaryDns": {
"type": "string"
},
"subnetCidr": {
"type": "integer"
},
"subnetIp": {
"type": "string"
}
},
"required": [
"disableCookies",
"h1",
"h2",
"h3",
"h4",
"jc",
"jmax",
"jmin",
"primaryDns",
"privateKey",
"publicKey",
"randomTrailers",
"s1",
"s2",
"s3",
"s4",
"secondaryDns",
"subnetCidr",
"subnetIp"
],
"type": "object"
},
"Setting": {
"description": "Setting stores key-value configuration settings for the 3x-ui panel.",
"properties": {
"id": {
"type": "integer"
},
"key": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"id",
"key",
"value"
],
"type": "object"
},
"SubBalancer": {
"description": "SubBalancer is one extra JSON-subscription config document whose members are\nthe selected inbounds' proxy outbounds. SortOrder shares SubSortIndex semantics.",
"properties": {
"createdAt": {
"example": 1710000000000,
"format": "int64",
"type": "integer"
},
"enabled": {
"description": "No gorm default:true — a bool default makes an explicit false at insert\ncollapse back to the column default (zero value is skipped).",
"example": true,
"type": "boolean"
},
"id": {
"example": 1,
"type": "integer"
},
"inboundIds": {
"example": [
1,
3
],
"items": {
"type": "integer"
},
"type": "array"
},
"remark": {
"example": "auto-fastest",
"maxLength": 256,
"type": "string"
},
"sortOrder": {
"example": 1,
"minimum": 1,
"type": "integer"
},
"strategy": {
"enum": [
"leastLoad",
"leastPing",
"random",
"roundRobin"
],
"example": "random",
"type": "string"
},
"updatedAt": {
"example": 1710000000000,
"format": "int64",
"type": "integer"
}
},
"required": [
"createdAt",
"enabled",
"id",
"inboundIds",
"remark",
"sortOrder",
"strategy",
"updatedAt"
],
"type": "object"
},
"User": {
"description": "User represents a user account in the 3x-ui panel.",
"properties": {
"id": {
"type": "integer"
},
"password": {
"type": "string"
},
"username": {
"type": "string"
}
},
"required": [
"id",
"password",
"username"
],
"type": "object"
}
}
},
"security": [
{
"bearerAuth": []
},
{
"cookieAuth": []
}
],
"tags": [
{
"name": "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/*."
},
{
"name": "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."
},
{
"name": "Server",
"description": "System status, log retrieval, certificate generators, Xray binary management, and backup/restore. All under /panel/api/server."
},
{
"name": "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."
},
{
"name": "Nodes",
"description": "Manage remote 3x-ui panels acting as nodes for a central panel. All endpoints under /panel/api/nodes."
},
{
"name": "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."
},
{
"name": "Backup",
"description": "Operations that interact with the configured Telegram bot."
},
{
"name": "Settings",
"description": "Panel configuration and user credentials. All endpoints live under /panel/api/setting and require a logged-in session or Bearer token."
},
{
"name": "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."
},
{
"name": "Xray Settings",
"description": "Xray configuration template, outbound management, Warp/Nord/PIA integration, and config testing. All endpoints under /panel/api/xray."
},
{
"name": "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."
},
{
"name": "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."
},
{
"name": "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."
}
],
"paths": {
"/login": {
"post": {
"tags": [
"Authentication"
],
"summary": "Authenticate with username + password and receive a session cookie. Required before any cookie-based API call.",
"operationId": "post_login",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"username": {
"type": "string",
"description": "Panel admin username."
},
"password": {
"type": "string",
"description": "Panel admin password."
},
"twoFactorCode": {
"type": "string",
"description": "OTP code when 2FA is enabled. Omit otherwise."
}
},
"required": [
"username",
"password",
"twoFactorCode"
]
},
"example": {
"username": "admin",
"password": "admin",
"twoFactorCode": "123456"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"msg": "Logged in successfully"
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
}
}
},
"example": {
"success": false,
"msg": "Wrong username or password"
}
}
}
}
}
}
},
"/logout": {
"post": {
"tags": [
"Authentication"
],
"summary": "Clear the session cookie. Requires the CSRF header for browser sessions.",
"operationId": "post_logout",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true
}
}
}
}
}
}
},
"/csrf-token": {
"get": {
"tags": [
"Authentication"
],
"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.",
"operationId": "get_csrf_token",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": "csrf-token-string"
}
}
}
}
}
}
},
"/getTwoFactorEnable": {
"post": {
"tags": [
"Authentication"
],
"summary": "Returns whether 2FA is enabled on the panel — used by the login page to decide whether to show the OTP field.",
"operationId": "post_getTwoFactorEnable",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": false
}
}
}
}
}
}
},
"/panel/api/inbounds/list": {
"get": {
"tags": [
"Inbounds"
],
"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.",
"operationId": "get_panel_api_inbounds_list",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Inbound"
}
}
}
},
"example": {
"success": true,
"obj": [
{
"clientStats": [
{
"down": 2097152,
"email": "user1",
"enable": true,
"expiryTime": 1735689600000,
"id": 14825,
"inboundId": 1,
"lastOnline": 1735680000000,
"lastSubFetch": 1735680000000,
"reset": 0,
"resetCount": 0,
"resetDay": 0,
"resetMax": 0,
"subId": "i7tvdpeffi0hvvf1",
"total": 10737418240,
"up": 1048576,
"uuid": "e18c9a96-71bf-48d4-933f-8b9a46d4290c"
}
],
"disableFlow": false,
"down": 0,
"enable": true,
"expiryTime": 0,
"fallbackParent": null,
"id": 1,
"lastTrafficResetTime": 0,
"listen": "",
"nodeId": null,
"originNodeGuid": "",
"port": 443,
"protocol": "vless",
"remark": "VLESS-443",
"settings": null,
"shareAddr": "",
"shareAddrStrategy": "node",
"sniffing": null,
"streamSettings": null,
"subSortIndex": 1,
"tag": "in-443-tcp",
"total": 0,
"trafficReset": "never",
"trafficResetDay": 1,
"up": 0
}
]
}
}
}
}
}
}
},
"/panel/api/inbounds/list/slim": {
"get": {
"tags": [
"Inbounds"
],
"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, ...).",
"operationId": "get_panel_api_inbounds_list_slim",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
{
"id": 1,
"remark": "VLESS-443",
"settings": {
"clients": [
{
"email": "alice",
"enable": true
}
],
"decryption": "none"
},
"clientStats": []
}
]
}
}
}
}
}
}
},
"/panel/api/inbounds/options": {
"get": {
"tags": [
"Inbounds"
],
"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.",
"operationId": "get_panel_api_inbounds_options",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InboundOption"
}
}
}
},
"example": {
"success": true,
"obj": [
{
"awgServer": null,
"enable": true,
"id": 1,
"listen": "",
"mtprotoDomain": "",
"nodeAddress": "",
"nodeId": null,
"port": 443,
"protocol": "vless",
"remark": "VLESS-443",
"shareAddr": "",
"shareAddrStrategy": "",
"ssMethod": "",
"tag": "in-443-tcp",
"tlsFlowCapable": true,
"wgDns": "",
"wgMtu": 0,
"wgPublicKey": ""
}
]
}
}
}
}
}
}
},
"/panel/api/inbounds/allLinks": {
"get": {
"tags": [
"Inbounds"
],
"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.",
"operationId": "get_panel_api_inbounds_allLinks",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
"vless://uuid@host:443?security=reality&...#Germany-alice",
"vmess://eyJ2IjoyLC..."
]
}
}
}
}
}
}
},
"/panel/api/inbounds/get/{id}": {
"get": {
"tags": [
"Inbounds"
],
"summary": "Fetch a single inbound by numeric ID.",
"operationId": "get_panel_api_inbounds_get_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Inbound ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/inbounds/add": {
"post": {
"tags": [
"Inbounds"
],
"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).",
"operationId": "post_panel_api_inbounds_add",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"enable": true,
"remark": "VLESS-443",
"listen": "",
"port": 443,
"protocol": "vless",
"expiryTime": 0,
"total": 0,
"settings": {
"clients": [
{
"id": "...",
"email": "user1"
}
],
"decryption": "none",
"fallbacks": []
},
"streamSettings": {
"network": "tcp",
"security": "reality",
"realitySettings": {
"show": false,
"dest": "..."
}
},
"sniffing": {
"enabled": true,
"destOverride": [
"http",
"tls"
]
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
}
}
},
"example": {
"success": false,
"msg": "Port 443 is already in use"
}
}
}
}
}
}
},
"/panel/api/inbounds/del/{id}": {
"post": {
"tags": [
"Inbounds"
],
"summary": "Delete an inbound by ID. Also removes its associated client stats rows.",
"operationId": "post_panel_api_inbounds_del_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Inbound ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/inbounds/bulkDel": {
"post": {
"tags": [
"Inbounds"
],
"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.",
"operationId": "post_panel_api_inbounds_bulkDel",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"ids": [
1,
2,
3
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"deleted": 2,
"skipped": [
{
"id": 3,
"reason": "..."
}
]
}
}
}
}
}
}
}
},
"/panel/api/inbounds/update/{id}": {
"post": {
"tags": [
"Inbounds"
],
"summary": "Replace an inbound’s configuration. Body shape mirrors /add. Heavy on inbounds with thousands of clients — prefer /setEnable for enable-only flips.",
"operationId": "post_panel_api_inbounds_update_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Inbound ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/inbounds/setEnable/{id}": {
"post": {
"tags": [
"Inbounds"
],
"summary": "Toggle only the enable flag without serialising the whole settings JSON. Recommended for UI switches on large inbounds.",
"operationId": "post_panel_api_inbounds_setEnable_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Inbound ID.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"enable": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/inbounds/{id}/subSortIndex": {
"post": {
"tags": [
"Inbounds"
],
"summary": "Set only the subscription sort order. Reads the stored inbound, so a reorder cannot carry a stale client list over a concurrent edit.",
"operationId": "post_panel_api_inbounds_id_subSortIndex",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Inbound ID.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"subSortIndex": 2
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/inbounds/{id}/resetTraffic": {
"post": {
"tags": [
"Inbounds"
],
"summary": "Zero out upload + download counters for a single inbound. Does not touch per-client counters.",
"operationId": "post_panel_api_inbounds_id_resetTraffic",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Inbound ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/inbounds/{id}/delAllClients": {
"post": {
"tags": [
"Inbounds"
],
"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.",
"operationId": "post_panel_api_inbounds_id_delAllClients",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Inbound ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"deleted": 12
}
}
}
}
}
}
}
},
"/panel/api/inbounds/resetAllTraffics": {
"post": {
"tags": [
"Inbounds"
],
"summary": "Reset upload + download counters on every inbound. Destructive — accounting history is lost.",
"operationId": "post_panel_api_inbounds_resetAllTraffics",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/inbounds/import": {
"post": {
"tags": [
"Inbounds"
],
"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.",
"operationId": "post_panel_api_inbounds_import",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/inbounds/pushClientTraffics": {
"post": {
"tags": [
"Inbounds"
],
"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.",
"operationId": "post_panel_api_inbounds_pushClientTraffics",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"masterGuid": "9f6c2d-…",
"traffics": [
{
"email": "alice",
"up": 1048576,
"down": 2097152
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true
}
}
}
}
}
}
},
"/panel/api/inbounds/{id}/fallbacks": {
"get": {
"tags": [
"Inbounds"
],
"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.",
"operationId": "get_panel_api_inbounds_id_fallbacks",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Master inbound ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
{
"id": 1,
"masterId": 10,
"childId": 11,
"name": "",
"alpn": "",
"path": "/vlws",
"dest": "",
"xver": 2,
"sortOrder": 0
}
]
}
}
}
}
}
},
"post": {
"tags": [
"Inbounds"
],
"summary": "Replace the entire fallback list for a master inbound. Body is JSON. Triggers an Xray restart.",
"operationId": "post_panel_api_inbounds_id_fallbacks",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Master inbound ID.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"fallbacks": [
{
"childId": 11,
"path": "/vlws",
"xver": 2
},
{
"childId": 12,
"alpn": "h2",
"dest": "8443"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"msg": "Inbound updated"
}
}
}
}
}
}
},
"/panel/api/openapi.json": {
"get": {
"tags": [
"Server"
],
"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.",
"operationId": "get_panel_api_openapi_json",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/status": {
"get": {
"tags": [
"Server"
],
"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.",
"operationId": "get_panel_api_server_status",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"cpu": 12.5,
"mem": {
"current": 2147483648,
"total": 8589934592
},
"swap": {
"current": 0,
"total": 4294967296
},
"disk": {
"current": 53687091200,
"total": 268435456000
},
"netIO": {
"up": 1073741824,
"down": 2147483648
},
"xray": {
"state": "running",
"version": "v25.10.31"
},
"tcpCount": 42,
"load": {
"load1": 0.5,
"load5": 0.3,
"load15": 0.2
}
}
}
}
}
}
}
}
},
"/panel/api/server/fail2banStatus": {
"get": {
"tags": [
"Server"
],
"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.",
"operationId": "get_panel_api_server_fail2banStatus",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"enabled": true,
"installed": true,
"usable": true,
"windows": false
}
}
}
}
}
}
}
},
"/panel/api/server/cpuHistory/{bucket}": {
"get": {
"tags": [
"Server"
],
"summary": "Legacy: aggregated CPU history. Use /history/cpu/:bucket instead — same data with a uniform {t, v} shape.",
"operationId": "get_panel_api_server_cpuHistory_bucket",
"parameters": [
{
"name": "bucket",
"in": "path",
"required": true,
"description": "Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/history/{metric}/{bucket}": {
"get": {
"tags": [
"Server"
],
"summary": "Aggregated time-series for one metric. Returns an array of {t, v} samples covering the last ~6 hours.",
"operationId": "get_panel_api_server_history_metric_bucket",
"parameters": [
{
"name": "metric",
"in": "path",
"required": true,
"description": "cpu | mem | netUp | netDown | online | load1 | load5 | load15.",
"schema": {
"type": "string"
}
},
{
"name": "bucket",
"in": "path",
"required": true,
"description": "Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
{
"t": 1700000000,
"v": 12.5
},
{
"t": 1700000002,
"v": 13.1
}
]
}
}
}
}
}
}
},
"/panel/api/server/xrayMetricsState": {
"get": {
"tags": [
"Server"
],
"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.",
"operationId": "get_panel_api_server_xrayMetricsState",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/xrayMetricsHistory/{metric}/{bucket}": {
"get": {
"tags": [
"Server"
],
"summary": "Time-series history for one Xray runtime metric over the last ~6 hours. Same {t, v} shape as /history/:metric/:bucket.",
"operationId": "get_panel_api_server_xrayMetricsHistory_metric_bucket",
"parameters": [
{
"name": "metric",
"in": "path",
"required": true,
"description": "xrAlloc | xrSys | xrHeapObjects | xrNumGC | xrPauseNs.",
"schema": {
"type": "string"
}
},
{
"name": "bucket",
"in": "path",
"required": true,
"description": "Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/xrayObservatory": {
"get": {
"tags": [
"Server"
],
"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.",
"operationId": "get_panel_api_server_xrayObservatory",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/xrayObservatoryHistory/{tag}/{bucket}": {
"get": {
"tags": [
"Server"
],
"summary": "Time-series of observatory probe results for one outbound tag. Same {t, v} shape as the other history endpoints.",
"operationId": "get_panel_api_server_xrayObservatoryHistory_tag_bucket",
"parameters": [
{
"name": "tag",
"in": "path",
"required": true,
"description": "Outbound tag from the observatory config.",
"schema": {
"type": "string"
}
},
{
"name": "bucket",
"in": "path",
"required": true,
"description": "Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/getXrayVersion": {
"get": {
"tags": [
"Server"
],
"summary": "List Xray binary versions available for install on this host.",
"operationId": "get_panel_api_server_getXrayVersion",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
"v25.10.31",
"v25.9.15",
"v25.8.1"
]
}
}
}
}
}
}
},
"/panel/api/server/getPanelUpdateInfo": {
"get": {
"tags": [
"Server"
],
"summary": "Check whether a newer 3x-ui release is available on GitHub.",
"operationId": "get_panel_api_server_getPanelUpdateInfo",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/getUpdateStatus": {
"get": {
"tags": [
"Server"
],
"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.",
"operationId": "get_panel_api_server_getUpdateStatus",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/PanelUpdateStatus"
}
}
},
"example": {
"success": true,
"obj": {
"exitCode": 0,
"finishedAt": 1735689612,
"runId": "1735689600123456789",
"state": "success"
}
}
}
}
}
}
}
},
"/panel/api/server/getConfigJson": {
"get": {
"tags": [
"Server"
],
"summary": "Return the assembled Xray config that’s currently running on this host.",
"operationId": "get_panel_api_server_getConfigJson",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/getDb": {
"get": {
"tags": [
"Server"
],
"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.",
"operationId": "get_panel_api_server_getDb",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/getMigration": {
"get": {
"tags": [
"Server"
],
"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.",
"operationId": "get_panel_api_server_getMigration",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/getNewUUID": {
"get": {
"tags": [
"Server"
],
"summary": "Generate a fresh UUID v4. Convenience helper for client IDs.",
"operationId": "get_panel_api_server_getNewUUID",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": "550e8400-e29b-41d4-a716-446655440000"
}
}
}
}
}
}
},
"/panel/api/server/getWebCertFiles": {
"get": {
"tags": [
"Server"
],
"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.",
"operationId": "get_panel_api_server_getWebCertFiles",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"webCertFile": "/root/cert/example.com/fullchain.pem",
"webKeyFile": "/root/cert/example.com/privkey.pem"
}
}
}
}
}
}
}
},
"/panel/api/server/descendants": {
"get": {
"tags": [
"Server"
],
"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.",
"operationId": "get_panel_api_server_descendants",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
{
"guid": "c3d4-...",
"parentGuid": "a1b2-...",
"name": "Node3",
"address": "10.0.0.3",
"status": "online"
}
]
}
}
}
}
}
}
},
"/panel/api/server/getNewX25519Cert": {
"get": {
"tags": [
"Server"
],
"summary": "Generate a new X25519 keypair for Reality.",
"operationId": "get_panel_api_server_getNewX25519Cert",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"privateKey": "uN9qLfV3zH8w...",
"publicKey": "5v8xPqR2sM7k..."
}
}
}
}
}
}
}
},
"/panel/api/server/getNewmldsa65": {
"get": {
"tags": [
"Server"
],
"summary": "Generate a new ML-DSA-65 keypair (post-quantum signature). Returns {privateKey, publicKey, seed}.",
"operationId": "get_panel_api_server_getNewmldsa65",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"privateKey": "mdsa65priv...",
"publicKey": "mdsa65pub...",
"seed": "random-seed..."
}
}
}
}
}
}
}
},
"/panel/api/server/getNewmlkem768": {
"get": {
"tags": [
"Server"
],
"summary": "Generate a new ML-KEM-768 keypair (post-quantum KEM). Returns {clientKey, serverKey}.",
"operationId": "get_panel_api_server_getNewmlkem768",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"clientKey": "mlkem768-client...",
"serverKey": "mlkem768-server..."
}
}
}
}
}
}
}
},
"/panel/api/server/getNewVlessEnc": {
"get": {
"tags": [
"Server"
],
"summary": "Generate VLESS encryption auth options. Returns an auths array each with id, label, encryption, and decryption fields.",
"operationId": "get_panel_api_server_getNewVlessEnc",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"auths": [
{
"id": 0,
"label": "Auth #0",
"encryption": "aes-256-gcm",
"decryption": ""
}
]
}
}
}
}
}
}
}
},
"/panel/api/server/stopXrayService": {
"post": {
"tags": [
"Server"
],
"summary": "Stop the Xray binary. All proxies go offline immediately.",
"operationId": "post_panel_api_server_stopXrayService",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
}
}
},
"example": {
"success": false,
"msg": "Xray is not running"
}
}
}
}
}
}
},
"/panel/api/server/restartXrayService": {
"post": {
"tags": [
"Server"
],
"summary": "Reload Xray with the current config. Typically required after structural inbound or routing changes.",
"operationId": "post_panel_api_server_restartXrayService",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
}
}
},
"example": {
"success": false,
"msg": "Xray config is invalid: ..."
}
}
}
}
}
}
},
"/panel/api/server/installXray/{version}": {
"post": {
"tags": [
"Server"
],
"summary": "Download and install the specified Xray version. Pass \"latest\" for the newest release.",
"operationId": "post_panel_api_server_installXray_version",
"parameters": [
{
"name": "version",
"in": "path",
"required": true,
"description": "Xray tag (e.g. v25.10.31) or \"latest\".",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/updatePanel": {
"post": {
"tags": [
"Server"
],
"summary": "Self-update the panel to the latest version. The server restarts on success.",
"operationId": "post_panel_api_server_updatePanel",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"runId": "1735689600123456789"
}
}
}
}
}
}
}
},
"/panel/api/server/setUpdateChannel": {
"post": {
"tags": [
"Server"
],
"summary": "Toggle the panel update channel between stable and the rolling per-commit dev release. Only effective on dev builds.",
"operationId": "post_panel_api_server_setUpdateChannel",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/updateGeofile": {
"post": {
"tags": [
"Server"
],
"summary": "Refresh the default GeoIP / GeoSite data files. Body can include a fileName, or use the /:fileName variant.",
"operationId": "post_panel_api_server_updateGeofile",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/updateGeofile/{fileName}": {
"post": {
"tags": [
"Server"
],
"summary": "Refresh a single Geo file by filename (e.g. geoip.dat, geosite.dat).",
"operationId": "post_panel_api_server_updateGeofile_fileName",
"parameters": [
{
"name": "fileName",
"in": "path",
"required": true,
"description": "Filename of the data file to refresh.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/logs/{count}": {
"post": {
"tags": [
"Server"
],
"summary": "Return the last N lines of the panel’s own log.",
"operationId": "post_panel_api_server_logs_count",
"parameters": [
{
"name": "count",
"in": "path",
"required": true,
"description": "Number of trailing log lines.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"level": "info",
"syslog": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": "2025/01/01 12:00:00 [INFO] Server started\n2025/01/01 12:00:01 [INFO] Xray is running"
}
}
}
}
}
}
},
"/panel/api/server/xraylogs/{count}": {
"post": {
"tags": [
"Server"
],
"summary": "Return the last N lines of the Xray process log.",
"operationId": "post_panel_api_server_xraylogs_count",
"parameters": [
{
"name": "count",
"in": "path",
"required": true,
"description": "Number of trailing log lines.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"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"
}
}
}
}
}
}
},
"/panel/api/server/amneziawglogs/{count}": {
"post": {
"tags": [
"Server"
],
"summary": "Return live AmneziaWG peer activity (handshake, endpoint, transfer) plus the panel’s own AmneziaWG event lines.",
"operationId": "post_panel_api_server_amneziawglogs_count",
"parameters": [
{
"name": "count",
"in": "path",
"required": true,
"description": "Maximum peer rows and event lines to return.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/AmneziaWGLogs"
}
}
},
"example": {
"success": true,
"obj": {
"events": [
"2025/01/01 12:00:00 amneziawg: started interface awg1 for inbound 1"
],
"peers": [
{
"allowedIPs": "10.8.1.2/32",
"down": 4194304,
"email": "peer@example.com",
"endpoint": "203.0.113.9:51820",
"handshake": 1735732800000,
"inboundId": 1,
"interface": "awg1",
"online": true,
"tag": "inbound-51820",
"up": 1048576
}
],
"running": true
}
}
}
}
}
}
}
},
"/panel/api/server/importDB": {
"post": {
"tags": [
"Server"
],
"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.",
"operationId": "post_panel_api_server_importDB",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/getNewEchCert": {
"post": {
"tags": [
"Server"
],
"summary": "Generate a new ECH (Encrypted Client Hello) keypair and config list for the given SNI.",
"operationId": "post_panel_api_server_getNewEchCert",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/server/getCertHash": {
"post": {
"tags": [
"Server"
],
"summary": "Compute the hex SHA-256 of a certificate (DER) for pinning (pinnedPeerCertSha256). Provide either a server file path or inline PEM/DER content.",
"operationId": "post_panel_api_server_getCertHash",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
"e8e2d3..."
]
}
}
}
}
}
}
},
"/panel/api/server/getRemoteCertHash": {
"post": {
"tags": [
"Server"
],
"summary": "Run `xray tls ping` against a remote server and return its live leaf-certificate SHA-256 hash(es) for pinning (pinnedPeerCertSha256).",
"operationId": "post_panel_api_server_getRemoteCertHash",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
"e8e2d3..."
]
}
}
}
}
}
}
},
"/panel/api/server/scanRealityTarget": {
"post": {
"tags": [
"Server"
],
"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.",
"operationId": "post_panel_api_server_scanRealityTarget",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/RealityScanResult"
}
}
},
"example": {
"success": true,
"obj": {
"alpn": "h2",
"certChainValid": true,
"certIssuer": "Google Trust Services",
"certSubject": "cloudflare.com",
"certValid": true,
"curveID": "X25519",
"feasible": true,
"h2": true,
"host": "www.cloudflare.com",
"ip": "104.16.124.96",
"latencyMs": 180,
"notAfter": "2026-08-01T00:00:00Z",
"port": 443,
"privateTarget": false,
"reason": "",
"serverNames": [
""
],
"target": "www.cloudflare.com:443",
"tls13": true,
"tlsVersion": "1.3",
"x25519": true
}
}
}
}
}
}
}
},
"/panel/api/server/scanRealityTargets": {
"post": {
"tags": [
"Server"
],
"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.",
"operationId": "post_panel_api_server_scanRealityTargets",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RealityScanResult"
}
}
}
},
"example": {
"success": true,
"obj": [
{
"alpn": "h2",
"certChainValid": true,
"certIssuer": "Google Trust Services",
"certSubject": "cloudflare.com",
"certValid": true,
"curveID": "X25519",
"feasible": true,
"h2": true,
"host": "www.cloudflare.com",
"ip": "104.16.124.96",
"latencyMs": 180,
"notAfter": "2026-08-01T00:00:00Z",
"port": 443,
"privateTarget": false,
"reason": "",
"serverNames": [
""
],
"target": "www.cloudflare.com:443",
"tls13": true,
"tlsVersion": "1.3",
"x25519": true
}
]
}
}
}
}
}
}
},
"/panel/api/server/clientIps": {
"get": {
"tags": [
"Server"
],
"summary": "Fetch the fully aggregated inbound_client_ips database table. Used by nodes to sync recently active IPs across the cluster.",
"operationId": "get_panel_api_server_clientIps",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InboundClientIps"
}
}
}
},
"example": {
"success": true,
"obj": [
{
"clientEmail": "",
"id": 0,
"ips": null
}
]
}
}
}
}
}
},
"post": {
"tags": [
"Server"
],
"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.",
"operationId": "post_panel_api_server_clientIps",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/clients/list": {
"get": {
"tags": [
"Clients"
],
"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).",
"operationId": "get_panel_api_clients_list",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
{
"id": 1,
"email": "alice@example.com",
"subId": "abcd1234",
"uuid": "...",
"totalGB": 53687091200,
"expiryTime": 1735689600000,
"enable": true,
"reverse": null,
"inboundIds": [
3,
5
],
"traffic": {
"up": 1024,
"down": 4096,
"enable": true
}
}
]
}
}
}
}
}
}
},
"/panel/api/clients/list/paged": {
"get": {
"tags": [
"Clients"
],
"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.",
"operationId": "get_panel_api_clients_list_paged",
"parameters": [
{
"name": "page",
"in": "query",
"required": true,
"description": "1-indexed page number. Defaults to 1.",
"schema": {
"type": "integer"
}
},
{
"name": "pageSize",
"in": "query",
"required": true,
"description": "Rows per page. Defaults to 25, capped at 200.",
"schema": {
"type": "integer"
}
},
{
"name": "search",
"in": "query",
"required": true,
"description": "Case-insensitive substring match on email / subId / comment.",
"schema": {
"type": "string"
}
},
{
"name": "filter",
"in": "query",
"required": true,
"description": "Status bucket: online | active | deactive | depleted | expiring.",
"schema": {
"type": "string"
}
},
{
"name": "protocol",
"in": "query",
"required": true,
"description": "Match clients attached to at least one inbound of this protocol (vless, vmess, trojan, shadowsocks, ...).",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"required": true,
"description": "Sort key: enable | email | inboundIds | traffic | remaining | expiryTime.",
"schema": {
"type": "string"
}
},
{
"name": "order",
"in": "query",
"required": true,
"description": "ascend or descend.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"items": [
{
"email": "alice@example.com",
"subId": "abcd1234",
"enable": true,
"totalGB": 53687091200,
"expiryTime": 1735689600000,
"limitIp": 0,
"limitHwid": 0,
"reset": 0,
"inboundIds": [
3,
5
],
"traffic": {
"up": 1024,
"down": 4096,
"enable": true
},
"createdAt": 1735000000000,
"updatedAt": 1735100000000
}
],
"total": 2000,
"filtered": 47,
"page": 1,
"pageSize": 25,
"summary": {
"total": 2000,
"active": 1850,
"onlineCount": 1,
"depletedCount": 0,
"expiringCount": 0,
"deactiveCount": 150,
"online": [
"alice@example.com"
],
"depleted": [],
"expiring": [],
"deactive": [
"bob@example.com"
]
}
}
}
}
}
}
}
}
},
"/panel/api/clients/get/{email}": {
"get": {
"tags": [
"Clients"
],
"summary": "Fetch one client by email, including the inbound IDs and external config IDs it is attached to.",
"operationId": "get_panel_api_clients_get_email",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email (unique identifier).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/clients/get/tgId/{tgId}": {
"get": {
"tags": [
"Clients"
],
"summary": "Fetch clients by Telegram user ID. Returns an array since multiple clients can share the same Telegram ID.",
"operationId": "get_panel_api_clients_get_tgId_tgId",
"parameters": [
{
"name": "tgId",
"in": "path",
"required": true,
"description": "Telegram user ID (numeric).",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/clients/add": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_add",
"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.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"client": {
"email": "alice@example.com",
"totalGB": 53687091200,
"expiryTime": 1735689600000,
"tgId": 0,
"limitIp": 0,
"limitHwid": 0,
"enable": true
},
"inboundIds": [
3,
5
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"msg": "Client added"
}
}
}
}
}
}
},
"/panel/api/clients/update/{email}": {
"post": {
"tags": [
"Clients"
],
"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).",
"operationId": "post_panel_api_clients_update_email",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Current client email (unique identifier).",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"email": "alice@example.com",
"totalGB": 107374182400,
"expiryTime": 1767225600000,
"limitHwid": 2,
"tgId": 123456789,
"enable": true
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"msg": "Client updated"
}
}
}
}
}
}
},
"/panel/api/clients/del/{email}": {
"post": {
"tags": [
"Clients"
],
"summary": "Delete a client by email. Removes it from every attached inbound and drops its traffic record unless keepTraffic=1 is passed.",
"operationId": "post_panel_api_clients_del_email",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email (unique identifier).",
"schema": {
"type": "string"
}
},
{
"name": "keepTraffic",
"in": "query",
"required": true,
"description": "Pass 1 to retain the xray_client_traffic row after deletion.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"msg": "Client deleted"
}
}
}
}
}
}
},
"/panel/api/clients/{email}/attach": {
"post": {
"tags": [
"Clients"
],
"summary": "Attach an existing client to one or more additional inbounds. Body is JSON.",
"operationId": "post_panel_api_clients_email_attach",
"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.",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email (unique identifier).",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"inboundIds": [
7,
9
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true
}
}
}
}
}
}
},
"/panel/api/clients/{email}/detach": {
"post": {
"tags": [
"Clients"
],
"summary": "Detach a client from one or more inbounds without deleting the client.",
"operationId": "post_panel_api_clients_email_detach",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email (unique identifier).",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"inboundIds": [
5
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true
}
}
}
}
}
}
},
"/panel/api/clients/{email}/externalLinks": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_email_externalLinks",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email (unique identifier).",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"externalLinks": {
"type": "array",
"items": {
"type": "object"
},
"description": "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."
}
},
"required": [
"externalLinks"
]
},
"example": {
"externalLinks": [
{
"kind": "link",
"value": "vless://uuid@host:443?...#srv",
"remark": "DE",
"enable": true,
"expiryTime": 0
},
{
"kind": "subscription",
"value": "https://provider.example/sub/abc",
"remark": "Provider",
"enable": false,
"expiryTime": 1767225600000,
"namePrefix": "[zjh] "
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true
}
}
}
}
}
}
},
"/panel/api/clients/resetAllTraffics": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_resetAllTraffics",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true
}
}
}
}
}
}
},
"/panel/api/clients/delDepleted": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_delDepleted",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"deleted": 0
}
}
}
}
}
}
}
},
"/panel/api/clients/delOrphans": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_delOrphans",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"deleted": 0
}
}
}
}
}
}
}
},
"/panel/api/clients/export": {
"get": {
"tags": [
"Clients"
],
"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.",
"operationId": "get_panel_api_clients_export",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
{
"client": {
"email": "alice@example.com",
"id": "...",
"totalGB": 53687091200,
"expiryTime": 0,
"limitHwid": 2,
"enable": true,
"subId": "..."
},
"inboundIds": [
7,
9
]
}
]
}
}
}
}
}
}
},
"/panel/api/clients/import": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_import",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"data": "[{\"client\":{\"email\":\"alice@example.com\",\"enable\":true},\"inboundIds\":[7]}]"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"created": 2,
"skipped": [
{
"email": "alice@example.com",
"reason": "email already in use: alice@example.com"
}
]
}
}
}
}
}
}
}
},
"/panel/api/clients/bulkAdjust": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_bulkAdjust",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"emails": [
"alice",
"bob"
],
"addDays": 30,
"addBytes": 53687091200,
"flow": "xtls-rprx-vision"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"adjusted": 2,
"skipped": [
{
"email": "carol",
"reason": "unlimited expiry"
}
]
}
}
}
}
}
}
}
},
"/panel/api/clients/bulkEnable": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_bulkEnable",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"emails": [
"alice",
"bob"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"changed": 2,
"skipped": [
{
"email": "carol",
"reason": "client not found"
}
]
}
}
}
}
}
}
}
},
"/panel/api/clients/bulkDisable": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_bulkDisable",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"emails": [
"alice",
"bob"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"changed": 2,
"skipped": [
{
"email": "carol",
"reason": "client not found"
}
]
}
}
}
}
}
}
}
},
"/panel/api/clients/bulkDel": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_bulkDel",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"emails": [
"alice",
"bob"
],
"keepTraffic": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"deleted": 2,
"skipped": [
{
"email": "carol",
"reason": "client not found"
}
]
}
}
}
}
}
}
}
},
"/panel/api/clients/bulkCreate": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_bulkCreate",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": [
{
"client": {
"email": "alice@example.com",
"totalGB": 53687091200,
"expiryTime": 0,
"limitHwid": 2,
"enable": true
},
"inboundIds": [
7
]
},
{
"client": {
"email": "bob@example.com",
"totalGB": 53687091200,
"expiryTime": 0,
"limitHwid": 0,
"enable": true
},
"inboundIds": [
7,
9
]
}
]
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"created": 2,
"skipped": [
{
"email": "alice@example.com",
"reason": "email already in use"
}
]
}
}
}
}
}
}
}
},
"/panel/api/clients/groups/bulkAdd": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_groups_bulkAdd",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"emails": [
"alice",
"bob"
],
"group": "customer-a"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"affected": 2
}
}
}
}
}
}
}
},
"/panel/api/clients/groups/bulkRemove": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_groups_bulkRemove",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"emails": [
"alice",
"bob"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"affected": 2
}
}
}
}
}
}
}
},
"/panel/api/clients/bulkAttach": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_bulkAttach",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"emails": [
"alice",
"bob"
],
"inboundIds": [
7,
9
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"attached": [
"alice",
"bob"
],
"skipped": [
"bob"
],
"errors": []
}
}
}
}
}
}
}
},
"/panel/api/clients/bulkDetach": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_bulkDetach",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"emails": [
"alice",
"bob"
],
"inboundIds": [
7,
9
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"detached": [
"alice",
"bob"
],
"skipped": [],
"errors": []
}
}
}
}
}
}
}
},
"/panel/api/clients/bulkResetTraffic": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_bulkResetTraffic",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"emails": [
"alice",
"bob"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"affected": 2
}
}
}
}
}
}
}
},
"/panel/api/clients/groups": {
"get": {
"tags": [
"Clients"
],
"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).",
"operationId": "get_panel_api_clients_groups",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
{
"name": "customer-a",
"clientCount": 5
},
{
"name": "internal",
"clientCount": 0
}
]
}
}
}
}
}
}
},
"/panel/api/clients/groups/{name}/emails": {
"get": {
"tags": [
"Clients"
],
"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.",
"operationId": "get_panel_api_clients_groups_name_emails",
"parameters": [
{
"name": "name",
"in": "path",
"required": true,
"description": "Group name (URL-encoded).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
"alice",
"bob",
"carol"
]
}
}
}
}
}
}
},
"/panel/api/clients/groups/create": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_groups_create",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"name": "customer-a"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"name": "customer-a"
}
}
}
}
}
}
}
},
"/panel/api/clients/groups/rename": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_groups_rename",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"oldName": "customer-a",
"newName": "tier-1"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"affected": 5
}
}
}
}
}
}
}
},
"/panel/api/clients/groups/delete": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_groups_delete",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"name": "customer-a"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"affected": 5
}
}
}
}
}
}
}
},
"/panel/api/clients/groups/resetTraffic": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_groups_resetTraffic",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"name": "customer-a"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"name": "customer-a"
}
}
}
}
}
}
}
},
"/panel/api/clients/resetTraffic/{email}": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_resetTraffic_email",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/clients/updateTraffic/{email}": {
"post": {
"tags": [
"Clients"
],
"summary": "Manually adjust a client’s upload + download counters. Useful for migrations from external accounting systems.",
"operationId": "post_panel_api_clients_updateTraffic_email",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"upload": 1073741824,
"download": 5368709120
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/clients/ips/{email}": {
"post": {
"tags": [
"Clients"
],
"summary": "List source IPs that have connected with the given client’s credentials. Returns an array of \"ip (timestamp)\" strings.",
"operationId": "post_panel_api_clients_ips_email",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/clients/clearIps/{email}": {
"post": {
"tags": [
"Clients"
],
"summary": "Reset the recorded IP list for a client.",
"operationId": "post_panel_api_clients_clearIps_email",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/clients/hwids/{email}": {
"post": {
"tags": [
"Clients"
],
"summary": "List registered HWID devices for a client. Hashes are not exposed.",
"operationId": "post_panel_api_clients_hwids_email",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
{
"id": 1,
"firstSeen": 1735000000000,
"lastSeen": 1735100000000,
"userAgent": "Happ/1.0",
"deviceOs": "android",
"osVersion": "15",
"deviceModel": "Pixel 9"
}
]
}
}
}
}
}
},
"delete": {
"tags": [
"Clients"
],
"summary": "Clear all registered HWID devices for a client so new devices can register again.",
"operationId": "delete_panel_api_clients_hwids_email",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/clients/hwids/{email}/{id}": {
"delete": {
"tags": [
"Clients"
],
"summary": "Remove a single registered HWID device by its id, freeing one slot under the HWID limit.",
"operationId": "delete_panel_api_clients_hwids_email_id",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email.",
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "path",
"required": true,
"description": "Device id, from the list endpoint.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/clients/onlines": {
"post": {
"tags": [
"Clients"
],
"summary": "List the emails of currently connected clients (last seen within the heartbeat window), deduped across every node.",
"operationId": "post_panel_api_clients_onlines",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
"user1",
"user2"
]
}
}
}
}
}
}
},
"/panel/api/clients/onlinesByGuid": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_onlinesByGuid",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"a1b2-...": [
"user1"
],
"c3d4-...": [
"user1",
"user2"
]
}
}
}
}
}
}
}
},
"/panel/api/clients/clientIpsByGuid": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_clientIpsByGuid",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"a1b2-...": {
"user1": [
{
"ip": "1.2.3.4",
"timestamp": 1700000000
}
]
}
}
}
}
}
}
}
}
},
"/panel/api/clients/activeInbounds": {
"post": {
"tags": [
"Clients"
],
"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.",
"operationId": "post_panel_api_clients_activeInbounds",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"a1b2-...": [
"in-443-tcp",
"in-8443-tcp"
]
}
}
}
}
}
}
}
},
"/panel/api/clients/lastOnline": {
"post": {
"tags": [
"Clients"
],
"summary": "Map of client email → last-seen unix timestamp.",
"operationId": "post_panel_api_clients_lastOnline",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"user1": 1700000000,
"user2": 1699999000
}
}
}
}
}
}
}
},
"/panel/api/clients/traffic/{email}": {
"get": {
"tags": [
"Clients"
],
"summary": "Traffic counters for a client identified by email.",
"operationId": "get_panel_api_clients_traffic_email",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email (unique across the panel).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/ClientTraffic"
}
}
},
"example": {
"success": true,
"obj": {
"down": 2097152,
"email": "user1",
"enable": true,
"expiryTime": 1735689600000,
"id": 14825,
"inboundId": 1,
"lastOnline": 1735680000000,
"lastSubFetch": 1735680000000,
"reset": 0,
"resetCount": 0,
"resetDay": 0,
"resetMax": 0,
"subId": "i7tvdpeffi0hvvf1",
"total": 10737418240,
"up": 1048576,
"uuid": "e18c9a96-71bf-48d4-933f-8b9a46d4290c"
}
}
}
}
}
}
}
},
"/panel/api/clients/subLinks/{subId}": {
"get": {
"tags": [
"Clients"
],
"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.",
"operationId": "get_panel_api_clients_subLinks_subId",
"parameters": [
{
"name": "subId",
"in": "path",
"required": true,
"description": "Subscription ID, taken from the client's subId field.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
"vless://uuid@host:443?security=reality&...#user1",
"vmess://eyJ2IjoyLC..."
]
}
}
}
}
}
}
},
"/panel/api/clients/links/{email}": {
"get": {
"tags": [
"Clients"
],
"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.",
"operationId": "get_panel_api_clients_links_email",
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Client email (unique identifier).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
"vless://uuid@host:443?...#user1"
]
}
}
}
}
}
}
},
"/panel/api/nodes/list": {
"get": {
"tags": [
"Nodes"
],
"summary": "List every configured node with its connection details, health, and last heartbeat patch.",
"operationId": "get_panel_api_nodes_list",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NodeView"
}
}
}
},
"example": {
"success": true,
"obj": [
{
"activeCount": 20,
"address": "node.example.com",
"allowPrivateAddress": false,
"basePath": "/",
"clientCount": 25,
"configDirty": false,
"configDirtyAt": 0,
"cpuPct": 12.5,
"createdAt": 1700000000,
"depletedCount": 1,
"disabledCount": 2,
"enable": true,
"guid": "node-guid",
"hasApiToken": true,
"id": 1,
"inboundCount": 3,
"inboundSyncMode": "all",
"inboundTags": [
"in-443-tcp"
],
"lastError": "",
"lastHeartbeat": 1700000000,
"latencyMs": 42,
"memPct": 45.2,
"name": "edge-1",
"netDown": 1048576,
"netUp": 2097152,
"onlineCount": 5,
"outboundTag": "direct",
"panelVersion": "v3.x.x",
"parentGuid": "",
"pinnedCertSha256": "",
"port": 2053,
"remark": "Primary edge",
"scheme": "https",
"status": "online",
"tlsVerifyMode": "verify",
"transitive": false,
"updatedAt": 1700003600,
"uptimeSecs": 86400,
"xrayError": "",
"xrayState": "running",
"xrayVersion": "25.10.31"
}
]
}
}
}
}
}
}
},
"/panel/api/nodes/mtls/ca": {
"post": {
"tags": [
"Nodes"
],
"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.",
"operationId": "post_panel_api_nodes_mtls_ca",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"caCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
}
}
}
}
}
}
}
},
"/panel/api/nodes/mtls/trustCA": {
"post": {
"tags": [
"Nodes"
],
"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.",
"operationId": "post_panel_api_nodes_mtls_trustCA",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"caCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/nodes/mtls/reloadClient": {
"post": {
"tags": [
"Nodes"
],
"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.",
"operationId": "post_panel_api_nodes_mtls_reloadClient",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/nodes/get/{id}": {
"get": {
"tags": [
"Nodes"
],
"summary": "Fetch a single node by ID.",
"operationId": "get_panel_api_nodes_get_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Node ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/NodeView"
}
}
},
"example": {
"success": true,
"obj": {
"activeCount": 20,
"address": "node.example.com",
"allowPrivateAddress": false,
"basePath": "/",
"clientCount": 25,
"configDirty": false,
"configDirtyAt": 0,
"cpuPct": 12.5,
"createdAt": 1700000000,
"depletedCount": 1,
"disabledCount": 2,
"enable": true,
"guid": "node-guid",
"hasApiToken": true,
"id": 1,
"inboundCount": 3,
"inboundSyncMode": "all",
"inboundTags": [
"in-443-tcp"
],
"lastError": "",
"lastHeartbeat": 1700000000,
"latencyMs": 42,
"memPct": 45.2,
"name": "edge-1",
"netDown": 1048576,
"netUp": 2097152,
"onlineCount": 5,
"outboundTag": "direct",
"panelVersion": "v3.x.x",
"parentGuid": "",
"pinnedCertSha256": "",
"port": 2053,
"remark": "Primary edge",
"scheme": "https",
"status": "online",
"tlsVerifyMode": "verify",
"transitive": false,
"updatedAt": 1700003600,
"uptimeSecs": 86400,
"xrayError": "",
"xrayState": "running",
"xrayVersion": "25.10.31"
}
}
}
}
}
}
}
},
"/panel/api/nodes/webCert/{id}": {
"get": {
"tags": [
"Nodes"
],
"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.",
"operationId": "get_panel_api_nodes_webCert_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Node ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"webCertFile": "/root/cert/example.com/fullchain.pem",
"webKeyFile": "/root/cert/example.com/privkey.pem"
}
}
}
}
}
}
}
},
"/panel/api/nodes/add": {
"post": {
"tags": [
"Nodes"
],
"summary": "Register a new remote node. Provide its URL, write-only apiToken, and optional remark / allowPrivateAddress flag. Responses expose hasApiToken only.",
"operationId": "post_panel_api_nodes_add",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"name": "de-fra-1",
"remark": "",
"scheme": "https",
"address": "node1.example.com",
"port": 2053,
"basePath": "/",
"apiToken": "abcdef...",
"clearApiToken": false,
"enable": true,
"allowPrivateAddress": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/NodeView"
}
}
},
"example": {
"success": true,
"obj": {
"activeCount": 20,
"address": "node.example.com",
"allowPrivateAddress": false,
"basePath": "/",
"clientCount": 25,
"configDirty": false,
"configDirtyAt": 0,
"cpuPct": 12.5,
"createdAt": 1700000000,
"depletedCount": 1,
"disabledCount": 2,
"enable": true,
"guid": "node-guid",
"hasApiToken": true,
"id": 1,
"inboundCount": 3,
"inboundSyncMode": "all",
"inboundTags": [
"in-443-tcp"
],
"lastError": "",
"lastHeartbeat": 1700000000,
"latencyMs": 42,
"memPct": 45.2,
"name": "edge-1",
"netDown": 1048576,
"netUp": 2097152,
"onlineCount": 5,
"outboundTag": "direct",
"panelVersion": "v3.x.x",
"parentGuid": "",
"pinnedCertSha256": "",
"port": 2053,
"remark": "Primary edge",
"scheme": "https",
"status": "online",
"tlsVerifyMode": "verify",
"transitive": false,
"updatedAt": 1700003600,
"uptimeSecs": 86400,
"xrayError": "",
"xrayState": "running",
"xrayVersion": "25.10.31"
}
}
}
}
}
}
}
},
"/panel/api/nodes/update/{id}": {
"post": {
"tags": [
"Nodes"
],
"summary": "Replace a node’s connection details. apiToken is write-only: omit it or send an empty string to keep the stored token; set clearApiToken=true to clear it.",
"operationId": "post_panel_api_nodes_update_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Node ID.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"name": "de-fra-1",
"remark": "",
"scheme": "https",
"address": "node1.example.com",
"port": 2053,
"basePath": "/",
"apiToken": "",
"clearApiToken": false,
"enable": true,
"allowPrivateAddress": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/nodes/del/{id}": {
"post": {
"tags": [
"Nodes"
],
"summary": "Delete a node. Inbounds bound to it are not auto-migrated.",
"operationId": "post_panel_api_nodes_del_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Node ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/nodes/setEnable/{id}": {
"post": {
"tags": [
"Nodes"
],
"summary": "Pause or resume traffic sync with this node.",
"operationId": "post_panel_api_nodes_setEnable_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Node ID.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"enable": true
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/nodes/test": {
"post": {
"tags": [
"Nodes"
],
"summary": "Probe a node without saving it. Uses the body as connection details and returns the same heartbeat snapshot a registered node would have.",
"operationId": "post_panel_api_nodes_test",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"scheme": "https",
"address": "node1.example.com",
"port": 2053,
"basePath": "/",
"apiToken": "abcdef..."
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/ProbeResultUI"
}
}
},
"example": {
"success": true,
"obj": {
"cpuPct": 12.5,
"error": "",
"latencyMs": 42,
"memPct": 45.2,
"panelVersion": "v3.x.x",
"status": "online",
"uptimeSecs": 86400,
"xrayError": "",
"xrayState": "",
"xrayVersion": "25.10.31"
}
}
}
}
}
}
}
},
"/panel/api/nodes/certFingerprint": {
"post": {
"tags": [
"Nodes"
],
"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.",
"operationId": "post_panel_api_nodes_certFingerprint",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"scheme": "https",
"address": "node1.example.com",
"port": 2053,
"basePath": "/"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": "k3b1...base64-sha256...="
}
}
}
}
}
}
},
"/panel/api/nodes/inbounds": {
"post": {
"tags": [
"Nodes"
],
"summary": "Use unsaved node connection details to list the remote inbounds available for selective import.",
"operationId": "post_panel_api_nodes_inbounds",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"name": "de-fra-1",
"scheme": "https",
"address": "node1.example.com",
"port": 2053,
"basePath": "/",
"apiToken": "abcdef..."
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
{
"tag": "inbound-443",
"remark": "VLESS",
"protocol": "vless",
"port": 443
}
]
}
}
}
}
}
}
},
"/panel/api/nodes/probe/{id}": {
"post": {
"tags": [
"Nodes"
],
"summary": "Probe an existing node, updating its cached health state.",
"operationId": "post_panel_api_nodes_probe_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Node ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/nodes/updatePanel": {
"post": {
"tags": [
"Nodes"
],
"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.",
"operationId": "post_panel_api_nodes_updatePanel",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"ids": [
1,
2,
3
],
"dev": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
{
"id": 1,
"name": "de-1",
"ok": true
},
{
"id": 2,
"name": "fr-1",
"ok": false,
"error": "node is offline"
}
]
}
}
}
}
}
}
},
"/panel/api/nodes/history/{id}/{metric}/{bucket}": {
"get": {
"tags": [
"Nodes"
],
"summary": "Aggregated metric history for a node — same shape as /server/history, scoped to one node.",
"operationId": "get_panel_api_nodes_history_id_metric_bucket",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Node ID.",
"schema": {
"type": "integer"
}
},
{
"name": "metric",
"in": "path",
"required": true,
"description": "cpu | mem.",
"schema": {
"type": "string"
}
},
{
"name": "bucket",
"in": "path",
"required": true,
"description": "Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/hosts/list": {
"get": {
"tags": [
"Hosts"
],
"summary": "List every host across all inbounds, grouped by inbound then ordered by sort order.",
"operationId": "get_panel_api_hosts_list",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HostGroup"
}
}
}
},
"example": {
"success": true,
"obj": [
{
"allowInsecure": false,
"alpn": [
""
],
"echConfigList": "",
"excludeFromSubTypes": [
""
],
"finalMask": "",
"fingerprint": "",
"groupId": "",
"hostHeader": "",
"hosts": [
""
],
"inboundIds": [
0
],
"isDisabled": false,
"isHidden": false,
"keepSniBlank": false,
"mihomoIpVersion": "dual",
"mihomoX25519": false,
"muxParams": "",
"nodeGuids": [
""
],
"overrideSniFromAddress": false,
"path": "",
"pinnedPeerCertSha256": [
""
],
"port": 0,
"remark": "",
"security": "same",
"serverDescription": "",
"shuffleHost": false,
"sni": "",
"sockoptParams": "",
"sortOrder": 0,
"tags": [
""
],
"verifyPeerCertByName": "",
"vlessRoute": ""
}
]
}
}
}
}
}
}
},
"/panel/api/hosts/get/{groupId}": {
"get": {
"tags": [
"Hosts"
],
"summary": "Fetch a single host group by Group ID.",
"operationId": "get_panel_api_hosts_get_groupId",
"parameters": [
{
"name": "groupId",
"in": "path",
"required": true,
"description": "Host Group ID.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/HostGroup"
}
}
},
"example": {
"success": true,
"obj": {
"allowInsecure": false,
"alpn": [
""
],
"echConfigList": "",
"excludeFromSubTypes": [
""
],
"finalMask": "",
"fingerprint": "",
"groupId": "",
"hostHeader": "",
"hosts": [
""
],
"inboundIds": [
0
],
"isDisabled": false,
"isHidden": false,
"keepSniBlank": false,
"mihomoIpVersion": "dual",
"mihomoX25519": false,
"muxParams": "",
"nodeGuids": [
""
],
"overrideSniFromAddress": false,
"path": "",
"pinnedPeerCertSha256": [
""
],
"port": 0,
"remark": "",
"security": "same",
"serverDescription": "",
"shuffleHost": false,
"sni": "",
"sockoptParams": "",
"sortOrder": 0,
"tags": [
""
],
"verifyPeerCertByName": "",
"vlessRoute": ""
}
}
}
}
}
}
}
},
"/panel/api/hosts/byInbound/{inboundId}": {
"get": {
"tags": [
"Hosts"
],
"summary": "Fetch one inbound's hosts, grouped by host group.",
"operationId": "get_panel_api_hosts_byInbound_inboundId",
"parameters": [
{
"name": "inboundId",
"in": "path",
"required": true,
"description": "Inbound ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HostGroup"
}
}
}
},
"example": {
"success": true,
"obj": [
{
"allowInsecure": false,
"alpn": [
""
],
"echConfigList": "",
"excludeFromSubTypes": [
""
],
"finalMask": "",
"fingerprint": "",
"groupId": "",
"hostHeader": "",
"hosts": [
""
],
"inboundIds": [
0
],
"isDisabled": false,
"isHidden": false,
"keepSniBlank": false,
"mihomoIpVersion": "dual",
"mihomoX25519": false,
"muxParams": "",
"nodeGuids": [
""
],
"overrideSniFromAddress": false,
"path": "",
"pinnedPeerCertSha256": [
""
],
"port": 0,
"remark": "",
"security": "same",
"serverDescription": "",
"shuffleHost": false,
"sni": "",
"sockoptParams": "",
"sortOrder": 0,
"tags": [
""
],
"verifyPeerCertByName": "",
"vlessRoute": ""
}
]
}
}
}
}
}
}
},
"/panel/api/hosts/tags": {
"get": {
"tags": [
"Hosts"
],
"summary": "Distinct, sorted set of tags used across all hosts.",
"operationId": "get_panel_api_hosts_tags",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
"CDN",
"EU",
"FAST"
]
}
}
}
}
}
}
},
"/panel/api/hosts/add": {
"post": {
"tags": [
"Hosts"
],
"summary": "Create a host group on inbounds.",
"operationId": "post_panel_api_hosts_add",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"inboundIds": [
1
],
"remark": "cdn-front",
"hosts": [
"cdn.example.com"
],
"port": 8443,
"security": "same",
"tags": [
"CDN"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Host"
}
}
}
},
"example": {
"success": true,
"obj": [
{
"address": "cdn.example.com",
"allowInsecure": false,
"alpn": [
""
],
"createdAt": 0,
"echConfigList": "",
"excludeFromSubTypes": [
""
],
"finalMask": "",
"fingerprint": "",
"groupId": "",
"hostHeader": "",
"id": 1,
"inboundId": 1,
"isDisabled": false,
"isHidden": false,
"keepSniBlank": false,
"mihomoIpVersion": "dual",
"mihomoX25519": false,
"muxParams": null,
"nodeGuids": [
""
],
"overrideSniFromAddress": false,
"path": "",
"pinnedPeerCertSha256": [
""
],
"port": 8443,
"remark": "cdn-front",
"security": "same",
"serverDescription": "",
"shuffleHost": false,
"sni": "",
"sockoptParams": null,
"sortOrder": 0,
"tags": [
""
],
"updatedAt": 0,
"verifyPeerCertByName": "",
"vlessRoute": "443"
}
]
}
}
}
}
}
}
},
"/panel/api/hosts/update/{groupId}": {
"post": {
"tags": [
"Hosts"
],
"summary": "Replace a host group’s content.",
"operationId": "post_panel_api_hosts_update_groupId",
"parameters": [
{
"name": "groupId",
"in": "path",
"required": true,
"description": "Host Group ID.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"inboundIds": [
1
],
"remark": "cdn-front",
"hosts": [
"cdn.example.com"
],
"port": 8443,
"security": "same",
"tags": [
"CDN"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Host"
}
}
}
},
"example": {
"success": true,
"obj": [
{
"address": "cdn.example.com",
"allowInsecure": false,
"alpn": [
""
],
"createdAt": 0,
"echConfigList": "",
"excludeFromSubTypes": [
""
],
"finalMask": "",
"fingerprint": "",
"groupId": "",
"hostHeader": "",
"id": 1,
"inboundId": 1,
"isDisabled": false,
"isHidden": false,
"keepSniBlank": false,
"mihomoIpVersion": "dual",
"mihomoX25519": false,
"muxParams": null,
"nodeGuids": [
""
],
"overrideSniFromAddress": false,
"path": "",
"pinnedPeerCertSha256": [
""
],
"port": 8443,
"remark": "cdn-front",
"security": "same",
"serverDescription": "",
"shuffleHost": false,
"sni": "",
"sockoptParams": null,
"sortOrder": 0,
"tags": [
""
],
"updatedAt": 0,
"verifyPeerCertByName": "",
"vlessRoute": "443"
}
]
}
}
}
}
}
}
},
"/panel/api/hosts/del/{groupId}": {
"post": {
"tags": [
"Hosts"
],
"summary": "Delete a host group.",
"operationId": "post_panel_api_hosts_del_groupId",
"parameters": [
{
"name": "groupId",
"in": "path",
"required": true,
"description": "Host Group ID.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/hosts/setEnable/{groupId}": {
"post": {
"tags": [
"Hosts"
],
"summary": "Enable or disable a host group.",
"operationId": "post_panel_api_hosts_setEnable_groupId",
"parameters": [
{
"name": "groupId",
"in": "path",
"required": true,
"description": "Host Group ID.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"enable": true
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/hosts/reorder": {
"post": {
"tags": [
"Hosts"
],
"summary": "Set host group sort order by the position of each groupId in the array.",
"operationId": "post_panel_api_hosts_reorder",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"ids": [
"abc-123",
"def-456"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/hosts/bulk/add": {
"post": {
"tags": [
"Hosts"
],
"summary": "Add a host group to inbounds (same as /add).",
"operationId": "post_panel_api_hosts_bulk_add",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"inboundIds": [
1,
2
],
"hosts": [
"cdn.example.com",
"cdn2.example.com:443"
],
"remark": "Cloudflare CDN",
"port": 0,
"security": "same",
"isDisabled": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Host"
}
}
}
},
"example": {
"success": true,
"obj": [
{
"address": "cdn.example.com",
"allowInsecure": false,
"alpn": [
""
],
"createdAt": 0,
"echConfigList": "",
"excludeFromSubTypes": [
""
],
"finalMask": "",
"fingerprint": "",
"groupId": "",
"hostHeader": "",
"id": 1,
"inboundId": 1,
"isDisabled": false,
"isHidden": false,
"keepSniBlank": false,
"mihomoIpVersion": "dual",
"mihomoX25519": false,
"muxParams": null,
"nodeGuids": [
""
],
"overrideSniFromAddress": false,
"path": "",
"pinnedPeerCertSha256": [
""
],
"port": 8443,
"remark": "cdn-front",
"security": "same",
"serverDescription": "",
"shuffleHost": false,
"sni": "",
"sockoptParams": null,
"sortOrder": 0,
"tags": [
""
],
"updatedAt": 0,
"verifyPeerCertByName": "",
"vlessRoute": "443"
}
]
}
}
}
}
}
}
},
"/panel/api/hosts/bulk/setEnable": {
"post": {
"tags": [
"Hosts"
],
"summary": "Enable or disable many host groups in one call.",
"operationId": "post_panel_api_hosts_bulk_setEnable",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"ids": [
"abc-123",
"def-456"
],
"enable": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/hosts/bulk/del": {
"post": {
"tags": [
"Hosts"
],
"summary": "Delete many host groups in one call.",
"operationId": "post_panel_api_hosts_bulk_del",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"ids": [
"abc-123",
"def-456"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/backuptotgbot": {
"post": {
"tags": [
"Backup"
],
"summary": "Send a fresh DB backup to every Telegram chat configured as an admin recipient. No body, no params.",
"operationId": "post_panel_api_backuptotgbot",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/setting/all": {
"post": {
"tags": [
"Settings"
],
"summary": "Return every panel setting: web server, Telegram bot, subscription, security, LDAP. The full JSON blob that the Settings page edits.",
"operationId": "post_panel_api_setting_all",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/setting/defaultSettings": {
"post": {
"tags": [
"Settings"
],
"summary": "Return the computed default settings based on the request host. Useful to preview what a fresh install would use.",
"operationId": "post_panel_api_setting_defaultSettings",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/setting/factoryDefaults": {
"post": {
"tags": [
"Settings"
],
"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.",
"operationId": "post_panel_api_setting_factoryDefaults",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/setting/update": {
"post": {
"tags": [
"Settings"
],
"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.",
"operationId": "post_panel_api_setting_update",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/setting/validateRegex": {
"post": {
"tags": [
"Settings"
],
"summary": "Validate any regular expression with the backend Go RE2 compiler without saving it.",
"operationId": "post_panel_api_setting_validateRegex",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"regex": "(?m)^general-purpose$"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"msg": ""
}
}
}
}
}
}
},
"/panel/api/setting/updateUser": {
"post": {
"tags": [
"Settings"
],
"summary": "Change the panel admin username and password. Requires the current credentials for verification. The session is refreshed with the new values on success.",
"operationId": "post_panel_api_setting_updateUser",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"oldUsername": {
"type": "string",
"description": "Current admin username."
},
"oldPassword": {
"type": "string",
"description": "Current admin password."
},
"newUsername": {
"type": "string",
"description": "Desired new username."
},
"newPassword": {
"type": "string",
"description": "Desired new password."
}
},
"required": [
"oldUsername",
"oldPassword",
"newUsername",
"newPassword"
]
},
"example": {
"oldUsername": "admin",
"oldPassword": "admin",
"newUsername": "newadmin",
"newPassword": "newpass"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/setting/restartPanel": {
"post": {
"tags": [
"Settings"
],
"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.",
"operationId": "post_panel_api_setting_restartPanel",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/setting/testSmtp": {
"post": {
"tags": [
"Settings"
],
"summary": "Test SMTP connection with stage-by-stage reporting (connect, auth, send). Returns structured result with stage and message.",
"operationId": "post_panel_api_setting_testSmtp",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"stage": "send",
"msg": "Test email sent successfully"
}
}
}
}
}
}
},
"/panel/api/setting/testTgBot": {
"post": {
"tags": [
"Settings"
],
"summary": "Test Telegram bot connection by sending a test message to the configured chat.",
"operationId": "post_panel_api_setting_testTgBot",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"msg": "Test message sent to Telegram"
}
}
}
}
}
}
},
"/panel/api/setting/getDefaultJsonConfig": {
"get": {
"tags": [
"Settings"
],
"summary": "Return the built-in default Xray JSON config template that ships with this panel version.",
"operationId": "get_panel_api_setting_getDefaultJsonConfig",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/setting/apiTokens": {
"get": {
"tags": [
"API Tokens"
],
"summary": "List every API token, enabled or not. The token value is never returned — only metadata.",
"operationId": "get_panel_api_setting_apiTokens",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": [
{
"id": 1,
"name": "default",
"enabled": true,
"createdAt": 1736000000
}
]
}
}
}
}
}
}
},
"/panel/api/setting/apiTokens/create": {
"post": {
"tags": [
"API Tokens"
],
"summary": "Mint a scoped API token. The server-generated plaintext is returned only once and stored as a hash.",
"operationId": "post_panel_api_setting_apiTokens_create",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Human-readable label, e.g. \"central-panel-a\"."
},
"scope": {
"type": "string",
"description": "admin (default), monitor, or node-sync."
},
"expiresAt": {
"type": "integer",
"description": "Future Unix milliseconds, or 0 for no expiry."
}
},
"required": [
"name",
"scope",
"expiresAt"
]
},
"example": {
"name": "central-panel-a",
"scope": "node-sync",
"expiresAt": 1798761600000
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/ApiTokenView"
}
}
},
"example": {
"success": true,
"obj": {
"createdAt": 1736000000,
"enabled": true,
"expiresAt": 0,
"id": 2,
"name": "central-panel-a",
"scope": "admin",
"token": "new-token-string"
}
}
}
}
},
"400": {
"description": "Error response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
}
}
},
"example": {
"success": false,
"msg": "a token with that name already exists"
}
}
}
}
}
}
},
"/panel/api/setting/apiTokens/delete/{id}": {
"post": {
"tags": [
"API Tokens"
],
"summary": "Permanently delete a token. Any caller using it stops authenticating immediately.",
"operationId": "post_panel_api_setting_apiTokens_delete_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Token row ID.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedScope": {
"type": "string",
"description": "Stored scope expected by the operator."
}
},
"required": [
"expectedScope"
]
},
"example": {
"expectedScope": "node-sync"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true
}
}
}
}
}
}
},
"/panel/api/setting/apiTokens/setEnabled/{id}": {
"post": {
"tags": [
"API Tokens"
],
"summary": "Toggle a token enabled/disabled without deleting it. Disabled tokens are rejected by checkAPIAuth on the next request.",
"operationId": "post_panel_api_setting_apiTokens_setEnabled_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Token row ID.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "New enabled state."
},
"expectedScope": {
"type": "string",
"description": "Stored scope expected by the operator."
}
},
"required": [
"enabled",
"expectedScope"
]
},
"example": {
"enabled": false,
"expectedScope": "node-sync"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true
}
}
}
}
}
}
},
"/panel/api/xray/": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Return the Xray config template (JSON string), available inbound tags, client reverse tags, and the configured outbound test URL in one response.",
"operationId": "post_panel_api_xray",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"success": true,
"obj": {
"xraySetting": "{...raw xray config...}",
"inboundTags": "[\"in-443-tcp\"]",
"clientReverseTags": "[]",
"outboundTestUrl": "https://www.google.com/generate_204"
}
}
}
}
}
}
}
},
"/panel/api/xray/getDefaultJsonConfig": {
"get": {
"tags": [
"Xray Settings"
],
"summary": "Return the built-in default Xray config shipped with the panel (identical to /panel/api/setting/getDefaultJsonConfig).",
"operationId": "get_panel_api_xray_getDefaultJsonConfig",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/getOutboundsTraffic": {
"get": {
"tags": [
"Xray Settings"
],
"summary": "Return traffic statistics for every outbound. Each outbound shows up/down/total counters.",
"operationId": "get_panel_api_xray_getOutboundsTraffic",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/getXrayResult": {
"get": {
"tags": [
"Xray Settings"
],
"summary": "Return the most recent Xray process stdout/stderr output. Useful to check for startup errors or runtime warnings.",
"operationId": "get_panel_api_xray_getXrayResult",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/update": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Save the Xray JSON config template and optionally the outbound test URL. Both are sent as form fields.",
"operationId": "post_panel_api_xray_update",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/warp/{action}": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Manage Cloudflare Warp integration. The action parameter selects the operation.",
"operationId": "post_panel_api_xray_warp_action",
"parameters": [
{
"name": "action",
"in": "path",
"required": true,
"description": "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).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/nord/{action}": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Manage NordVPN integration. The action parameter selects the operation.",
"operationId": "post_panel_api_xray_nord_action",
"parameters": [
{
"name": "action",
"in": "path",
"required": true,
"description": "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.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/pia/{action}": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Manage PIA WireGuard integration. The action parameter selects the operation.",
"operationId": "post_panel_api_xray_pia_action",
"parameters": [
{
"name": "action",
"in": "path",
"required": true,
"description": "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.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/resetOutboundsTraffic": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Reset traffic counters for a specific outbound by tag.",
"operationId": "post_panel_api_xray_resetOutboundsTraffic",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/testOutbound": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Test an outbound configuration. Sends the outbound JSON (required), optionally all outbounds (to resolve sockopt.dialerProxy dependencies), and a mode flag.",
"operationId": "post_panel_api_xray_testOutbound",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/testOutbounds": {
"post": {
"tags": [
"Xray Settings"
],
"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.",
"operationId": "post_panel_api_xray_testOutbounds",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/balancerStatus": {
"post": {
"tags": [
"Xray Settings"
],
"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.",
"operationId": "post_panel_api_xray_balancerStatus",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/balancerOverride": {
"post": {
"tags": [
"Xray Settings"
],
"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.",
"operationId": "post_panel_api_xray_balancerOverride",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/routeTest": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Ask the running core which outbound its router would pick for a synthetic connection (RoutingService.TestRoute). No traffic is sent.",
"operationId": "post_panel_api_xray_routeTest",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/geodata/files": {
"get": {
"tags": [
"Xray Settings"
],
"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\".",
"operationId": "get_panel_api_xray_geodata_files",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/geodata/categories": {
"get": {
"tags": [
"Xray Settings"
],
"summary": "One page of a database's categories, each with its entry count and the attributes its domains carry (e.g. \"ads\", \"cn\").",
"operationId": "get_panel_api_xray_geodata_categories",
"parameters": [
{
"name": "file",
"in": "query",
"required": true,
"description": "Database file name inside the asset folder, e.g. geosite.dat (required).",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"required": false,
"description": "Case-insensitive substring filter on the category code.",
"schema": {
"type": "string"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Rows to skip. Defaults to 0.",
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Rows to return, capped at 500. Omit it to return every category — the index is small and the panel filters it client-side.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/geodata/entries": {
"get": {
"tags": [
"Xray Settings"
],
"summary": "One page of the rules inside a category — domain rules typed as domain/full/keyword/regexp for geosite databases, CIDRs for geoip ones.",
"operationId": "get_panel_api_xray_geodata_entries",
"parameters": [
{
"name": "file",
"in": "query",
"required": true,
"description": "Database file name inside the asset folder (required).",
"schema": {
"type": "string"
}
},
{
"name": "code",
"in": "query",
"required": true,
"description": "Category code, case-insensitive, e.g. google (required).",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"required": false,
"description": "Case-insensitive substring filter on the rule value.",
"schema": {
"type": "string"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Rows to skip. Defaults to 0.",
"schema": {
"type": "integer"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Rows to return, capped at 500. Defaults to the cap.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/geodata/validate": {
"post": {
"tags": [
"Xray Settings"
],
"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.",
"operationId": "post_panel_api_xray_geodata_validate",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/outbound-subs": {
"get": {
"tags": [
"Xray Settings"
],
"summary": "List all outbound subscriptions (remote URLs that supply additional outbounds), newest first.",
"operationId": "get_panel_api_xray_outbound_subs",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
},
"post": {
"tags": [
"Xray Settings"
],
"summary": "Create an outbound subscription. The URL is fetched, parsed into outbounds with stable tags, and merged additively into the running Xray config.",
"operationId": "post_panel_api_xray_outbound_subs",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/outbound-subs/{id}": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Update an existing outbound subscription by id. Accepts the same form fields as create.",
"operationId": "post_panel_api_xray_outbound_subs_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Subscription id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
},
"delete": {
"tags": [
"Xray Settings"
],
"summary": "Delete an outbound subscription by id.",
"operationId": "delete_panel_api_xray_outbound_subs_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Subscription id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/outbound-subs/{id}/del": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Delete an outbound subscription by id (POST alias of DELETE for clients that cannot send DELETE).",
"operationId": "post_panel_api_xray_outbound_subs_id_del",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Subscription id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/outbound-subs/{id}/refresh": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Force an immediate re-fetch of the subscription and return the parsed outbounds. Signals Xray to reload.",
"operationId": "post_panel_api_xray_outbound_subs_id_refresh",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Subscription id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/outbound-subs/{id}/move": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Reorder a subscription one step up or down in priority (controls its position in the merged outbounds).",
"operationId": "post_panel_api_xray_outbound_subs_id_move",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Subscription id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/xray/outbound-subs/parse": {
"post": {
"tags": [
"Xray Settings"
],
"summary": "Preview a subscription URL: fetch and parse it into outbounds without persisting anything.",
"operationId": "post_panel_api_xray_outbound_subs_parse",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/panel/api/sub-balancers": {
"get": {
"tags": [
"Subscription Balancers"
],
"summary": "List all subscription balancers in sort order (sort_order asc, id asc).",
"operationId": "get_panel_api_sub_balancers",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SubBalancer"
}
}
}
},
"example": {
"success": true,
"obj": [
{
"createdAt": 1710000000000,
"enabled": true,
"id": 1,
"inboundIds": [
1,
3
],
"remark": "auto-fastest",
"sortOrder": 1,
"strategy": "random",
"updatedAt": 1710000000000
}
]
}
}
}
}
}
},
"post": {
"tags": [
"Subscription Balancers"
],
"summary": "Create a subscription balancer. It appears in the JSON subscription of every client that sits on at least one selected inbound.",
"operationId": "post_panel_api_sub_balancers",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/SubBalancer"
}
}
},
"example": {
"success": true,
"obj": {
"createdAt": 1710000000000,
"enabled": true,
"id": 1,
"inboundIds": [
1,
3
],
"remark": "auto-fastest",
"sortOrder": 1,
"strategy": "random",
"updatedAt": 1710000000000
}
}
}
}
}
}
}
},
"/panel/api/sub-balancers/{id}": {
"post": {
"tags": [
"Subscription Balancers"
],
"summary": "Update a balancer by id. Accepts the same form fields as create (full-row update, including the enabled toggle).",
"operationId": "post_panel_api_sub_balancers_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Balancer id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/SubBalancer"
}
}
},
"example": {
"success": true,
"obj": {
"createdAt": 1710000000000,
"enabled": true,
"id": 1,
"inboundIds": [
1,
3
],
"remark": "auto-fastest",
"sortOrder": 1,
"strategy": "random",
"updatedAt": 1710000000000
}
}
}
}
}
}
},
"delete": {
"tags": [
"Subscription Balancers"
],
"summary": "Delete a balancer by id.",
"operationId": "delete_panel_api_sub_balancers_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Balancer id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/SubBalancer"
}
}
},
"example": {
"success": true,
"obj": {
"createdAt": 1710000000000,
"enabled": true,
"id": 1,
"inboundIds": [
1,
3
],
"remark": "auto-fastest",
"sortOrder": 1,
"strategy": "random",
"updatedAt": 1710000000000
}
}
}
}
}
}
}
},
"/panel/api/sub-balancers/{id}/del": {
"post": {
"tags": [
"Subscription Balancers"
],
"summary": "Delete a balancer by id (POST alias of DELETE for clients that cannot send DELETE).",
"operationId": "post_panel_api_sub_balancers_id_del",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Balancer id.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {
"$ref": "#/components/schemas/SubBalancer"
}
}
},
"example": {
"success": true,
"obj": {
"createdAt": 1710000000000,
"enabled": true,
"id": 1,
"inboundIds": [
1,
3
],
"remark": "auto-fastest",
"sortOrder": 1,
"strategy": "random",
"updatedAt": 1710000000000
}
}
}
}
}
}
}
},
"/{subPath}{subid}": {
"get": {
"tags": [
"Subscription Server"
],
"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.",
"operationId": "get_subPath_subid",
"parameters": [
{
"name": "subid",
"in": "path",
"required": true,
"description": "Client subscription ID.",
"schema": {
"type": "string"
}
},
{
"name": "format",
"in": "query",
"required": false,
"description": "Set to \"info\" to get the subscription status view-model as JSON instead of the links.",
"schema": {
"type": "string"
}
},
{
"name": "subPath",
"in": "path",
"required": true,
"description": "",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/{jsonPath}{subid}": {
"get": {
"tags": [
"Subscription Server"
],
"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.",
"operationId": "get_jsonPath_subid",
"parameters": [
{
"name": "subid",
"in": "path",
"required": true,
"description": "Client subscription ID.",
"schema": {
"type": "string"
}
},
{
"name": "jsonPath",
"in": "path",
"required": true,
"description": "",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/{clashPath}{subid}": {
"get": {
"tags": [
"Subscription Server"
],
"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.",
"operationId": "get_clashPath_subid",
"parameters": [
{
"name": "subid",
"in": "path",
"required": true,
"description": "Client subscription ID.",
"schema": {
"type": "string"
}
},
{
"name": "clashPath",
"in": "path",
"required": true,
"description": "",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"/ws": {
"get": {
"tags": [
"WebSocket"
],
"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.",
"operationId": "get_ws",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
}
}
}
}
}
}
},
"→ type: status": {
"ws": {
"tags": [
"WebSocket"
],
"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>.",
"operationId": "ws_type_status",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"type": "status",
"data": {
"cpu": 12.5,
"mem": {
"current": 2147483648,
"total": 8589934592
},
"xray": {
"state": "running"
}
}
}
}
}
}
}
}
},
"→ type: xrayState": {
"ws": {
"tags": [
"WebSocket"
],
"summary": "Xray process state change. Fired when Xray starts, stops, or encounters an error.",
"operationId": "ws_type_xrayState",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"type": "xrayState",
"data": "running"
}
}
}
}
}
}
},
"→ type: notification": {
"ws": {
"tags": [
"WebSocket"
],
"summary": "In-panel toast notification. Fired on Xray stop/restart, DB import, panel restart, etc.",
"operationId": "ws_type_notification",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"type": "notification",
"title": "Xray service restarted",
"body": "Xray has been restarted successfully",
"severity": "success"
}
}
}
}
}
}
},
"→ type: invalidate": {
"ws": {
"tags": [
"WebSocket"
],
"summary": "Instructs the UI to re-fetch a resource. Fired when another admin session modifies data (e.g. toggling inbound enable).",
"operationId": "ws_type_invalidate",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"msg": {
"type": "string"
},
"obj": {}
}
},
"example": {
"type": "invalidate",
"resource": "inbounds"
}
}
}
}
}
}
}
}
}
Reference in New Issue View Git Blame Copy Permalink