API

هر کاری که پنل انجام می‌دهد، از طریق HTTP API خودش انجام می‌دهد. مسیر خصوصی‌ای نیست که رابط کاربری از آن استفاده کند و برنامه‌های دیگر نتوانند.

احراز هویت

یا وارد شوید و توکن نشست بگیرید:

curl -X POST 'https://panel:2053/PATH/api/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"…"}'

یا از یک توکن API استفاده کنید: همانی که نصب‌کننده چاپ کرد، یا توکنی از تنظیمات ← احراز هویت ← توکن API، یا از wui token issue --name NAME. آن را این‌طور بفرستید:

Authorization: Bearer wui_…

کارهایی که توکن نمی‌تواند انجام دهد

توکن مال یک ماشین است. کاری که فقط مدیر می‌تواند انجام دهد، با 403 this needs a signed-in administrator, not an API token جواب می‌گیرد: حساب و ورود دومرحله‌ای خود مدیر، صدور یا باطل کردن توکن، بکاپ، ثبت نودها و اعتماد به آنها، تنظیمات و قالب پنل، و ری‌استارت. هر کاری درباره‌ی مشتری‌ها، دستگاه‌ها، تونل‌ها، میزبان‌ها، خروجی‌ها و مسیریابی با توکن ممکن است؛ توکن برای همین است.

توکن‌های اضافه با نام «installer»

پیش از اصلاح این مشکل، هر به‌روزرسانی با نصب‌کننده یک توکن دیگر با دسترسی کامل به نام installer روی پنل جا می‌گذاشت. هر کدام اعتبارنامه‌ی معتبری است که کسی از آن استفاده نمی‌کند. همانی را که اتوماسیون شما از install-result.env می‌خواند نگه دارید و بقیه را در تنظیمات ← احراز هویت ← توکن API باطل کنید؛ فهرست، پیشوند هر توکن و آخرین استفاده‌اش را نشان می‌دهد.

مستندات داخل خود پنل است

API در نوار کناری همه‌ی endpointها را گروه‌بندی‌شده نشان می‌دهد، با بدنه‌ی نمونه و دستور curl با همان آدرسی که با آن به پنل رسیده‌اید. این صفحه از همان جدولی ساخته می‌شود که مسیرها از روی آن ثبت می‌شوند؛ پس فقط endpointهایی را توصیف می‌کند که واقعاً هستند، و endpoint تازه با اضافه شدنش مستند می‌شود.

GET /api/docs همین را به شکل JSON برمی‌گرداند.

چند endpoint پرکاربرد

GET /api/overview/full	تله‌متری، وضعیت پنل و موجودی، در یک درخواست
GET /api/clients?search=&status=&group=&page=&perPage=	مشتری‌ها
POST /api/clients	ساختن مشتری؛ telegramId، quotaBytes، expiresAt، deviceLimit، interfaceIds
POST /api/clients/{id}/reset	صفر کردن مصرف
GET /api/clients/{id}/configs · GET /api/devices/{id}/profiles	همه‌ی کانفیگ‌ها، برای هر دستگاه و هر میزبان
GET /api/interfaces · POST · PATCH /{id} · DELETE /{id}	تونل‌ها
GET /api/outbounds · POST /api/outbounds/{id}/check	هاپ‌ها و بررسی آنها
GET /api/routing · POST /api/routing/rules/order	قانون‌ها
GET /api/template?section= · PUT	کل پیکربندی
POST /api/backups · GET /api/backups/{name}	بکاپ‌ها
GET /api/backups/password · PUT /api/backups/password	اینکه آرشیوها رمزنگاری می‌شوند یا نه؛ تنظیم رمز بکاپ ({"password":"…"}، دست‌کم ده نویسه؛ خالی یعنی توقف رمزنگاری)
GET /api/system · GET /api/system/history	سرور
GET /api/health	200 {"ok":true} یا 503، بدون ورود، برای سرویس پایش در دسترس بودن. زیر مسیر خود پنل است و دلیل خرابی فقط به کسی گفته می‌شود که وارد شده باشد.
GET /api/metrics	برای Prometheus: بالا یا پایین بودن هر تونل، آخرین اجرای چرخه، شکست در نوشتن مصرف، در دسترس بودن نودها، و بکاپ‌های نگه‌داشته‌شده

خطاها به شکل {"error": "…", "field": "…"} برمی‌گردند، با کد وضعیتی که همان معنی را دارد؛ خطای اعتبارسنجی نام فیلد را می‌گوید.