API سرورها

لیست همه سرورها

کارسازهای موجود در حساب شما را با اولی جدیدتر و ۲۵ در هر صفحه برمی‌گرداند. کارسازهایی که حذف می‌شوند ، شامل نمی‌شوند.

مجوز مورد نیاز: servers:list

پارامترهای پرس و جو

درخواست نمونه

curl -X GET "https://admin.vps.org/api/v1/servers/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests

url = "https://admin.vps.org/api/v1/servers/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
for server in response.json()["results"]:
    print(server["uuid"], server["hostname"], server["status"])

const response = await fetch('https://admin.vps.org/api/v1/servers/', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});

const data = await response.json();
console.log(data.results);

$ch = curl_init('https://admin.vps.org/api/v1/servers/');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer YOUR_API_TOKEN']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($data['results'] as $server) {
    echo $server['hostname'] . ' ' . $server['status'] . "\n";
}

پاسخ نمونه

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b",
      "hostname": "web-01",
      "status": "on",
      "error_description": null,
      "location_name": "New Jersey",
      "plan_name": "1 vCPU / 2 GB RAM / 10 GB",
      "os_name": "Ubuntu",
      "ipv4_addresses": ["203.0.113.10"],
      "ipv6_addresses": ["2001:db8:2:dd::f9:6b"],
      "created_at": "2026-07-30T03:54:14.914364Z",
      "deployed": true
    },
    {
      "uuid": "2d7e9b40-6c1a-4f3e-8b5d-9a0c1e2f3b4d",
      "hostname": "db-01",
      "status": "queue",
      "error_description": null,
      "location_name": "New Jersey",
      "os_name": "Debian",
      "ipv4_addresses": [],
      "ipv6_addresses": [],
      "created_at": "2026-09-14T19:33:49.426508Z",
      "deployed": false
    }
  ]
}

فیلدهای پاسخ

کدهای وضعیت پاسخ

ایجاد سرور جدید

صف کارساز جدید برای پراکندگی را ایجاد می‌کند و بلافاصله با صف وضعیت آن را برمی‌گرداند. فراهم‌سازی در پس‌زمینه ادامه می‌یابد: نقطه پایانی وضعیت را پرس و جو کنید تا زمانی که پراکندگی درست باشد. هنگامی که کارساز آماده است ، جزئیات ورود آن به صاحب حساب ارسال می‌شود.

حساب شما نیازمند یک روش پرداخت ذخیره‌شده است. بسته به تاریخچه حساب شما، ممکن است قبل از ایجاد کارگزار، یک پیش‌اجازه‌ی موقت حدود یک هفته از قیمت برنامه (حداقل ۱ دلار آمریکا) روی کارت شما قرار گیرد.

مجوز مورد نیاز: servers:create

درخواست پارامترهای بدنه

درخواست نمونه

curl -X POST "https://admin.vps.org/api/v1/servers/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "web-01",
    "location_id": 1,
    "plan_uuid": "3bc2faf6-8f8b-4978-b62d-b52ed3f858e9",
    "operating_system_version_uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "ssh_key_uuids": ["YOUR_SSH_KEY_UUID"]
  }'

import requests

url = "https://admin.vps.org/api/v1/servers/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
data = {
    "hostname": "web-01",
    "location_id": 1,
    "plan_uuid": "3bc2faf6-8f8b-4978-b62d-b52ed3f858e9",
    "operating_system_version_uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "ssh_key_uuids": ["YOUR_SSH_KEY_UUID"],
}

response = requests.post(url, headers=headers, json=data)
server = response.json()
print(response.status_code, server["uuid"], server["status"])

const response = await fetch('https://admin.vps.org/api/v1/servers/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    hostname: 'web-01',
    location_id: 1,
    plan_uuid: '3bc2faf6-8f8b-4978-b62d-b52ed3f858e9',
    operating_system_version_uuid: 'c3418f90-80a0-4e00-a7e1-d0ab1822b941',
    ssh_key_uuids: ['YOUR_SSH_KEY_UUID']
  })
});

const server = await response.json();
console.log(server.uuid, server.status);

