OmidCloud API · نسخه ۱

سرورهایت را با کد مدیریت کن.

با API امیدکلاد هر کاری که در پنل با سرورتان می‌کنید — دیدن وضعیت و مصرف، روشن و خاموش کردن، تغییر رمز، حالت Rescue و نصب مجدد — را از اسکریپت، CI یا ابزار مانیتورینگ خودتان انجام دهید. همه درخواست‌ها و پاسخ‌ها JSON هستند.

آدرس پایهhttps://omidcloud.net/api/v1
16اندپوینت3زبان نمونه کدJSONدرخواست و پاسخHTTPS Bearer Token

شروع سریع

در کمتر از یک دقیقه اولین درخواست را بفرستید:

کلید بسازید

در پنل ← امنیت ← کلیدهای API یک کلید بسازید. کلید فقط یک‌بار نمایش داده می‌شود؛ همان لحظه کپی‌اش کنید.

در متغیر محیطی بگذارید

کلید را داخل کد ننویسید؛ در متغیر OMIDCLOUD_API_KEY نگه دارید.

درخواست بفرستید

کلید را در هدر Authorization بفرستید و فهرست سرورهایتان را بگیرید.

bash
export OMIDCLOUD_API_KEY="vps_xxxxxxxxxxxxxxxxxxxxxxxx"

curl "https://omidcloud.net/api/v1/servers" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY"

احراز هویت

همه درخواست‌ها باید هدر زیر را داشته باشند. کلیدها با vps_ شروع می‌شوند و فقط به سرورها و اطلاعات حساب خودتان دسترسی دارند.

http
Authorization: Bearer vps_xxxxxxxxxxxxxxxxxxxxxxxx
کلید ما فقط به‌صورت هش ذخیره می‌شود و دوباره قابل نمایش نیست. اگر گمش کردید یا لو رفت، از همان صفحه ابطالش کنید و کلید جدید بسازید؛ آخرین زمان استفاده از هر کلید هم آنجا دیده می‌شود.
اندپوینت‌هایی که با برچسب کنترل مشخص شده‌اند فقط برای حساب احراز هویت‌شده و سرور فعال کار می‌کنند — همان قوانین پنل. سرور معلق‌شده از طریق API روشن نمی‌شود.

قالب درخواست و پاسخ

  • بدنه درخواست‌های POST از نوع JSON است و هدر Content-Type: application/json می‌خواهد.
  • پاسخ موفق کد 200 دارد. دستورهای کنترلی همیشه فیلد ok را برمی‌گردانند.
  • خطاهای اعتبارسنجی به شکل {"detail": "..."} و خطای هایپروایزر به شکل {"ok": false, "error": "..."} با کد 502 برمی‌گردد.
  • مبالغ به تومان و عدد صحیح، تاریخ‌ها به‌شکل YYYY-MM-DD هستند. در مسیرها {id} شناسه سرور است (از GET /servers).

حساب و کیف پول

GET /api/v1/me

اطلاعات حساب فقط خواندنی

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

نمونه درخواست
curl -X GET "https://omidcloud.net/api/v1/me" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY"
نمونه پاسخ 200 OK
json
{
  "id": 7,
  "username": "amin",
  "email": "amin@example.com",
  "wallet_balance": 2450000,
  "is_verified": true
}
GET /api/v1/wallet

کیف پول و تراکنش‌ها فقط خواندنی

موجودی فعلی و ۲۰ تراکنش آخر (جدیدترین اول). مبالغ به تومان است.

نمونه درخواست
curl -X GET "https://omidcloud.net/api/v1/wallet" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY"
نمونه پاسخ 200 OK
json
{
  "balance": 2450000,
  "transactions": [
    {
      "id": 431,
      "type": "deposit",
      "amount": 3000000,
      "status": "success",
      "date": "2026-10-01 14:22"
    },
    {
      "id": 430,
      "type": "purchase",
      "amount": 550000,
      "status": "success",
      "date": "2026-09-28 09:05"
    }
  ]
}
GET /api/v1/invoices

