EasyXrayمرجع API
REST API پنل EasyXray — فضای نام، احراز هویت، inboundها، کلاینت‌ها، آمار سرور و موارد دیگر، تولیدشده از مشخصات OpenAPI.
پنل EasyXray یک REST API برای خودکارسازی در اختیار می‌گذارد. صفحات این بخش از مشخصات OpenAPI خود پنل تولید شده‌اند، بنابراین همواره با اسکیمایی که پنل واقعاً ارائه می‌دهد هماهنگ هستند.
فضای نام
هر آنچه پنل ارائه می‌دهد زیر مسیر پایهٔ پیکربندی‌شدهٔ وب (webBasePath) و سپس
easyxray قرار دارد:
| سطح | مسیر |
|---|---|
| رابط پنل | <basePath>/easyxray/… |
| REST API | <basePath>/easyxray/api/v1/… |
| WebSocket | <basePath>/easyxray/ws |
| مشخصات OpenAPI | <basePath>/easyxray/api/v1/openapi.json |
با مسیر پایهٔ پیش‌فرض (/)، برای مثال یعنی:
GET /easyxray/api/v1/inbounds/list
POST /easyxray/api/v1/clients/add
GET /easyxray/api/v1/server/status
GET /easyxray/api/v1/openapi.jsonفضای نام easyxray نام مستعار ندارد. نسخه‌های پیشین پنل X-UI/3x-ui این
endpointها را زیر /panel/api/… ارائه می‌کردند؛ EasyXray روی آن پیشوند
پاسخی نمی‌دهد و هیچ ریدایرکت سازگاری نصب نشده است. هر اسکریپت، ربات یا
داشبوردی که برای مسیرهای قدیمی نوشته‌اید باید به مسیرهای /easyxray/api/v1/…
در بالا به‌روزرسانی شود.
احراز هویت
درخواست‌ها یا با یک کوکی نشست — که هنگام ورود به پنل تنظیم می‌شود و نامش
easyxray است — یا با یک توکن Bearer احراز هویت می‌شوند:
Authorization: Bearer <token>توکن‌های API را در تنظیمات → امنیت → توکن API بسازید؛ این توکن‌ها اعتبارنامه‌های ادمین کامل هستند، پس آن‌ها را مانند رمز عبور پنل نگهداری کنید. به توکن‌های API مراجعه کنید.
برای هر endpointی در این بخش یک درخواست احرازهویت‌شده بسازید:
API request builder
Build an authenticated cURL command or fetch() snippet for any EasyXray panel API endpoint under /easyxray/api/v1/*.
curl -X GET 'https://panel.example.com:2053/easyxray/api/v1/inbounds/list' \
-H 'Authorization: Bearer <token>'await fetch('https://panel.example.com:2053/easyxray/api/v1/inbounds/list', {
method: 'GET',
headers: { 'Authorization': 'Bearer <token>' },
});مرور بر اساس حوزه
صفحات هر حوزه با اجرای pnpm gen:api از مشخصات ثبت‌شدهٔ public/openapi.json
بازتولید می‌شوند (خود مشخصات توسط frontend/scripts/build-openapi.mjs در
مخزن پنل منتشر می‌شود). صفحات تگ تولیدشده را به‌صورت دستی ویرایش نکنید — منبع
مشخصات را تغییر دهید و دوباره تولید کنید.
پورت‌ها و فایروال
پورت‌هایی که EasyXray به‌صورت پیش‌فرض استفاده می‌کند و قواعد آماده ufw / nftables برای باز کردن آن‌ها.
احراز هویت
دو حالت احراز هویت پشتیبانی می‌شود. نشست‌های UI از یک کوکی استفاده می‌کنند که توسط نقطه‌پایانی ورود تنظیم می‌شود. کلاینت‌های برنامه‌نویسی‌شده (ربات‌ها، اسکریپت‌ها، پنل‌های راه دور) با یک توکن Bearer که از مسیر Settings → Security → API Token گرفته می‌شود احراز هویت می‌کنند. هر دو روش برای همهٔ نقاط‌پایانی زیر /easyxray/api/v1/* کار می‌کنند.