$data = [
    'hostname' => 'web-01',
    'location_id' => 1,
    'plan_uuid' => '3bc2faf6-8f8b-4978-b62d-b52ed3f858e9',
    'operating_system_version_uuid' => 'c3418f90-80a0-4e00-a7e1-d0ab1822b941',
    'ssh_key_uuids' => ['YOUR_SSH_KEY_UUID']
];

$ch = curl_init('https://admin.vps.org/api/v1/servers/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_TOKEN',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$server = json_decode(curl_exec($ch), true);
curl_close($ch);

پاسخ نمونه

201 با شیء کامل کارساز که در Get Server Details توصیف شده‌است ایجاد شده‌است. آدرس‌ها و vmid هنگامی که انتشار به پایان می‌رسد پر می‌شوند.

{
  "uuid": "5f0c8e2a-6b1d-4c3e-9a7f-2d4b6c8e0a1f",
  "hostname": "web-01",
  "vmid": null,
  "status": "queue",
  "error_description": null,
  "location": {
    "id": 1,
    "name": "New Jersey",
    "country_name": "United States",
    "is_active": true
  },
  "plan": {
    "uuid": "3bc2faf6-8f8b-4978-b62d-b52ed3f858e9",
    "cpu": 1,
    "ram": 2,
    "ram_unit": "GB",
    "disk_space": 10,
    "disk_space_total": 10240,
    "transfer": 500,
    "price": "3.50",
    "cpu_type_name": "Shared",
    "is_active": true,
    "hourly_price": "0.005",
    "monthly_price": "3.50",
    "is_gpu": false,
    "gpu_count": 0,
    "gpu_model": ""
  },
  "operating_system": {
    "id": 1,
    "name": "Ubuntu",
    "svg_icon": "<svg ...>",
    "versions": [ ... ]
  },
  "operating_system_version": {
    "uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "name": "24.04 LTS x64",
    "os_name": "Ubuntu",
    "os_svg_icon": "<svg ...>",
    "is_active": true
  },
  "ipv4_addresses": [],
  "ipv6_addresses": [],
  "deployed": false,
  "created_at": "2026-09-14T21:02:11.402113Z",
  "recent_actions": []
}

کدهای وضعیت پاسخ

دریافت جزئیات سرور

یک سرور را با مکان، برنامه، سیستم عامل، آدرس IP و پنج آخرین عمل باز می‌گرداند.

مجوز مورد نیاز: servers:list

curl -X GET "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

پاسخ نمونه

{
  "uuid": "8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b",
  "hostname": "web-01",
  "vmid": 1042,
  "status": "on",
  "error_description": null,
  "location": {
    "id": 1,
    "name": "New Jersey",
    "country_name": "United States",
    "is_active": true
  },
  "plan": {
    "uuid": "14186969-fbaf-43e1-9ab2-b1f1aeb66674",
    "cpu": 1,
    "ram": 2,
    "ram_unit": "GB",
    "disk_space": 25,
    "disk_space_total": 25600,
    "transfer": 1,
    "price": "5.00",
    "cpu_type_name": "Shared",
    "is_active": true,
    "hourly_price": "0.007",
    "monthly_price": "5.00",
    "is_gpu": false,
    "gpu_count": 0,
    "gpu_model": ""
  },
  "operating_system": {
    "id": 1,
    "name": "Ubuntu",
    "svg_icon": "<svg ...>",
    "versions": [ ... ]
  },
  "operating_system_version": {
    "uuid": "c3418f90-80a0-4e00-a7e1-d0ab1822b941",
    "name": "24.04 LTS x64",
    "os_name": "Ubuntu",
    "os_svg_icon": "<svg ...>",
    "is_active": true
  },
  "ipv4_addresses": [
    {
      "ip": "203.0.113.10",
      "gateway": "203.0.113.1",
      "subnet": "203.0.113.0",
      "rdns": "web-01.example.com"
    }
  ],
  "ipv6_addresses": [
    {
      "ip": "2001:db8:2:dd::f9:6b",
      "gateway": "2001:db8:2:dd::f9:1",
      "subnet": "2001:db8:2:dd::f9:0",
      "rdns": "web-01.example.com"
    }
  ],
  "deployed": true,
  "created_at": "2026-07-30T03:54:14.914364Z",
  "recent_actions": [
    {
      "id": 17028,
      "action": "create",
      "action_display": "Create",
      "description": "Server deployed with VMID 1042",
      "user_email": "you@example.com",
      "created_at": "2026-07-30T03:54:32.860854Z"
    }
  ]
}

در این نسخه از مرورگر، مرورگرهای وب و مرورگرهای وب‌گردی به صورت پیش‌فرض در نظر گرفته شده‌اند.

فیلدهای پاسخ

کدهای وضعیت پاسخ

دریافت وضعیت کارساز

یک فراخوان سبک برای پرسش پس از ایجاد، قدرت یا تغییر اندازه کارساز.

curl -X GET "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/status/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "status": "on",
  "deployed": true,
  "resizing": false
}