فاکتورها فقط خواندنی

همه فاکتورهای حساب، جدیدترین اول. مقدار kind نوع فاکتور است (مثل new_server، renew).

نمونه درخواست
curl -X GET "https://omidcloud.net/api/v1/invoices" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY"
نمونه پاسخ 200 OK
json
{
  "invoices": [
    {
      "number": "INV-20261001-0042",
      "kind": "renew",
      "total": 1650000,
      "status": "paid",
      "date": "2026-10-01"
    }
  ]
}

سرورها

GET /api/v1/servers

فهرست سرورها فقط خواندنی

همه سرورهای حساب به‌همراه منابع و تاریخ انقضا.

نمونه درخواست
curl -X GET "https://omidcloud.net/api/v1/servers" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY"
نمونه پاسخ 200 OK
json
{
  "servers": [
    {
      "id": 12,
      "name": "web-server-1",
      "ip": "185.0.2.24",
      "status": "active",
      "cpu": 2,
      "ram_mb": 4096,
      "disk_gb": 25,
      "traffic_gb": 100,
      "expires_at": "2026-11-01"
    }
  ]
}
GET /api/v1/servers/{id}

جزئیات سرور فقط خواندنی

اطلاعات کامل یک سرور: سیستم‌عامل، نام میزبان، دیتاسنتر، پلن، IPهای اضافه و قیمت ماهانه.

نمونه درخواست
curl -X GET "https://omidcloud.net/api/v1/servers/12" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY"
نمونه پاسخ 200 OK
json
{
  "id": 12,
  "name": "web-server-1",
  "ip": "185.0.2.24",
  "status": "active",
  "cpu": 2,
  "ram_mb": 4096,
  "disk_gb": 25,
  "traffic_gb": 100,
  "expires_at": "2026-11-01",
  "hostname": "web1.example.com",
  "os": {
    "id": 1215,
    "name": "Ubuntu 26.04"
  },
  "datacenter": "رسپینا",
  "plan": "P4",
  "extra_ips": [
    "185.0.2.25"
  ],
  "monthly_price": 1650000,
  "created_at": "2026-09-01"
}
GET /api/v1/servers/{id}/status

وضعیت روشن/خاموش فقط خواندنی

وضعیت زنده سرور از هایپروایزر. مقدار power یکی از on، off یا unknown است.

نمونه درخواست
curl -X GET "https://omidcloud.net/api/v1/servers/12/status" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY"
نمونه پاسخ 200 OK
json
{
  "ok": true,
  "power": "on"
}
GET /api/v1/servers/{id}/resources

مصرف منابع فقط خواندنی

درصد مصرف پردازنده و مقدار مصرف رم و دیسک به‌صورت زنده. اگر هایپروایزر مقدار مصرف را گزارش نکند، used برابر null است.

نمونه درخواست
curl -X GET "https://omidcloud.net/api/v1/servers/12/resources" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY"
نمونه پاسخ 200 OK
json
{
  "ok": true,
  "cpu_percent": 12.5,
  "ram_mb": {
    "used": 1830,
    "total": 4096
  },
  "disk_gb": {
    "used": 9.4,
    "total": 25
  }
}
GET /api/v1/servers/{id}/bandwidth

ترافیک مصرفی فقط خواندنی

ترافیک مصرف‌شده در دوره فعلی، سقف ترافیک و مصرف روزانه (کلید: روز ماه، مقدار: گیگابایت).

نمونه درخواست
curl -X GET "https://omidcloud.net/api/v1/servers/12/bandwidth" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY"
نمونه پاسخ 200 OK
json
{
  "ok": true,
  "used_gb": 31.2,
  "total_gb": 100,
  "percent": 31.2,
  "daily": {
    "1": 1.4,
    "2": 2.1,
    "3": 0.9
  }
}
GET /api/v1/os

سیستم‌عامل‌های قابل نصب فقط خواندنی

