🌐 English | 中文 | 한국어

HY2 SCALE exposes a REST API under http://<host>:5565/scale/api/. Every endpoint except POST /api/login requires a session token obtained from login.

POST /api/login

Body:

{
  "username": "admin",
  "password": "<sha256-hex-of-plaintext>"
}

The password is SHA-256 hashed on the client before transmission; the server only ever stores and compares the hash.

Response:

{
  "token": "hex-session-token",
  "force_password_change": false
}

force_password_change: true indicates you are still on the default admin/admin credentials — the web UI will force a password change before showing any page.

Subsequent requests pass the token as a Bearer header:

Authorization: Bearer <token>

Long-lived EventSource endpoints (notably /api/graph-layout/stream) additionally accept the token as a ?token=<hex> query parameter because EventSource can't set custom headers.

Returns this node's identity and Hysteria 2 server configuration:

{
  "node_id": "ea1b2adb",
  "name": "sg-home",
  "exit_node": true,
  "hy2_user_auth": false,
  "compat": false,
  "limited": false,
  "server": {
    "listen": "0.0.0.0:5565",
    "password": "<hex>",
    "tls_cert": "/data/tls/default.crt",
    "tls_key": "/data/tls/default.key"
  },
  "version": "1.3.0"
}

Replaces the node config. Only the fields you include are modified.

{ "tx_bytes": 1234567890, "rx_bytes": 9876543210 }

Returns a flat array of top-level peers, each with a nested children tree for peers visible through nested discovery. Self is always first with direction: "local" and is_self: true.

[
  {
    "name": "ea1b2adb",
    "direction": "local",
    "latency_ms": 0,
    "is_self": true
  },
  {
    "name": "jp",
    "direction": "outbound",
    "connected": true,
    "latency_ms": 35,
    "nested": true,
    "version": "1.3.0",
    "tx_rate": 0,
    "rx_rate": 0,
    "children": [
      { "name": "jp-r1", "direction": "outbound", "latency_ms": 73 }
    ]
  }
]

Create body:

{
  "name": "jp",
  "addr": "jp.example.com:5565",
  "addrs": ["jp.example.com:5565", "jp2.example.com:5565"],
  "password": "<hy2-password>",
  "sni": "jp.example.com",
  "insecure": false,
  "ca": "",
  "max_tx": 0,
  "max_rx": 0
}

Nested body:

{ "enabled": true }

{name} may be a bare peer name (direct peer) or a /-separated path for sub-peers (us/us-east, kr/kr-r1/kr-r1-a …).

Generic proxy list (SOCKS5, HTTP, Shadowsocks):

Create body (SOCKS5 / HTTP / SS share this schema):

{
  "id": "socks5",
  "protocol": "socks5",
  "listen": "0.0.0.0:1080",
  "enabled": true,
  "tls_cert": ""
}

For Shadowsocks also include "method": "aes-256-gcm".

Each has a dedicated config endpoint pair:

PUT triggers hot reload — the service stops and restarts with the new config.

Create body:

{
  "username": "alice",
  "password": "<plaintext or hashed>",
  "exit_via": "us/us-east",
  "exit_paths": ["us/us-east"],
  "exit_mode": "direct",
  "traffic_limit_gb": 500,
  "expiry": "2026-12-31T00:00:00Z",
  "enabled": true
}

Create body:

{
  "id": "netflix",
  "name": "Netflix",
  "type": "domain",
  "targets": ["netflix.com"],
  "exit_via": "us",
  "exit_paths": ["us"],
  "exit_mode": "direct",
  "enabled": true
}

type is "ip" or "domain".

Body:

{ "enabled": true, "mode": "mixed" }

mode: "mixed" (rule-matched targets via TUN, others via proxy) or "full" (all traffic via TUN).

POST /api/tls/generate body:

{
  "id": "vpn-cert",
  "name": "vpn.sg.example",
  "domains": ["vpn.sg.example"],
  "days": 730,
  "is_ca": false
}

The Nodes-page graph stores node coordinates server-side so every logged-in session sees the same layout.

SSE events are JSON objects with the same shape as the GET response.

/api/build-info drives the License + native components panel in Settings → Upgrade.

{ "ports": [5565, 1701, 500] }

Response:

{ "results": { "5565": true, "1701": false, "500": false } }

true means the port is free on the host.

The following endpoints are used by the relay protocol itself for inter-node coordination. They do not use web-UI auth — access control is the Hysteria 2 tunnel password.

GET /api/internal/peers    — peer list for reverse nested discovery

These aren't intended for external automation — they're documented only for protocol implementers.