12 API Documentation
Alireza Ahmadi edited this page 2026-09-16 19:50:12 +02:00

API Documentation

S-UI exposes two HTTP APIs:

  1. 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.
  2. 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

  1. Open the Admin page in the panel.
  2. Create a new API Token.
  3. Set an expiration date and rotate tokens periodically.
  4. 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"