فهرست سیستم‌عامل‌ها؛ مقدار id همان os_id است که در نصب مجدد استفاده می‌کنید.

نمونه درخواست
curl -X GET "https://omidcloud.net/api/v1/os" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY"
نمونه پاسخ 200 OK
json
{
  "os": [
    {
      "id": 1215,
      "name": "Ubuntu 26.04",
      "family": "ubuntu"
    },
    {
      "id": 1188,
      "name": "Debian 13.0",
      "family": "debian"
    }
  ]
}

کنترل سرور

POST /api/v1/servers/{id}/power

روشن، خاموش، ری‌استارت کنترل

اجرای دستور پاور. stop خاموش کردن عادی است و poweroff خاموشی اجباری (مثل کشیدن برق؛ ممکن است داده ذخیره‌نشده از دست برود). به‌جای بدنه JSON می‌توانید از ?action=restart هم استفاده کنید.

پارامترها (بدنه JSON)
نامنوعتوضیح
actionstring
الزامی
یکی از start، stop، restart، poweroff
نمونه درخواست
curl -X POST "https://omidcloud.net/api/v1/servers/12/power" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "restart"}'
نمونه پاسخ 200 OK
json
{
  "ok": true,
  "action": "restart"
}
POST /api/v1/servers/{id}/hostname

تغییر نام میزبان کنترل

نام میزبان (hostname) سرور را تغییر می‌دهد. فقط حروف انگلیسی، عدد، خط تیره و نقطه مجاز است.

پارامترها (بدنه JSON)
نامنوعتوضیح
hostnamestring
الزامی
مثلاً web1.example.com
نمونه درخواست
curl -X POST "https://omidcloud.net/api/v1/servers/12/hostname" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "web1.example.com"}'
نمونه پاسخ 200 OK
json
{
  "ok": true,
  "hostname": "web1.example.com"
}
POST /api/v1/servers/{id}/root-password

تغییر رمز روت کنترل

رمز کاربر root (یا Administrator در ویندوز) را تغییر می‌دهد.

پارامترها (بدنه JSON)
نامنوعتوضیح
passwordstring
الزامی
حداقل ۸ کاراکتر
نمونه درخواست
curl -X POST "https://omidcloud.net/api/v1/servers/12/root-password" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password": "N3w-Str0ng-Pass"}'
نمونه پاسخ 200 OK
json
{
  "ok": true
}
GET /api/v1/servers/{id}/vnc

اطلاعات کنسول VNC کنترل

آدرس، پورت و رمز VNC برای اتصال با کلاینت‌های VNC، و آدرس کنسول تحت وب پنل.

نمونه درخواست
curl -X GET "https://omidcloud.net/api/v1/servers/12/vnc" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY"
نمونه پاسخ 200 OK
json
{
  "ok": true,
  "host": "185.0.2.10",
  "port": 5997,
  "password": "5DGLuVJA",
  "console_url": "/servers/12/console"
}
POST /api/v1/servers/{id}/vnc-password

تغییر رمز VNC کنترل

رمز اتصال به کنسول VNC را تغییر می‌دهد.

پارامترها (بدنه JSON)
نامنوعتوضیح
passwordstring
الزامی
حداقل ۶ کاراکتر
نمونه درخواست
curl -X POST "https://omidcloud.net/api/v1/servers/12/vnc-password" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password": "vnc-Pass9"}'
نمونه پاسخ 200 OK
json
{
  "ok": true
}
POST /api/v1/servers/{id}/rescue

حالت Rescue کنترل

سرور را در حالت Rescue (یک لینوکس موقت) بالا می‌آورد تا بتوانید دیسک را بازیابی یا تعمیر کنید. برای خروج، enable را false بفرستید.

