Drive the whole panel from your own code.
Everything you click in Umiji, a program can do over HTTPS: users, nodes, hosts, squads, templates, billing and stats. Here is how to sign requests, what comes back, the webhooks the panel sends, and every endpoint with its fields.
- 239 endpoints
- 29 groups
- 279 error codes
- JSON over HTTPS
- Version 3.4.7
How it works
The panel you open in the browser is itself a client of this API. Your scripts, bots and billing systems talk to the same endpoints, with a token instead of a sign-in.
- Every endpoint lives under
/apion your panel’s address. - A program proves who it is with an API token, sent as
Authorization: Bearer …. Each token carries scopes that limit what it may call. - Requests and answers are JSON. A successful answer is wrapped in
{"response": …}. - The panel also calls you: webhooks for user, node and billing events, and optional Redis streams for traffic.
Base URL
The address you open the panel at, plus /api. Type yours in Your panel at the top, and every example on this page uses it.
https://panel.example.com/api
HTTPS through a reverse proxy is required. The API closes the connection, without any answer, on a request that doesn’t carry X-Forwarded-For and X-Forwarded-Proto: https. Your reverse proxy (Caddy, Nginx) adds both, so calls to the public address just work. curl shows this as “Empty reply from server”.
A script on the panel’s own server can skip the proxy and call port 3000 directly, if it sends both headers itself:
curl "http://127.0.0.1:3000/api/system/stats" \
-H "Authorization: Bearer $UMIJI_TOKEN" \
-H "X-Forwarded-For: 127.0.0.1" \
-H "X-Forwarded-Proto: https"
Call the API from a server, not from a web page. Browsers only get answers on the panel’s own domain, and a token in front-end code is a token anyone can read.
API tokens
A token is a long key that stands for one program. Make a separate one for each bot or script, so you can remove one without breaking the others.
- Open Umiji Settings and find the API tokens card. Press Create API token.
- Fill in Token name and Expires in (days), then pick the scopes: a preset, or single endpoints.
- Copy the token. It is shown only once, right after you create it.
- Send it with every request, in the
Authorizationheader.
# keep it out of your code, in an environment variable
export UMIJI_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
curl "https://panel.example.com/api/system/stats" \
-H "Authorization: Bearer $UMIJI_TOKEN"
- Deleting a token stops it at once. The panel checks the token on every request, so a deleted token gets 403 on its very next call.
- An expired token gets 401. Make a new one; tokens can’t be extended.
- Creating and deleting tokens is for the owner, from the panel. A token can’t list, create or delete tokens, and each change sends the
service.api_token_createdorservice.api_token_deletedwebhook.
Your own sign-in doesn’t work for scripts. The owner’s session is accepted only from the panel in a browser. Used anywhere else, it gets 403 with For API requests you must create own API-token in the admin dashboard. Brokers can’t make tokens, and their sessions also work only in the browser.
Scopes
Scopes say what a token may call. They come in four sizes, from everything down to one endpoint. A token passes if any one of its scopes covers the endpoint.
*Everything an API token can reach. The Full access switch.users:*Every endpoint of one resource, here users.users:readAll reading endpoints of a resource.users:writeis all the changing ones.users:createOne endpoint. Each endpoint in the reference shows its own scope; click it to copy.
The create dialog has three presets: Read only (every reading endpoint), full access, and Subpage, the five scopes the subscription page server needs. You can also paste a JSON array of scopes from the clipboard. The full list of scopes, grouped by resource, comes from GET /api/tokens/scopes.
["subscription-page-configs:list", "subscription-page-configs:get",
"subscriptions:subpage-config", "system:metadata", "users:by-username"]
A call outside the token’s scopes gets 403 with Forbidden resource. Give each token the smallest set it needs: a sign-up bot needs users:create and users:by-username, not *.
Who can call what
Most endpoints work with a token. A few belong to the panel’s own screens and refuse tokens. Each endpoint in the reference is tagged, so you know before you try.
| Endpoints | API token | Owner in panel | Broker in panel |
|---|---|---|---|
| Users, nodes, hosts, squads, templates, stats and the rest (165) | ✓ | ✓ | – |
| Users and squads a broker works with (28) | ✓ | ✓ | ✓ own only |
| Brokers, broadcasts, Umiji Settings, passkeys, API tokens (19) | – | ✓ | – |
| A broker’s own store bot (17) | – | – | ✓ |
| Sign-in, and the public subscription links (10) | No token needed | ||
A token always acts as the owner, so it sees every user. To work for a single broker, filter by the user’s brokerUuid.
First requests
List the first ten users, then create one with 50 GiB a month for 30 days. The same two calls in three languages:
# the first ten users
curl "https://panel.example.com/api/users?start=0&size=10" \
-H "Authorization: Bearer $UMIJI_TOKEN"
# a new user: 50 GiB a month, for 30 days, in one internal squad
curl -X POST "https://panel.example.com/api/users" \
-H "Authorization: Bearer $UMIJI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"username": "alice",
"expireAt": "2026-12-15T00:00:00.000Z",
"trafficLimitBytes": 53687091200,
"trafficLimitStrategy": "MONTH",
"activeInternalSquads": ["7f3c2a1e-5b4d-4c6e-9f8a-1b2c3d4e5f60"]
}'
// Node.js 18 or newer: fetch is built in
const BASE = 'https://panel.example.com/api'
const headers = {
Authorization: `Bearer ${process.env.UMIJI_TOKEN}`,
'Content-Type': 'application/json',
}
async function umiji(method, path, body) {
const res = await fetch(BASE + path, { method, headers, body: body && JSON.stringify(body) })
if (res.status === 202 || res.status === 204) return null
const json = await res.json()
if (!res.ok) throw new Error(`${json.errorCode ?? res.status}: ${json.message}`)
return json.response
}
const { users, total } = await umiji('GET', '/users?start=0&size=10')
const alice = await umiji('POST', '/users', {
username: 'alice',
expireAt: new Date(Date.now() + 30 * 864e5).toISOString(),
trafficLimitBytes: 50 * 1024 ** 3,
trafficLimitStrategy: 'MONTH',
})
console.log(alice.subscriptionUrl)
import os, datetime, requests
BASE = "https://panel.example.com/api"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['UMIJI_TOKEN']}"
def umiji(method, path, **kw):
r = s.request(method, BASE + path, timeout=30, **kw)
if r.status_code in (202, 204):
return None
data = r.json()
if not r.ok:
raise RuntimeError(f"{data.get('errorCode', r.status_code)}: {data['message']}")
return data["response"]
page = umiji("GET", "/users", params={"start": 0, "size": 10})
alice = umiji("POST", "/users", json={
"username": "alice",
"expireAt": (datetime.datetime.now(datetime.UTC) + datetime.timedelta(days=30)).isoformat(),
"trafficLimitBytes": 50 * 1024**3,
"trafficLimitStrategy": "MONTH",
})
print(alice["subscriptionUrl"])
The new user comes back whole, with its id and subscriptionUrl: the link you hand to the customer. Leave out activeInternalSquads and the user gets no servers until you add them to a squad.
Requests and responses
- Send bodies as JSON with
Content-Type: application/json. Fields the API doesn’t know are dropped, not refused. - The thing to act on goes in the path (
/api/nodes/{uuid}), except for updates:PATCHtakes the whole change in the body, with itsuuidoridinside.PATCH /api/userstakes eitheridorusername. - A
PATCHchanges only the fields you send. - Actions that aren’t plain edits sit under
/actions/:POST /api/users/{userId}/actions/reset-traffic,…/actions/disable,…/actions/restart.
| Status | Means | Body |
|---|---|---|
200 OK | Done. | {"response": …} |
201 Created | A new object was made. | {"response": …}, the new object |
202 Accepted | Queued: bulk changes to users and squads, node restarts, plugin and snippet syncs, dropped connections. The work runs in the background and takes a moment. | None |
204 No Content | Deleted. | None |
Live connection lookups work like a ticket: POST /api/connections/by-user/{userId} answers with a jobId at once, then GET /api/connections/by-user/{jobId} returns the result once the nodes have replied. Ask again every second or two until isCompleted is true.
Errors
An error comes back in one of three shapes. Check the status first, then errorCode when there is one: the codes stay the same between versions, the messages may not.
The panel refused it
{
"timestamp": "2026-11-15T07:11:48.106Z",
"path": "/api/users",
"message": "User username already exists",
"errorCode": "A019"
}
The body didn’t pass validation (400)
{
"statusCode": 400,
"message": "Validation failed",
"errors": [
{ "code": "too_small", "minimum": 3, "path": ["username"], "message": "Username must be at least 3 characters" },
{ "code": "invalid_type", "expected": "string", "path": ["expireAt"], "message": "Invalid input: expected string, received undefined" }
]
}
The token was refused (401, 403)
{ "message": "Unauthorized", "statusCode": 401 }
{ "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403 }
| Status | Usually means |
|---|---|
400 | Validation failed, or a panel rule said no; the errorCode tells which. |
401 | No token, a broken token, or an expired one. |
403 | The token lacks the scope, was deleted, or the endpoint is panel-only. |
404 | No such user, node, host… (for example A063). |
409 | A name or tag is already taken. |
429 | Too many sign-in attempts (A286). The API has no other rate limit, but be gentle. |
500 | The panel couldn’t finish the job: the database or a node failed. The errorCode names the step. |
Every code with its message is in Error codes, and the search at the top finds them too.
Pagination
Lists that can grow large come in pages. There are two kinds.
Offset: start and size
GET /api/users, /api/subscriptions, /api/hwid/devices and the request history take start (where to begin, from 0) and size (up to 1000; up to 500 for subscriptions). The answer has total, so you know how many pages there are. Good for a table with page numbers.
Cursor: GET /api/users/stream
For going through every user, for a sync or an export. Each page has nextCursor and hasMore: pass the cursor back until hasMore is false. It stays fast on large panels and filters by status, tag, telegramId, email, trafficLimitStrategy and externalSquadUuid.
let cursor
do {
const q = new URLSearchParams({ size: '1000', status: 'ACTIVE', ...(cursor && { cursor }) })
const page = await umiji('GET', `/users/stream?${q}`)
for (const user of page.users) save(user)
cursor = page.hasMore ? page.nextCursor : undefined
} while (cursor)
The table parameters (filters, filterModes, globalFilterMode, sorting) are made for the panel’s own tables and search with slow text matching. For automation, use the cursor list or the direct lookups: /api/users/by-username/{username}, /by-short-uuid/{shortUuid} and /api/users/{userId}.
Dates, bytes and IDs
| What | How it looks |
|---|---|
| Dates | ISO 8601 in UTC, like 2026-11-15T12:00:00.000Z. Send them the same way; an offset such as +03:30 also works. |
| Traffic | Bytes, as numbers. 1 GiB is 1073741824. A traffic limit of 0 means unlimited. |
| Users | A number, id, in paths such as /api/users/{userId}. Also found by username, by shortUuid (the ID inside the subscription link), by telegramId and by email. |
| Everything else | A uuid: nodes, hosts, squads, profiles, templates, brokers. |
| User status | ACTIVE, DISABLED, LIMITED (out of traffic), EXPIRED. You set only the first two; the panel sets the others. |
| Traffic reset | NO_RESET, DAY (every night), WEEK (Mondays), MONTH (on the 1st), MONTH_ROLLING (each month on the day the user was created). Times are UTC. |
Webhooks
Instead of asking the panel every minute whether a user ran out of traffic, let it tell you. With webhooks on, the panel sends a signed POST to your address the moment something happens.
Turn them on in the panel’s .env, then restart the panel:
WEBHOOK_ENABLED=true
# one address, or several separated by commas; http:// or https://
WEBHOOK_URL=https://bot.example.com/umiji-hook
# the signing key: at least 32 letters and digits, nothing else
WEBHOOK_SECRET_HEADER=vsmu67Kmg6R8FjIOF1WUY8LWBHie4scdEqrfsKmyf4IAf8dY3nFS0wwYHkhh6ZvQ
Every event goes out by default. To mute some, or send one event to an extra address, edit notifications-config.yml (in /var/lib/umiji/configs/notifications/ in the container):
events:
user.modified:
telegram: false
webhook: false
user.expired:
telegram: true
webhook: true
additionalWebhookUrls:
- https://crm.example.com/hooks/expired
What arrives
| Header | Value |
|---|---|
Content-Type | application/json |
X-Umiji-Signature | HMAC-SHA256 of the raw body with your secret, in hex. |
X-Umiji-Timestamp | When the event happened, ISO 8601; the same as timestamp in the body. |
User-Agent | Umiji |
{
"scope": "user",
"event": "user.expired",
"timestamp": "2026-11-15T12:00:00.000Z",
"data": { "id": 74, "username": "alice", "status": "EXPIRED", "subscriptionUrl": "https://sub.example.com/JRAT-hTGXSqu0xLM" },
"meta": null
}
For user events, data is the whole user, the same object GET /api/users/{userId} returns. Answer with any 2xx status. If your server doesn’t, the panel tries three more times, five seconds apart.
Check the signature
Anyone can post to your address. Before you trust a webhook, sign the raw body, byte for byte, with your secret and compare it with X-Umiji-Signature. Don’t parse and re-encode the JSON first: the bytes would change.
import crypto from 'node:crypto'
import express from 'express'
const app = express()
// express.raw keeps the body as bytes, exactly as the panel signed it
app.post('/umiji-hook', express.raw({ type: 'application/json' }), (req, res) => {
const expected = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET).update(req.body).digest()
const given = Buffer.from(req.get('X-Umiji-Signature') ?? '', 'hex')
if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
return res.sendStatus(401)
}
const { event, data } = JSON.parse(req.body)
if (event === 'user.expired') remindToRenew(data.username)
res.sendStatus(200)
})
app.listen(8080)
import hashlib, hmac, json, os
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"].encode()
@app.post("/umiji-hook")
def hook():
body = request.get_data() # the raw bytes
expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Umiji-Signature", "")):
abort(401)
event = json.loads(body)
if event["event"] == "user.expired":
remind_to_renew(event["data"]["username"])
return "", 200
<?php
$body = file_get_contents('php://input'); // the raw bytes
$expected = hash_hmac('sha256', $body, getenv('WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_UMIJI_SIGNATURE'] ?? '')) {
http_response_code(401);
exit;
}
$event = json_decode($body, true);
if ($event['event'] === 'user.expired') {
remind_to_renew($event['data']['username']);
}
http_response_code(200);
To refuse replays, also drop webhooks whose X-Umiji-Timestamp is more than a few minutes old.
Events
Each event has a scope, which decides what is in data.
| Event | When |
|---|---|
user.created | A user was made. |
user.modified | A user was changed. |
user.deleted | A user was deleted. |
user.revoked | The user’s subscription link was replaced with a new one. |
user.disabled, user.enabled | Switched off or back on. |
user.limited | Out of traffic. |
user.expired | The expiry date passed. |
user.traffic_reset | Traffic was reset, by hand or on schedule. |
user.first_connected | The user connected for the first time. |
user.bandwidth_usage_threshold_reached | Crossed a share of the limit, such as 80%. Needs BANDWIDTH_USAGE_NOTIFICATIONS_ENABLED. |
user.not_connected | Hasn’t connected for some hours after creation; meta.notConnectedAfterHours says how many. Needs NOT_CONNECTED_USERS_NOTIFICATIONS_ENABLED. |
user.expiration | Expires soon, or expired a while ago; meta.expiration is the hours (negative before expiry). Needs EXPIRATION_NOTIFICATIONS_ENABLED. |
user_hwid_devices.added, .deleted | A device was added or removed. data has user and hwidUserDevice. |
node.created, .modified, .deleted | A node was made, changed or deleted. |
node.enabled, .disabled | A node was switched on or off. |
node.connection_lost, .connection_restored | The panel lost a node, or got it back. |
node.traffic_notify | A node reached its traffic alert. |
service.panel_started | The panel started; data.panelVersion. |
service.login_attempt_success, _failed | Someone signed in to the panel, or tried; data.loginAttempt has the username, IP and browser. |
service.subpage_config_changed | A subscription page config was made, changed or deleted. |
service.api_token_created, _deleted | An API token was made or deleted; data.apiToken. |
crm.infra_billing_node_payment_in_7_days | A server bill is due in 7 days. Also _in_48hrs, _in_24hrs, _due_today, and when it’s late: _overdue_24hrs, _overdue_48hrs, _overdue_7_days. |
torrent_blocker.report | Torrent Blocker caught a user; data has the node, the user and the report. |
errors.bandwidth_usage_threshold_reached_max_notifications | Listed in the config for completeness; this version never sends it. |
Every field, by scope
Redis export streams
For analytics at scale, the panel can also write raw data into Redis Streams, for a worker of your own, ClickHouse or Vector to read. Turn it on with EXPORT_TO_STREAM_ENABLED=true. EXPORT_TO_STREAM_MAXLEN (3000 by default) is about how many messages each stream keeps before the oldest go.
| Stream | One message is |
|---|---|
ioraw:export:user_usage | One node’s batch of user traffic: records is userId:bytes pairs joined by ;. |
ioraw:export:subscription_requests | One subscription fetch: user, time, IP, app and the response rule that answered. |
ioraw:export:node_connections | Who is on one node right now. Kept for an hour. |
# read new messages as they come, with a consumer group
redis-cli XGROUP CREATE ioraw:export:user_usage billing $ MKSTREAM
redis-cli XREADGROUP GROUP billing worker-1 COUNT 100 BLOCK 5000 STREAMS ioraw:export:user_usage >
Subscription links
The links client apps import aren’t under the token: the short ID in the link is the key. They are served from the subscription address in SUB_PUBLIC_DOMAIN, which the Docker install sets to its SUB_DOMAIN, the sub page's domain.
| Address | Gives |
|---|---|
/api/sub/{shortUuid} | What the app imports. The response rules pick the format from the app’s User-Agent: Base64 links, Xray JSON, Mihomo, sing-box and so on. |
/api/sub/{shortUuid}/{clientType} | A format you name: json, v2ray-json, mihomo, stash, clash or singbox. |
/api/sub/{shortUuid}/info | JSON for your own pages: the user, their connection links and the subscription URL. |
For bots, the token-protected Subscriptions group gives the same data by username or ID, with nothing to parse.
Metrics and health
The scheduler process answers on METRICS_PORT (3001), bound to 127.0.0.1 on the panel’s server, with two endpoints outside /api:
# Prometheus metrics, with the METRICS_USER and METRICS_PASS from .env
curl -u "$METRICS_USER:$METRICS_PASS" http://127.0.0.1:3001/metrics
# is the database reachable? Docker's health check uses this one
curl http://127.0.0.1:3001/health
# prometheus.yml
scrape_configs:
- job_name: umiji
static_configs:
- targets: ['127.0.0.1:3001']
basic_auth:
username: admin
password: your-METRICS_PASS
From the API itself, GET /api/system/health and /api/system/stats give the same picture as JSON.
Scalar and Swagger
Your panel carries its own live API explorers, generated from the code it runs. Open Umiji Settings › Backend tools and press Login next to Scalar (a modern, interactive reference) or Swagger (the classic OpenAPI explorer). The login is a one-time link that lasts two hours.
Both can send real requests with a token, and Scalar has a button to download the OpenAPI document. Feed that to a generator such as openapi-generator to get a typed client in your language.
Error codes
All 279 codes the panel can send in errorCode, with their HTTP status.
| Code | HTTP | Message |
|---|
Every endpoint
Grouped the way the panel’s menu is. Open an endpoint for its access, parameters, body and response fields, a request to copy and an example answer.
- GET read
- POST create or act
- PATCH change
- PUT replace
- DELETE remove
A few routes are left out on purpose: the node installer, SSH terminal tickets, the Backend tools login and the Telegram webhook of broker bots. Only the panel’s own screens and Telegram call them.