مقادیر وضعیت کارساز

کنترل توان کارساز

صف کردن یک کنش قدرت. وضعیت کارساز تا زمانی که کنش تکمیل شود به صف تغییر می‌کند.

مجوز مورد نیاز: servers:power

درخواست پارامترهای بدنه

درخواست نمونه

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/power/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "restart"}'

import requests

server_uuid = "8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b"
url = f"https://admin.vps.org/api/v1/servers/{server_uuid}/power/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.post(url, headers=headers, json={"action": "restart"})
print(response.json())

پاسخ نمونه

{
  "message": "Server restart queued"
}

کدهای وضعیت پاسخ

تغییر اندازۀ کارساز

کارساز را به یک طرح فعال دیگر منتقل می‌کند. طرح جدید نمی‌تواند فضای دیسک کمتری نسبت به طرح جاری داشته باشد ، و بدنۀ درخواست باید شامل عمل تنظیم شده برای تغییر اندازۀ آن باشد. ظرفیت ابرنمایشگر برای طرح جدید قبل از صف کردن هر چیزی بررسی می‌شود ، بنابراین درخواست رد شده کارساز را بدون تغییر می‌گذارد.

کارساز در حین تغییر اندازۀ خود خاموش می‌شود و بعد از آن دوباره شروع می‌شود. اگر تغییر اندازۀ کارساز شکست بخورد ، کارساز به طرح قبلی خود برمی‌گردد و اگر در حال اجرا بود ، دوباره شروع می‌شود. رشد دیسک را نمی‌توان برگرداند.

مجوز مورد نیاز: servers:resize

درخواست پارامترهای بدنه

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/resize/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "resize", "new_plan_uuid": "5e26a4a6-bd0c-467c-abca-da036c811c3f"}'

{
  "message": "Resize queued successfully"
}

مثالی از تغییر اندازه رد شده (409):

{
  "error": "Not enough hypervisor capacity for the selected plan; the server was not changed"
}

کدهای وضعیت پاسخ

بازنشانی گذرواژه ریشه

تولید یک گذرواژه ریشۀ جدید ، بازگرداندن آن در پاسخ و صف کردن تغییر در کارساز. گذرواژه جدید همچنین به شما با رایانامه ارسال می‌شود. کارساز باید پراکنده شود. بدنۀ درخواست نیازی نیست.

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/reset-password/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "message": "Password reset queued. New password will also be emailed to you.",
  "password": "generated-password",
  "job_id": "b6f1c7e2-3a4d-4f5e-8b9c-0d1e2f3a4b5c"
}

کدهای وضعیت پاسخ

DNS معکوس (PTR)

GET نام میزبان DNS معکوس هر آدرس IPv4 و IPv6 را در کارساز فهرست می‌کند. POST آن را برای یک آدرس تنظیم می‌کند. ارسال نام میزبان خالی آدرس را به نام DNS معکوس پیش‌فرض بازگرداند.

مجوز مورد نیاز: servers:update

درخواست پارامترهای بدنه (POST)

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/rdns/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.10", "hostname": "mail.example.com"}'