پارامترها (بدنه JSON)
نامنوعتوضیح
enableboolean
الزامی
true برای فعال، false برای غیرفعال
passwordstring
اختیاری
رمز ورود به محیط Rescue؛ هنگام فعال‌سازی الزامی (حداقل ۸ کاراکتر)
نمونه درخواست
curl -X POST "https://omidcloud.net/api/v1/servers/12/rescue" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enable": true, "password": "Rescue-Pass1"}'
نمونه پاسخ 200 OK
json
{
  "ok": true,
  "rescue": true
}
POST /api/v1/servers/{id}/reinstall

نصب مجدد سیستم‌عامل غیرقابل بازگشتکنترل

سیستم‌عامل را از نو نصب می‌کند. همه اطلاعات دیسک پاک می‌شود؛ برای همین باید confirm را صریحاً true بفرستید.

این عملیات تمام اطلاعات سرور را پاک می‌کند و قابل بازگشت نیست. قبل از اجرا از داده‌ها نسخه پشتیبان بگیرید.
پارامترها (بدنه JSON)
نامنوعتوضیح
os_idinteger
الزامی
شناسه از GET /api/v1/os
root_passwordstring
الزامی
رمز روت سیستم جدید، حداقل ۸ کاراکتر
confirmboolean
الزامی
باید true باشد
نمونه درخواست
curl -X POST "https://omidcloud.net/api/v1/servers/12/reinstall" \
  -H "Authorization: Bearer $OMIDCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"os_id": 1215, "root_password": "N3w-Str0ng-Pass", "confirm": true}'
نمونه پاسخ 200 OK
json
{
  "ok": true,
  "os_id": 1215
}

کدهای خطا

کد وضعیت HTTP همیشه معنی‌دار است؛ قبل از خواندن بدنه آن را بررسی کنید.

کدمعنیچه زمانی و نمونه پاسخ
400درخواست نامعتبرپارامتر اشتباه یا ناقص، یا سرور هنوز ساخته نشده است.{"detail": "invalid action (start | stop | restart | poweroff)"}
401احراز هویت ناموفقهدر Authorization نیست یا کلید نامعتبر/باطل‌شده است.{"detail": "invalid API key"}
403دسترسی نداریدحساب احراز هویت نشده، غیرفعال است یا سرویس فعال نیست (مثلاً معلق).{"detail": "server is not active"}
404پیدا نشدسرور وجود ندارد یا متعلق به حساب شما نیست.{"detail": "server not found"}
422قالب بدنه اشتباهبدنه JSON نیست یا فیلد الزامی آن را نفرستاده‌اید.{"detail": [{"loc": ["body", "hostname"], "msg": "Field required"}]}
502خطای هایپروایزردستور به سرور مجازی‌ساز رسید ولی اجرا نشد. پیام خطا در error است.{"ok": false, "error": "VPS is locked"}

محدوده API

برای امنیت حساب شما، عملیاتی که پول خرج می‌کنند یا سرویس را حذف می‌کنند عمداً فقط از داخل پنل انجام می‌شوند.

از طریق API

  • خواندن حساب، کیف پول، فاکتورها و سرورها
  • وضعیت زنده، مصرف منابع و ترافیک
  • روشن، خاموش، ری‌استارت و خاموشی اجباری
  • نام میزبان، رمز روت و رمز VNC
  • حالت Rescue و نصب مجدد سیستم‌عامل

فقط از داخل پنل

  • خرید سرور جدید و پرداخت فاکتور
  • ارتقای پلن، خرید ترافیک و IP اضافه
  • شارژ کیف پول
  • حذف سرور
  • ساخت و ابطال کلیدهای API

نکات امنیتی

  • برای هر اسکریپت یا سرویس یک کلید جدا بسازید تا در صورت نشت، فقط همان را باطل کنید.
  • کلید را در کد، مخزن Git یا لاگ‌ها نگذارید؛ از متغیر محیطی یا Secret Manager استفاده کنید.
  • کلید دسترسی کامل به سرورهای شماست — مثل رمز عبور با آن رفتار کنید و فقط روی HTTPS بفرستید.
  • ستون «آخرین استفاده» را در صفحه کلیدها گاهی بررسی کنید و کلیدهای بلااستفاده را باطل کنید.