شروع سریع
در کمتر از یک دقیقه اولین درخواست را بفرستید:
در متغیر محیطی بگذارید کلید را داخل کد ننویسید؛ در متغیر OMIDCLOUD_API_KEY نگه دارید.
درخواست بفرستید کلید را در هدر Authorization بفرستید و فهرست سرورهایتان را بگیرید.
export OMIDCLOUD_API_KEY="vps_xxxxxxxxxxxxxxxxxxxxxxxx"
curl "https://omidcloud.net/api/v1/servers" \
-H "Authorization: Bearer $OMIDCLOUD_API_KEY"
احراز هویت
همه درخواستها باید هدر زیر را داشته باشند. کلیدها با vps_ شروع میشوند و فقط به سرورها و اطلاعات حساب خودتان دسترسی دارند.
Authorization: Bearer vps_xxxxxxxxxxxxxxxxxxxxxxxx
کلید ما فقط بهصورت هش ذخیره میشود و دوباره قابل نمایش نیست. اگر گمش کردید یا لو رفت، از همان صفحه ابطالش کنید و کلید جدید بسازید؛ آخرین زمان استفاده از هر کلید هم آنجا دیده میشود.
اندپوینتهایی که با برچسب کنترل مشخص شدهاند فقط برای حساب احراز هویتشده و سرور فعال کار میکنند — همان قوانین پنل. سرور معلقشده از طریق API روشن نمیشود.
حساب و کیف پول
GET
/api/v1/me
اطلاعات حساب
فقط خواندنی
مشخصات حسابی که کلید API به آن تعلق دارد، بههمراه موجودی کیف پول.
نمونه درخواست
cURL
Python
JavaScript
کپی
curl -X GET "https://omidcloud.net/api/v1/me" \
-H "Authorization: Bearer $OMIDCLOUD_API_KEY"
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.get("https://omidcloud.net/api/v1/me", headers=headers)
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/me", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"id": 7,
"username": "amin",
"email": "amin@example.com",
"wallet_balance": 2450000,
"is_verified": true
}
GET
/api/v1/wallet
کیف پول و تراکنشها
فقط خواندنی
موجودی فعلی و ۲۰ تراکنش آخر (جدیدترین اول). مبالغ به تومان است.
نمونه درخواست
cURL
Python
JavaScript
کپی
curl -X GET "https://omidcloud.net/api/v1/wallet" \
-H "Authorization: Bearer $OMIDCLOUD_API_KEY"
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.get("https://omidcloud.net/api/v1/wallet", headers=headers)
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/wallet", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"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
Python
JavaScript
کپی
curl -X GET "https://omidcloud.net/api/v1/invoices" \
-H "Authorization: Bearer $OMIDCLOUD_API_KEY"
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.get("https://omidcloud.net/api/v1/invoices", headers=headers)
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/invoices", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"invoices": [
{
"number": "INV-20261001-0042",
"kind": "renew",
"total": 1650000,
"status": "paid",
"date": "2026-10-01"
}
]
}
سرورها
GET
/api/v1/servers
فهرست سرورها
فقط خواندنی
همه سرورهای حساب بههمراه منابع و تاریخ انقضا.
نمونه درخواست
cURL
Python
JavaScript
کپی
curl -X GET "https://omidcloud.net/api/v1/servers" \
-H "Authorization: Bearer $OMIDCLOUD_API_KEY"
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.get("https://omidcloud.net/api/v1/servers", headers=headers)
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"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
Python
JavaScript
کپی
curl -X GET "https://omidcloud.net/api/v1/servers/12" \
-H "Authorization: Bearer $OMIDCLOUD_API_KEY"
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.get("https://omidcloud.net/api/v1/servers/12", headers=headers)
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers/12", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"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
Python
JavaScript
کپی
curl -X GET "https://omidcloud.net/api/v1/servers/12/status" \
-H "Authorization: Bearer $OMIDCLOUD_API_KEY"
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.get("https://omidcloud.net/api/v1/servers/12/status", headers=headers)
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers/12/status", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"ok": true,
"power": "on"
}
GET
/api/v1/servers/{id} /resources
مصرف منابع
فقط خواندنی
درصد مصرف پردازنده و مقدار مصرف رم و دیسک بهصورت زنده. اگر هایپروایزر مقدار مصرف را گزارش نکند، used برابر null است.
نمونه درخواست
cURL
Python
JavaScript
کپی
curl -X GET "https://omidcloud.net/api/v1/servers/12/resources" \
-H "Authorization: Bearer $OMIDCLOUD_API_KEY"
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.get("https://omidcloud.net/api/v1/servers/12/resources", headers=headers)
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers/12/resources", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"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
Python
JavaScript
کپی
curl -X GET "https://omidcloud.net/api/v1/servers/12/bandwidth" \
-H "Authorization: Bearer $OMIDCLOUD_API_KEY"
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.get("https://omidcloud.net/api/v1/servers/12/bandwidth", headers=headers)
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers/12/bandwidth", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"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
Python
JavaScript
کپی
curl -X GET "https://omidcloud.net/api/v1/os" \
-H "Authorization: Bearer $OMIDCLOUD_API_KEY"
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.get("https://omidcloud.net/api/v1/os", headers=headers)
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/os", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"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)
نام نوع توضیح
action string الزامی یکی از start، stop، restart، poweroff
نمونه درخواست
cURL
Python
JavaScript
کپی
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"}'
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.post("https://omidcloud.net/api/v1/servers/12/power", headers=headers, json={"action": "restart"})
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers/12/power", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"action": "restart"}),
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"ok": true,
"action": "restart"
}
POST
/api/v1/servers/{id} /hostname
تغییر نام میزبان
کنترل
نام میزبان (hostname) سرور را تغییر میدهد. فقط حروف انگلیسی، عدد، خط تیره و نقطه مجاز است.
پارامترها (بدنه JSON)
نام نوع توضیح
hostname string الزامی مثلاً web1.example.com
نمونه درخواست
cURL
Python
JavaScript
کپی
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"}'
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.post("https://omidcloud.net/api/v1/servers/12/hostname", headers=headers, json={"hostname": "web1.example.com"})
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers/12/hostname", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"hostname": "web1.example.com"}),
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"ok": true,
"hostname": "web1.example.com"
}
POST
/api/v1/servers/{id} /root-password
تغییر رمز روت
کنترل
رمز کاربر root (یا Administrator در ویندوز) را تغییر میدهد.
پارامترها (بدنه JSON)
نام نوع توضیح
password string الزامی حداقل ۸ کاراکتر
نمونه درخواست
cURL
Python
JavaScript
کپی
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"}'
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.post("https://omidcloud.net/api/v1/servers/12/root-password", headers=headers, json={"password": "N3w-Str0ng-Pass"})
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers/12/root-password", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"password": "N3w-Str0ng-Pass"}),
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
GET
/api/v1/servers/{id} /vnc
اطلاعات کنسول VNC
کنترل
آدرس، پورت و رمز VNC برای اتصال با کلاینتهای VNC، و آدرس کنسول تحت وب پنل.
نمونه درخواست
cURL
Python
JavaScript
کپی
curl -X GET "https://omidcloud.net/api/v1/servers/12/vnc" \
-H "Authorization: Bearer $OMIDCLOUD_API_KEY"
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.get("https://omidcloud.net/api/v1/servers/12/vnc", headers=headers)
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers/12/vnc", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"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)
نام نوع توضیح
password string الزامی حداقل ۶ کاراکتر
نمونه درخواست
cURL
Python
JavaScript
کپی
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"}'
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.post("https://omidcloud.net/api/v1/servers/12/vnc-password", headers=headers, json={"password": "vnc-Pass9"})
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers/12/vnc-password", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"password": "vnc-Pass9"}),
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
POST
/api/v1/servers/{id} /rescue
حالت Rescue
کنترل
سرور را در حالت Rescue (یک لینوکس موقت) بالا میآورد تا بتوانید دیسک را بازیابی یا تعمیر کنید. برای خروج، enable را false بفرستید.
پارامترها (بدنه JSON)
نام نوع توضیح
enable boolean الزامی true برای فعال، false برای غیرفعال
password string اختیاری رمز ورود به محیط Rescue؛ هنگام فعالسازی الزامی (حداقل ۸ کاراکتر)
نمونه درخواست
cURL
Python
JavaScript
کپی
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"}'
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.post("https://omidcloud.net/api/v1/servers/12/rescue", headers=headers, json={"enable": True, "password": "Rescue-Pass1"})
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers/12/rescue", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"enable": true, "password": "Rescue-Pass1"}),
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"ok": true,
"rescue": true
}
POST
/api/v1/servers/{id} /reinstall
نصب مجدد سیستمعامل
غیرقابل بازگشت کنترل
سیستمعامل را از نو نصب میکند. همه اطلاعات دیسک پاک میشود ؛ برای همین باید confirm را صریحاً true بفرستید.
این عملیات تمام اطلاعات سرور را پاک میکند و قابل بازگشت نیست. قبل از اجرا از دادهها نسخه پشتیبان بگیرید.
پارامترها (بدنه JSON)
نام نوع توضیح
os_id integer الزامی شناسه از GET /api/v1/os
root_password string الزامی رمز روت سیستم جدید، حداقل ۸ کاراکتر
confirm boolean الزامی باید true باشد
نمونه درخواست
cURL
Python
JavaScript
کپی
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}'
import os, requests
headers = {"Authorization": f"Bearer {os.environ['OMIDCLOUD_API_KEY']}"}
r = requests.post("https://omidcloud.net/api/v1/servers/12/reinstall", headers=headers, json={"os_id": 1215, "root_password": "N3w-Str0ng-Pass", "confirm": True})
r.raise_for_status()
print(r.json())
const res = await fetch("https://omidcloud.net/api/v1/servers/12/reinstall", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.OMIDCLOUD_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"os_id": 1215, "root_password": "N3w-Str0ng-Pass", "confirm": true}),
});
if (!res.ok) throw new Error((await res.json()).detail);
console.log(await res.json());
نمونه پاسخ 200 OK
{
"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 بفرستید.
ستون «آخرین استفاده» را در صفحه کلیدها گاهی بررسی کنید و کلیدهای بلااستفاده را باطل کنید.