{
  "message": "Reverse DNS for 203.0.113.10 set to mail.example.com",
  "ip": "203.0.113.10",
  "hostname": "mail.example.com"
}

پاسخ GET:

{
  "rdns": [
    {"ip": "203.0.113.10", "hostname": "mail.example.com"},
    {"ip": "2001:db8:2:dd::f9:6b", "hostname": "mail.example.com"}
  ]
}

کدهای وضعیت پاسخ

اجرای فرمان در کارساز

یک فرمان پوسته را در درون کارساز از طریق کارساز مهمان QEMU اجرا می‌کند و منتظر پایان آن است. کارساز باید گسترش داده شده و در حال اجرا باشد ، و qemu-guest-agent باید نصب شده و در مهمان در حال اجرا باشد.

مجوز مورد نیاز: servers:exec

درخواست پارامترهای بدنه

curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/exec/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "uptime", "timeout": 30}'

{
  "stdout": " 21:14:03 up 46 days,  2:10,  0 users,  load average: 0.08, 0.03, 0.01\n",
  "stderr": "",
  "exit_code": 0,
  "timed_out": false
}

اگر فرمان هنوز در حال اجرا باشد، پاسخ timed_out را به true و exit_code را به null تنظیم می‌کند.

کدهای وضعیت پاسخ

حذف سرور

صف کارساز را برای حذف دائمی می‌سازد. کارساز بلافاصله از فهرست ناپدید می‌شود و نمی‌توان آن را بازیابی کرد.

مجوز مورد نیاز: servers:delete

curl -X DELETE "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "message": "Server deletion queued"
}

کدهای وضعیت پاسخ

کلیدهای SSH

کلیدهای عمومی SSH را در حساب خود ذخیره کنید، سپس هنگامی که کارگزار را ایجاد می‌کنید، uuids آن‌ها را به عنوان ssh_key_uuids منتقل کنید. GET کلیدهای شما را فهرست می‌کند (۲۵ کلید در هر صفحه)؛ POST یکی را اضافه می‌کند.

مجوز مورد نیاز: ssh-keys:list (GET), ssh-keys:create (POST)

درخواست پارامترهای بدنه (POST)

درخواست نمونه

curl -X POST "https://admin.vps.org/api/v1/ssh-keys/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... you@laptop"}'

import requests

url = "https://admin.vps.org/api/v1/ssh-keys/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

with open("/home/you/.ssh/id_ed25519.pub") as f:
    data = {"name": "laptop", "public_key": f.read().strip()}

response = requests.post(url, headers=headers, json=data)
print(response.status_code, response.json()["uuid"])

پاسخ نمونه

{
  "id": 19,
  "uuid": "6e1b9c52-3f8a-4d7e-a2c4-5b9d0e1f2a3c",
  "name": "laptop",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... you@laptop",
  "fingerprint": "0b:4c:9b:48:76:e7:1d:07:b9:ac:71:90:70:f7:9a:69",
  "created_at": "2026-08-23T19:16:11.547183Z",
  "last_used_at": null
}

فیلدهای پاسخ

کدهای وضعیت پاسخ

گرفتن یا حذف یک کلید SSH

GET یک کلید را با حوزه‌های بالا برمی‌گرداند. DELETE آن را از حساب شما حذف می‌کند و ۲۰۴ را بدون بدنه برمی‌گرداند. حذف یک کلید، آن را از کارسازهایی که در آن‌ها نصب شده حذف نمی‌کند. کلیدها نمی‌توانند ویرایش شوند: حذف و دوباره اضافه شوند.

مجوز مورد نیاز: ssh-keys:list (GET), ssh-keys:delete (DELETE)

curl -X DELETE "https://admin.vps.org/api/v1/ssh-keys/6e1b9c52-3f8a-4d7e-a2c4-5b9d0e1f2a3c/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

پشتیبان‌گیری و عکس‌های لحظه

ایجاد یک پشتیبان یا یک عکس هم یک عمل کارساز است:

• POST /api/v1/servers/{uuid}/backup/: API پشتیبان‌گیری
• POST /api/v1/servers/{uuid}/snapshot/: API اسنپ‌شات‌ها