"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":{
"description":"AllSetting contains all configuration settings for the 3x-ui panel including web server, Telegram bot, and subscription settings.",
"properties":{
"datepicker":{
"description":"Date picker format",
"type":"string"
},
"expireDiff":{
"description":"Expiration warning threshold in days",
"description":"AllSettingView is the browser-safe settings read model. Secret values\nare redacted from the embedded write model and represented by presence\nflags so the UI can show configured/not configured state.",
"properties":{
"datepicker":{
"description":"Date picker format",
"type":"string"
},
"expireDiff":{
"description":"Expiration warning threshold in days",
"description":"Telegram user ID for notifications",
"type":"integer"
},
"totalGB":{
"description":"Total traffic limit in GB",
"type":"integer"
},
"updated_at":{
"description":"Last update timestamp",
"type":"integer"
}
},
"required":[
"comment",
"email",
"enable",
"expiryTime",
"limitIp",
"reset",
"security",
"subId",
"tgId",
"totalGB"
],
"type":"object"
},
"ClientInbound":{
"properties":{
"clientId":{
"type":"integer"
},
"createdAt":{
"type":"integer"
},
"flowOverride":{
"type":"string"
},
"inboundId":{
"type":"integer"
}
},
"required":[
"clientId",
"createdAt",
"flowOverride",
"inboundId"
],
"type":"object"
},
"ClientRecord":{
"properties":{
"auth":{
"type":"string"
},
"comment":{
"type":"string"
},
"createdAt":{
"type":"integer"
},
"email":{
"type":"string"
},
"enable":{
"type":"boolean"
},
"expiryTime":{
"type":"integer"
},
"flow":{
"type":"string"
},
"group":{
"type":"string"
},
"id":{
"type":"integer"
},
"limitIp":{
"type":"integer"
},
"password":{
"type":"string"
},
"reset":{
"type":"integer"
},
"reverse":{},
"security":{
"type":"string"
},
"subId":{
"type":"string"
},
"tgId":{
"type":"integer"
},
"totalGB":{
"type":"integer"
},
"updatedAt":{
"type":"integer"
},
"uuid":{
"type":"string"
}
},
"required":[
"auth",
"comment",
"createdAt",
"email",
"enable",
"expiryTime",
"flow",
"group",
"id",
"limitIp",
"password",
"reset",
"reverse",
"security",
"subId",
"tgId",
"totalGB",
"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,
"type":"integer"
},
"email":{
"example":"user1",
"type":"string"
},
"enable":{
"example":true,
"type":"boolean"
},
"expiryTime":{
"example":1735689600000,
"type":"integer"
},
"id":{
"example":14825,
"type":"integer"
},
"inboundId":{
"example":1,
"type":"integer"
},
"lastOnline":{
"example":1735680000000,
"type":"integer"
},
"reset":{
"example":0,
"type":"integer"
},
"subId":{
"example":"i7tvdpeffi0hvvf1",
"type":"string"
},
"total":{
"example":10737418240,
"type":"integer"
},
"up":{
"example":1048576,
"type":"integer"
},
"uuid":{
"example":"e18c9a96-71bf-48d4-933f-8b9a46d4290c",
"type":"string"
}
},
"required":[
"down",
"email",
"enable",
"expiryTime",
"id",
"inboundId",
"lastOnline",
"reset",
"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"
},
"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":{
"description":"Host is an override endpoint attached to an inbound: at subscription time each\nenabled host renders one share link/proxy with its own address/port/TLS/etc.,\nsuperseding the legacy externalProxy array. Free-JSON fields are stored as\ntext and parsed in the sub layer; slice fields use the json serializer.",
"properties":{
"address":{
"example":"cdn.example.com",
"type":"string"
},
"allowInsecure":{
"type":"boolean"
},
"alpn":{
"items":{
"type":"string"
},
"type":"array"
},
"createdAt":{
"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"
},
"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":{
"type":"integer"
},
"verifyPeerCertByName":{
"type":"string"
},
"vlessRoute":{
"description":"VlessRoute is a free-form port/range routing spec (e.g. \"53,443,1000-2000\");\nstored verbatim, format-validated on the frontend.",
"type":"string"
}
},
"required":[
"address",
"allowInsecure",
"alpn",
"createdAt",
"echConfigList",
"excludeFromSubTypes",
"finalMask",
"fingerprint",
"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"
},
"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"
},
"down":{
"description":"Download traffic in bytes",
"type":"integer"
},
"enable":{
"description":"Whether the inbound is enabled",
"example":true,
"type":"boolean"
},
"expiryTime":{
"description":"Expiration timestamp",
"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",
"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"
],
"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",
"type":"integer"
},
"trafficReset":{
"description":"Traffic reset schedule",
"enum":[
"never",
"hourly",
"daily",
"weekly",
"monthly"
],
"type":"string"
},
"up":{
"description":"Upload traffic in bytes",
"type":"integer"
}
},
"required":[
"clientStats",
"down",
"enable",
"expiryTime",
"id",
"lastTrafficResetTime",
"listen",
"port",
"protocol",
"remark",
"settings",
"shareAddr",
"shareAddrStrategy",
"sniffing",
"streamSettings",
"subSortIndex",
"tag",
"total",
"trafficReset",
"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":{
"id":{
"example":1,
"type":"integer"
},
"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"
},
"ssMethod":{
"type":"string"
},
"tag":{
"example":"in-443-tcp",
"type":"string"
},
"tlsFlowCapable":{
"example":true,
"type":"boolean"
}
},
"required":[
"id",
"port",
"protocol",
"remark",
"ssMethod",
"tag",
"tlsFlowCapable"
],
"type":"object"
},
"Msg":{
"description":"Msg represents a standard API response message with success status, message text, and optional data object.",
"properties":{
"msg":{
"description":"Response message text",
"type":"string"
},
"obj":{
"description":"Optional data object"
},
"success":{
"description":"Indicates if the operation was successful",
"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"
},
"apiToken":{
"example":"abcdef0123456789",
"type":"string"
},
"basePath":{
"example":"/",
"type":"string"
},
"clientCount":{
"example":27,
"type":"integer"
},
"configDirty":{
"type":"boolean"
},
"configDirtyAt":{
"type":"integer"
},
"cpuPct":{
"example":23.5,
"type":"number"
},
"createdAt":{
"example":1700000000,
"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,
"type":"integer"
},
"latencyMs":{
"example":42,
"type":"integer"
},
"memPct":{
"example":45.1,
"type":"number"
},
"name":{
"example":"de-fra-1",
"type":"string"
},
"netDown":{
"example":2097152,
"type":"integer"
},
"netUp":{
"example":1048576,
"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,
"type":"integer"
},
"uptimeSecs":{
"example":86400,
"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",
"apiToken",
"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"
},
"OutboundTraffics":{
"description":"OutboundTraffics tracks traffic statistics for Xray outbound connections.",
"properties":{
"down":{
"type":"integer"
},
"id":{
"type":"integer"
},
"tag":{
"type":"string"
},
"total":{
"type":"integer"
},
"up":{
"type":"integer"
}
},
"required":[
"down",
"id",
"tag",
"total",
"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,
"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"
},
"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"
},
"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 Bearer tokens used for programmatic auth (bots, central panels acting on this node, CI). Each token has a unique name and an enabled flag — disable to revoke without deleting, delete to revoke permanently. Tokens are stored as SHA-256 hashes and the plaintext is returned only once, in the create response — it cannot be retrieved afterwards, so copy it then. Send one as <code>Authorization: Bearer <token></code> on any /panel/api/* request — the token is a full-admin credential."
},
{
"name":"Xray Settings",
"description":"Xray configuration template, outbound management, Warp/Nord integration, and config testing. All endpoints under /panel/api/xray."
},
{
"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,
"reset":0,
"subId":"i7tvdpeffi0hvvf1",
"total":10737418240,
"up":1048576,
"uuid":"e18c9a96-71bf-48d4-933f-8b9a46d4290c"
}
],
"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",
"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":[
{
"id":1,
"nodeId":null,
"port":443,
"protocol":"vless",
"remark":"VLESS-443",
"ssMethod":"",
"tag":"in-443-tcp",
"tlsFlowCapable":true
}
]
}
}
}
}
}
}
},
"/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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"summary":"Stream the SQLite database file as an attachment. 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.",
"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.",
"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.",
"summary":"Compute the hex SHA-256 of a certificate (DER) for pinning (pinnedPeerCertSha256). Provide either a server file path or inline PEM/DER content.",
"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. 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.",
"summary":"Create a new client and attach it to one or more inbounds in a single call. Body is JSON. Per-protocol secrets (UUID for VLESS/VMess, password for Trojan/Shadowsocks, auth for Hysteria) are generated server-side when omitted, so callers can send only the universal fields.",
"operationId":"post_panel_api_clients_add",
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"type":"object"
},
"example":{
"client":{
"email":"alice@example.com",
"totalGB":53687091200,
"expiryTime":1735689600000,
"tgId":0,
"limitIp":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).",
"summary":"Replace a client's external links (per-client share links and remote subscription URLs surfaced in their subscription). Sends the full set; the server replaces all rows.",
"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.",
"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.",
"summary":"Delete every client that is not attached to any inbound, along with its traffic record, IP log, and external links. Useful for clearing clients left unattached after their inbounds were removed. Returns the deleted count. Cannot be undone.",
"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,
"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.",
"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. 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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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,
"reset":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.",
"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.",
"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/Node"
}
}
}
},
"example":{
"success":true,
"obj":[
{
"activeCount":23,
"address":"node1.example.com",
"allowPrivateAddress":false,
"apiToken":"abcdef0123456789",
"basePath":"/",
"clientCount":27,
"configDirty":false,
"configDirtyAt":0,
"cpuPct":23.5,
"createdAt":1700000000,
"depletedCount":1,
"disabledCount":3,
"enable":true,
"guid":"",
"id":1,
"inboundCount":5,
"inboundSyncMode":"all",
"inboundTags":[
""
],
"lastError":"",
"lastHeartbeat":1700000000,
"latencyMs":42,
"memPct":45.1,
"name":"de-fra-1",
"netDown":2097152,
"netUp":1048576,
"onlineCount":3,
"outboundTag":"",
"panelVersion":"v3.x.x",
"parentGuid":"",
"pinnedCertSha256":"",
"port":2053,
"remark":"",
"scheme":"https",
"status":"online",
"tlsVerifyMode":"verify",
"transitive":false,
"updatedAt":1700000000,
"uptimeSecs":86400,
"xrayError":"",
"xrayState":"",
"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.",
"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.",
"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.",
"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.",
"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.",
"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/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.",
"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.",
"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 new API token. Name must be unique and 1-64 characters; the token string is server-generated and returned only in this response — it is stored hashed and cannot be retrieved later.",
"summary":"Return the Xray config template (JSON string), available inbound tags, client reverse tags, and the configured outbound test URL in one response.",
"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/resetOutboundsTraffic":{
"post":{
"tags":[
"Xray Settings"
],
"summary":"Reset traffic counters for a specific outbound by tag.",
"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.",
"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.",
"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.",
"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/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.",
"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. Default path: /sub/:subid.",
"operationId":"get_subPath_subid",
"parameters":[
{
"name":"subid",
"in":"path",
"required":true,
"description":"Client subscription ID.",
"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).",