API Documentation
S-UI exposes two HTTP APIs:
- Frontend API (
/api) — what the panel's own UI uses. Authenticated with a login session cookie and restricted to same-origin requests, so it is not usable from an external application. - REST API with Token (
/apiv2) — for scripts and external applications. Authenticated with an API token.
This page documents /apiv2. See Frontend API at the end for the
handful of endpoints that exist only on /api.
Related: Configuration Objects describes the shape of everything you read and write here.
Base URL
Endpoints live under the panel's own path, not at the root:
http://<host>:<panel port>/<panel path>/apiv2/<endpoint>
With the default installation (port 2095, path /app/) that is
http://localhost:2095/app/apiv2/. If you changed webPort or webPath, use yours. Every
example below uses the defaults.
Authentication
Generating a token
- Open the Admin page in the panel.
- Create a new API Token.
- Set an expiration date and rotate tokens periodically.
- Copy the token — it is not shown again.
Tokens can only be created from the panel, because the endpoints that manage them live on
the session-authenticated /api group.
Using a token
Send it in the Token header on every request:
curl -H "Token: <Your Token Key>" "http://localhost:2095/app/apiv2/inbounds?id=2"
A token carries the identity of the user who created it; actions you take through it are recorded in the change log under that username.
An invalid or expired token gets:
{ "success": false, "msg": "invalid token", "obj": null }
Response structure
Every response has the same three fields:
{
"success": true, // whether the request succeeded
"msg": "", // a message, usually the action name, or the error
"obj": null // the requested data, or the result of the action
}
Note that failures still return HTTP 200 with "success": false — check the field, not
the status code. The exceptions are the two file downloads (getdb, and singbox-config on
/api), which return the file itself rather than this envelope.
A successful action:
{ "success": true, "msg": "save", "obj": { } }
A failure:
{ "success": false, "msg": "unknown object: inbound", "obj": null }
GET endpoints
| Endpoint | Description | Query parameters |
|---|---|---|
/apiv2/load |
Everything the panel needs for a full refresh | lu — last update, unix seconds |
/apiv2/inbounds |
Inbound objects | id (optional) |
/apiv2/outbounds |
Outbound objects | — |
/apiv2/endpoints |
Endpoint objects | — |
/apiv2/services |
Service objects | — |
/apiv2/tls |
TLS objects | — |
/apiv2/clients |
Client objects | id (optional) |
/apiv2/config |
The core's configuration skeleton | — |
/apiv2/users |
Panel users | — |
/apiv2/settings |
All panel settings | — |
/apiv2/stats |
Traffic statistics | resource, tag, limit, start, end |
/apiv2/status |
Server and core status | r |
/apiv2/onlines |
Currently online clients | — |
/apiv2/sessions |
Live sessions | resource, tag |
/apiv2/logs |
Core logs | c, l |
/apiv2/changes |
Change log | a, k, c |
/apiv2/keypairs |
Generate a keypair | k, o |
/apiv2/checkOutbound |
Test an outbound | tag, link |
/apiv2/getdb |
Download the database | exclude |
load
The polling endpoint. Pass the timestamp of your last poll as lu; if nothing changed
since, the response contains only onlines and maintenance, which keeps repeated polling
cheap.
curl -H "Token: <Your Token Key>" "http://localhost:2095/app/apiv2/load?lu=1757000000"
When something has changed, obj carries config, clients, tls, inbounds,
outbounds, endpoints, services, subURI, enableTraffic, onlines and os.
maintenance is always present, so a core that was stopped on purpose is never mistaken
for one that crashed. When the core is down for any other reason, lastLog carries the
last log line.
Object endpoints
Each returns its objects under a key named after the endpoint:
curl -H "Token: <Your Token Key>" "http://localhost:2095/app/apiv2/clients"
{ "success": true, "msg": "", "obj": { "clients": [ … ] } }
Only inbounds and clients accept an id to fetch a single object — the others always
return everything:
curl -H "Token: <Your Token Key>" "http://localhost:2095/app/apiv2/clients?id=7"
The shape of each object is documented in Configuration Objects.
stats
| Parameter | Meaning |
|---|---|
resource |
inbound, outbound, user, or endpoint for inbounds and outbounds together |
tag |
The specific tag or client name. Omit for all |
limit |
Rows to return. Default 100 |
start / end |
Unix seconds, inclusive range |
curl -H "Token: <Your Token Key>" \
"http://localhost:2095/app/apiv2/stats?resource=user&tag=alice&start=1756900000&limit=500"
Statistics are bucketed by statsBucketSeconds (60 by default) and kept for trafficAge
days. Both are in Settings.
status
Pass the parts you want as a comma-separated list in r — fetching only what you need
keeps the call cheap:
| Option | Returns |
|---|---|
cpu |
CPU usage |
mem |
RAM usage |
swp |
Swap usage |
dsk |
Disk usage |
dio |
Disk I/O statistics |
net |
Network statistics |
sys |
System information: uptime, load, panel version |
sbd |
Core state: running, plus stats with Uptime, Alloc and NumGoroutine |
db |
Database size and row counts |
curl -H "Token: <Your Token Key>" \
"http://localhost:2095/app/apiv2/status?r=cpu,mem,net,sys,sbd"
The sbd object also carries a maintenance flag, so a core stopped on purpose can be
told apart from one that crashed.
sessions
The connections the core is serving right now, one entry per session.
| Parameter | Meaning |
|---|---|
resource |
What tag refers to: user (default), inbound, outbound, or endpoint for either side |
tag |
The client name or tag to filter by. Omit for every session |
curl -H "Token: <Your Token Key>" \
"http://localhost:2095/app/apiv2/sessions?resource=user&tag=alice"
Each session carries id, user, inbound, outbound, network, source,
destination, domain, rule, createdAt and the bytes moved so far as up and down.
Sessions live in the running core, so this returns an empty list when the core is stopped rather than an error — a panel in maintenance mode is simply serving nobody.
logs
| Parameter | Meaning |
|---|---|
c |
Number of lines |
l |
Minimum level: debug, info, warning, error |
curl -H "Token: <Your Token Key>" "http://localhost:2095/app/apiv2/logs?c=50&l=warning"
changes
The audit log: who changed what, and when. Every save appends an entry.
| Parameter | Meaning |
|---|---|
a |
Actor — the username that made the change |
k |
Key — the object type, e.g. clients |
c |
Number of entries |
curl -H "Token: <Your Token Key>" "http://localhost:2095/app/apiv2/changes?k=clients&c=20"
Each entry has dateTime, actor, key, action and the submitted obj.
keypairs
Generates key material so you do not have to run sing-box generate yourself.
| Parameter | Meaning |
|---|---|
k |
ech, tls, reality or wireguard |
o |
Type-specific options |
curl -H "Token: <Your Token Key>" "http://localhost:2095/app/apiv2/keypairs?k=reality"
checkOutbound
Runs the core's own URL test against one outbound:
curl -H "Token: <Your Token Key>" \
"http://localhost:2095/app/apiv2/checkOutbound?tag=proxy-out"
{ "success": true, "msg": "", "obj": { "OK": true, "Delay": 184, "Error": "" } }
Delay is in milliseconds and only meaningful when OK is true; otherwise Error says
why. tag is required, link overrides the test URL, and the core must be running.
getdb
Downloads the SQLite database as a file — this is the backup endpoint.
curl -H "Token: <Your Token Key>" -OJ \
"http://localhost:2095/app/apiv2/getdb?exclude=stats,changes"
exclude is a comma-separated list of tables to leave out. The tables are settings,
tls, inbounds, outbounds, services, endpoints, users, tokens, stats,
clients and changes. Excluding stats and changes usually shrinks the file
dramatically without losing any configuration.
POST endpoints
| Endpoint | Description | Parameters |
|---|---|---|
/apiv2/save |
Create, update or delete an object | object, action, data, initUsers |
/apiv2/restartApp |
Restart the panel | — |
/apiv2/restartSb |
Restart the core | — |
/apiv2/maintenance |
Stop the core and hold it stopped, or start it again | enable |
/apiv2/resetTraffic |
Reset every client's traffic | — |
/apiv2/closeSessions |
Disconnect one client | u |
/apiv2/linkConvert |
Convert a share link into an outbound | link |
/apiv2/subConvert |
Fetch a subscription and return its links | link |
/apiv2/importdb |
Import a database file | db (file) |
/apiv2/getCertPing |
Read a remote server's certificate fingerprint | domain, port |
save
The single write endpoint for every object.
| Field | Value |
|---|---|
object |
clients, tls, inbounds, outbounds, endpoints, services, config or settings |
action |
new, edit or del (settings ignores this; the panel sends set) |
data |
The object as JSON. For del, the id is enough |
initUsers |
Optional, inbounds only: client ids to attach to a newly created inbound |
The response returns the affected objects in the same shape as the matching GET
endpoint, so you can use it to confirm what was written.
Create a client:
curl -X POST -H "Token: <Your Token Key>" \
-d "object=clients" -d "action=new" \
-d 'data={"enable":true,"name":"alice","remark":"Alice","inbounds":[1,2],"volume":107374182400,"expiry":0,"config":{"vless":{"name":"alice","uuid":"b831381d-6324-4d53-ad4f-8cda48b30811"}}}' \
"http://localhost:2095/app/apiv2/save"
Disable a client (send the full object with the field changed):
curl -X POST -H "Token: <Your Token Key>" \
-d "object=clients" -d "action=edit" \
-d 'data={"id":7,"enable":false,"name":"alice", … }' \
"http://localhost:2095/app/apiv2/save"
Delete one:
curl -X POST -H "Token: <Your Token Key>" \
-d "object=clients" -d "action=del" -d 'data={"id":7}' \
"http://localhost:2095/app/apiv2/save"
Writes run in a transaction: if anything fails the whole save is rolled back. Saving something the core depends on restarts it in the background after the change is committed, so a rollback never leaves the core running a configuration that was not saved.
maintenance
A watchdog restarts the core a few seconds after it stops, so stopping it by hand does not hold. This is the supported way to keep it down — for a certificate renewal or a migration:
curl -X POST -H "Token: <Your Token Key>" -d "enable=true" \
"http://localhost:2095/app/apiv2/maintenance"
curl -X POST -H "Token: <Your Token Key>" -d "enable=false" \
"http://localhost:2095/app/apiv2/maintenance"
enable is required and must parse as a boolean (true/false, 1/0). The state is
reported by load and by status?r=sbd.
restartApp and restartSb
restartApp restarts the panel process itself. The panel is unreachable for a moment
afterwards, and the response to this call may be lost as the process goes down — treat a
dropped connection here as success and retry your next call after a few seconds.
restartSb restarts only the sing-box core and leaves the panel up, so it answers
normally.
closeSessions
Disconnects a client, cutting its sessions across every inbound that has them:
curl -X POST -H "Token: <Your Token Key>" -d "u=alice" \
"http://localhost:2095/app/apiv2/closeSessions"
Nothing is blocked afterwards — the client may connect again straight away. To keep it out,
disable the client with save instead.
resetTraffic
Zeroes every client's up and down and restarts the core. Lifetime totalUp and
totalDown are not affected. For a scheduled version, set globalReset in
Settings.
linkConvert and subConvert
linkConvert turns one share link into the outbound JSON the panel stores. subConvert
fetches a subscription URL and returns the links it contains. Both are what the panel uses
when you paste a link into a client's external links.
curl -X POST -H "Token: <Your Token Key>" \
--data-urlencode "link=vless://…" \
"http://localhost:2095/app/apiv2/linkConvert"
importdb
Restores a database file produced by getdb. Send it as multipart form data in a field
named db:
curl -X POST -H "Token: <Your Token Key>" \
-F "db=@s-ui_20260912-120000.db" \
"http://localhost:2095/app/apiv2/importdb"
This replaces the current database. Take a backup with getdb first.
getCertPing
Connects to a remote server and reports its TLS certificate fingerprint — useful when setting up a node that pins one:
curl -X POST -H "Token: <Your Token Key>" \
-d "domain=example.com" -d "port=443" \
"http://localhost:2095/app/apiv2/getCertPing"
Frontend API (/api)
The /api group serves the panel itself. It exposes everything /apiv2 does, but
authenticates with a login session cookie and is restricted to same-origin requests — so it
is not usable from an external application. It additionally carries the endpoints that
manage the session and the tokens themselves:
| Endpoint | Description |
|---|---|
POST /api/login |
Start a session |
GET /api/logout |
End the session |
POST /api/changePass |
Change the current user's credentials |
GET /api/tokens |
List API tokens |
POST /api/addToken |
Create an API token |
POST /api/deleteToken |
Revoke an API token |
GET /api/singbox-config |
Download the core's generated sing-box configuration |
Creating and revoking tokens takes effect immediately — the running /apiv2 handler
reloads its token list on every change.
Recipes
Back up nightly
curl -sf -H "Token: $SUI_TOKEN" \
"http://localhost:2095/app/apiv2/getdb?exclude=stats,changes" \
-o "/backups/s-ui-$(date +%F).db"
Find clients that are out of traffic
curl -s -H "Token: $SUI_TOKEN" "http://localhost:2095/app/apiv2/clients" \
| jq '.obj.clients[] | select(.volume > 0 and (.up + .down) >= .volume) | .name'
Alert when the core is down and it is not intentional
curl -s -H "Token: $SUI_TOKEN" "http://localhost:2095/app/apiv2/status?r=sbd" \
| jq -e '.obj.sbd.running or .obj.sbd.maintenance' >/dev/null \
|| echo "core is down and maintenance mode is off"