پرش به محتوای اصلی
همه چیز در حال کار است
ایران‌کلاد
ورود ثبت‌نام
آغاز محتوای اصلی
بازگشت به مستندات

vm

8 endpoint

GET /api/v1/vms scope: vm:read

List your VMs

پارامترهای Query
  • limit — Max items (1-200, default 50)
  • offset — Skip first N items
  • status — Filter by status: running|stopped|paused|suspended|creating|destroyed|failed
  • q — Case-insensitive substring match against uuid, public_ip and display_name
پاسخ‌ها
  • 200 — List of VMs
  • 401 — Missing or invalid token
  • 422 — Invalid status filter value
نمونه cURL 
curl -X GET -H "Authorization: Bearer ic_pat_…" \
  https://iranclaud.ir/api/v1/vms
POST /api/v1/vms scope: vm:create

Create a new VM

بدنه درخواست (JSON) 
{
    "plan_slug": "starter",
    "os_template_slug": "debian-12",
    "auth_mode": "password",
    "custom_password": "StrongPass123!"
}
پاسخ‌ها
  • 202 — Accepted; provisioning sync. Location header points at the new VM.
  • 422 — Validation failed (bad fields or insufficient wallet balance)
  • 503 — Hypervisor unavailable; order remains in paid_pending_provision and will be retried
نمونه cURL 
curl -X POST -H "Authorization: Bearer ic_pat_…" \
  -H "Content-Type: application/json" \
    -d '{"plan_slug":"starter","os_template_slug":"debian-12","auth_mode":"password","custom_password":"StrongPass123!"}' \
  https://iranclaud.ir/api/v1/vms
GET /api/v1/vms/{uuid} scope: vm:read

Get a VM by UUID

پارامترهای مسیر
  • uuid — VM UUID
پاسخ‌ها
  • 200 — VM detail
  • 404 — Not found (or owned by someone else)
نمونه cURL 
curl -X GET -H "Authorization: Bearer ic_pat_…" \
  https://iranclaud.ir/api/v1/vms/{uuid}
PATCH /api/v1/vms/{uuid} scope: vm:write

Update mutable VM fields (currently: display_name only)

پارامترهای مسیر
  • uuid — VM UUID
بدنه درخواست (JSON) 
{
    "display_name": "prod-api"
}
پاسخ‌ها
  • 200 — Updated VM detail
  • 404 — Not found (or owned by someone else)
  • 422 — Validation failed (display_name required or too long)
نمونه cURL 
curl -X PATCH -H "Authorization: Bearer ic_pat_…" \
  -H "Content-Type: application/json" \
    -d '{"display_name":"prod-api"}' \
  https://iranclaud.ir/api/v1/vms/{uuid}
POST /api/v1/vms/{uuid}/power/{action} scope: vm:write

Power action: start | shutdown | reboot | kill

پارامترهای مسیر
  • uuid — VM UUID
  • action — start | shutdown | reboot | kill
پاسخ‌ها
  • 200 — Action accepted (idempotent)
  • 404 — Unknown VM or unknown action
نمونه cURL 
curl -X POST -H "Authorization: Bearer ic_pat_…" \
  https://iranclaud.ir/api/v1/vms/{uuid}/power/{action}
POST /api/v1/vms/{uuid}/console scope: vm:console

Open a console session (60s TTL websocket token)

پارامترهای مسیر
  • uuid — VM UUID
پاسخ‌ها
  • 200 — Session URL + expires_at + ttl_sec
  • 503 — Console subsystem unavailable
نمونه cURL 
curl -X POST -H "Authorization: Bearer ic_pat_…" \
  https://iranclaud.ir/api/v1/vms/{uuid}/console
POST /api/v1/vms/{uuid}/security/password scope: vm:write

Change root password (audit severity=security)

پارامترهای مسیر
  • uuid — VM UUID
بدنه درخواست (JSON) 
{
    "password": "NewStrongPass123!"
}
پاسخ‌ها
  • 204 — Password set; never echoed back
نمونه cURL 
curl -X POST -H "Authorization: Bearer ic_pat_…" \
  -H "Content-Type: application/json" \
    -d '{"password":"NewStrongPass123!"}' \
  https://iranclaud.ir/api/v1/vms/{uuid}/security/password
POST /api/v1/vms/{uuid}/security/hostname scope: vm:write

Set the VM hostname (RFC1123)

پارامترهای مسیر
  • uuid — VM UUID
بدنه درخواست (JSON) 
{
    "hostname": "web-01"
}
پاسخ‌ها
  • 200 — Hostname set
نمونه cURL 
curl -X POST -H "Authorization: Bearer ic_pat_…" \
  -H "Content-Type: application/json" \
    -d '{"hostname":"web-01"}' \
  https://iranclaud.ir/api/v1/vms/{uuid}/security/hostname