Umiji

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
Getting started

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 /api on 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.

  1. Open Umiji Settings and find the API tokens card. Press Create API token.
  2. Fill in Token name and Expires in (days), then pick the scopes: a preset, or single endpoints.
  3. Copy the token. It is shown only once, right after you create it.
  4. Send it with every request, in the Authorization header.
# 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_created or service.api_token_deleted webhook.

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.

  1. *Everything an API token can reach. The Full access switch.
  2. users:*Every endpoint of one resource, here users.
  3. users:readAll reading endpoints of a resource. users:write is all the changing ones.
  4. 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.

EndpointsAPI tokenOwner in panelBroker 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.

Conventions

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: PATCH takes the whole change in the body, with its uuid or id inside. PATCH /api/users takes either id or username.
  • A PATCH changes 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.
StatusMeansBody
200 OKDone.{"response": …}
201 CreatedA new object was made.{"response": …}, the new object
202 AcceptedQueued: 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 ContentDeleted.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 }
StatusUsually means
400Validation failed, or a panel rule said no; the errorCode tells which.
401No token, a broken token, or an expired one.
403The token lacks the scope, was deleted, or the endpoint is panel-only.
404No such user, node, host… (for example A063).
409A name or tag is already taken.
429Too many sign-in attempts (A286). The API has no other rate limit, but be gentle.
500The 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

WhatHow it looks
DatesISO 8601 in UTC, like 2026-11-15T12:00:00.000Z. Send them the same way; an offset such as +03:30 also works.
TrafficBytes, as numbers. 1 GiB is 1073741824. A traffic limit of 0 means unlimited.
UsersA 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 elseA uuid: nodes, hosts, squads, profiles, templates, brokers.
User statusACTIVE, DISABLED, LIMITED (out of traffic), EXPIRED. You set only the first two; the panel sets the others.
Traffic resetNO_RESET, DAY (every night), WEEK (Mondays), MONTH (on the 1st), MONTH_ROLLING (each month on the day the user was created). Times are UTC.
The panel calls you

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

HeaderValue
Content-Typeapplication/json
X-Umiji-SignatureHMAC-SHA256 of the raw body with your secret, in hex.
X-Umiji-TimestampWhen the event happened, ISO 8601; the same as timestamp in the body.
User-AgentUmiji
{
  "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.

EventWhen
user.createdA user was made.
user.modifiedA user was changed.
user.deletedA user was deleted.
user.revokedThe user’s subscription link was replaced with a new one.
user.disabled, user.enabledSwitched off or back on.
user.limitedOut of traffic.
user.expiredThe expiry date passed.
user.traffic_resetTraffic was reset, by hand or on schedule.
user.first_connectedThe user connected for the first time.
user.bandwidth_usage_threshold_reachedCrossed a share of the limit, such as 80%. Needs BANDWIDTH_USAGE_NOTIFICATIONS_ENABLED.
user.not_connectedHasn’t connected for some hours after creation; meta.notConnectedAfterHours says how many. Needs NOT_CONNECTED_USERS_NOTIFICATIONS_ENABLED.
user.expirationExpires soon, or expired a while ago; meta.expiration is the hours (negative before expiry). Needs EXPIRATION_NOTIFICATIONS_ENABLED.
user_hwid_devices.added, .deletedA device was added or removed. data has user and hwidUserDevice.
node.created, .modified, .deletedA node was made, changed or deleted.
node.enabled, .disabledA node was switched on or off.
node.connection_lost, .connection_restoredThe panel lost a node, or got it back.
node.traffic_notifyA node reached its traffic alert.
service.panel_startedThe panel started; data.panelVersion.
service.login_attempt_success, _failedSomeone signed in to the panel, or tried; data.loginAttempt has the username, IP and browser.
service.subpage_config_changedA subscription page config was made, changed or deleted.
service.api_token_created, _deletedAn API token was made or deleted; data.apiToken.
crm.infra_billing_node_payment_in_7_daysA 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.reportTorrent Blocker caught a user; data has the node, the user and the report.
errors.bandwidth_usage_threshold_reached_max_notificationsListed 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.

StreamOne message is
ioraw:export:user_usageOne node’s batch of user traffic: records is userId:bytes pairs joined by ;.
ioraw:export:subscription_requestsOne subscription fetch: user, time, IP, app and the response rule that answered.
ioraw:export:node_connectionsWho 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 >

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.

CodeHTTPMessage
Reference

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.