API سرورهای ابری

GET /api/v1/vms #

List your servers

دسترسی لازم: vm:read محدودیت نرخ: خواندن

پارامترهای Query (۴)

limit integer: اختیاری Max items, 1-200 (default 50); out-of-range values are clamped
offset integer: اختیاری Skip the first N items, 0-10000 (default 0)
status string: اختیاری Filter by status: running | stopped | paused | suspended | creating | destroyed | failed
q string: اختیاری Case-insensitive substring match against uuid, public_ip and display_name

پاسخ‌ها (۵)

200 Servers; meta.total is the count after filtering data[]: uuidstatusspecspublic_ipdisplay_namecreated_atupdated_atlive
401 unauthenticated — Authorization header missing or not "Bearer …"; token_invalid — token unknown, expired, revoked or the account is not active
403 scope_missing — the token lacks vm:read (details.required_scope)
422 validation_failed — unknown status value, or limit/offset is not an integer
429 rate_limited — read limit reached; wait Retry-After seconds (details.retry_after_sec)

نمونهٔ curl

curl

curl \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  "https://iranclaud.ir/api/v1/vms"

بازگشت به فهرست این بخش

POST /api/v1/vms #

Create a cloud server (the first hour is charged to the wallet)

دسترسی لازم: vm:create محدودیت نرخ: تغییر

فیلدهای بدنه (JSON) (۷)

plan_slug string: الزامی slug from GET /api/v1/plans
os_template_slug string: الزامی slug from GET /api/v1/os-templates
hostname string: اختیاری Optional; validated (1-63 chars a-z 0-9 -) but not applied at creation yet — set it afterwards with POST /api/v1/vms/{uuid}/security/hostname — max 63 chars; pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
auth_mode string: اختیاری one of: password | pubkey | both; default: password
custom_password string: اختیاری Optional root password: min 12 chars with at least one letter and one digit — min 12 chars
ssh_key_uuids array<string>: اختیاری uuids from GET /api/v1/account/ssh-keys
ad_hoc_pubkey string: اختیاری One OpenSSH public key that is not saved to the account

نمونهٔ بدنهٔ درخواست (JSON)

application/json

{
    "plan_slug": "mini",
    "os_template_slug": "debian-12",
    "auth_mode": "pubkey",
    "ssh_key_uuids": [
        "YOUR_SSH_KEY_UUID"
    ]
}

پاسخ‌ها (۷)

202 Created; data.uuid and the Location header point at the new server. Poll GET /api/v1/vms/{uuid} until status is running data: uuidstatusspecspublic_ipdisplay_namecreated_atupdated_atlive
401 unauthenticated — Authorization header missing or not "Bearer …"; token_invalid — token unknown, expired, revoked or the account is not active
403 scope_missing — the token lacks vm:create (details.required_scope)
422 validation_failed — bad fields (details.fields), or details.reason = insufficient_balance with details.required_irr / details.balance_irr
429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)
500 internal_error — unexpected error; send the request_id to support
503 compute_unavailable — no capacity right now. The first hour is already charged; the paid order is provisioned automatically when capacity is back (do not retry, or you create a second server)

نمونهٔ curl

curl

curl -X POST \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_slug":"mini","os_template_slug":"debian-12","auth_mode":"pubkey","ssh_key_uuids":["YOUR_SSH_KEY_UUID"]}' \
  "https://iranclaud.ir/api/v1/vms"

بازگشت به فهرست این بخش

GET /api/v1/vms/{uuid} #

Get a server

دسترسی لازم: vm:read محدودیت نرخ: خواندن

پارامترهای مسیر (۱)

uuid string: الزامی Server UUID (from GET /api/v1/vms)

پاسخ‌ها (۵)

200 Server detail (live is always null here; use /metrics for live usage) data: uuidstatusspecspublic_ipdisplay_namecreated_atupdated_atlive
401 unauthenticated — Authorization header missing or not "Bearer …"; token_invalid — token unknown, expired, revoked or the account is not active
403 scope_missing — the token lacks vm:read (details.required_scope)
404 not_found — unknown server or owned by another account
429 rate_limited — read limit reached; wait Retry-After seconds (details.retry_after_sec)

نمونهٔ curl

curl

curl \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  "https://iranclaud.ir/api/v1/vms/YOUR_UUID"

بازگشت به فهرست این بخش

PATCH /api/v1/vms/{uuid} #

Rename a server (display_name is the only writable field)

دسترسی لازم: vm:write محدودیت نرخ: تغییر

پارامترهای مسیر (۱)

uuid string: الزامی Server UUID (from GET /api/v1/vms)

فیلدهای بدنه (JSON) (۱)

display_name string | null: الزامی Max 80 characters; an empty string clears the name — max 80 chars

نمونهٔ بدنهٔ درخواست (JSON)

application/json

{
    "display_name": "prod-api"
}

پاسخ‌ها (۶)

200 Updated server data: uuidstatusspecspublic_ipdisplay_namecreated_atupdated_atlive
401 unauthenticated — Authorization header missing or not "Bearer …"; token_invalid — token unknown, expired, revoked or the account is not active
403 scope_missing — the token lacks vm:write (details.required_scope)
404 not_found — unknown server or owned by another account
422 validation_failed — display_name missing or longer than 80 characters
429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)

نمونهٔ curl

curl

curl -X PATCH \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"prod-api"}' \
  "https://iranclaud.ir/api/v1/vms/YOUR_UUID"

بازگشت به فهرست این بخش

POST /api/v1/vms/{uuid}/power/{action} #

Power action: start | shutdown | reboot | kill

دسترسی لازم: vm:write محدودیت نرخ: تغییر

پارامترهای مسیر (۲)

uuid string: الزامی Server UUID (from GET /api/v1/vms)
action string: الزامی start | shutdown (graceful) | reboot | kill (hard power-off). Any other value does not match the route (plain-text 404)

پاسخ‌ها (۷)

200 Action sent to the server data: vmaction
401 unauthenticated — Authorization header missing or not "Bearer …"; token_invalid — token unknown, expired, revoked or the account is not active
403 scope_missing — the token lacks vm:write (details.required_scope)
404 not_found — unknown server or owned by another account
409 suspended_unpaid — server suspended for an unpaid balance: start and reboot are refused (shutdown and kill stay allowed); it is started automatically after a wallet top-up
429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)
503 compute_unavailable — the server platform did not answer; retry later

نمونهٔ curl

curl

curl -X POST \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  "https://iranclaud.ir/api/v1/vms/YOUR_UUID/power/reboot"

بازگشت به فهرست این بخش

POST /api/v1/vms/{uuid}/console #

Open a web-console session (short-lived websocket URL)

دسترسی لازم: vm:console محدودیت نرخ: کنسول

پارامترهای مسیر (۱)

uuid string: الزامی Server UUID (from GET /api/v1/vms)

پاسخ‌ها (۷)

200 Session; ws_url is valid for ttl_sec seconds (60 by default) data: ws_urlexpires_atttl_sec
401 unauthenticated — Authorization header missing or not "Bearer …"; token_invalid — token unknown, expired, revoked or the account is not active
403 scope_missing — the token lacks vm:console (details.required_scope)
404 not_found — unknown server or owned by another account
409 not_supported — no web console for dedicated servers; connect with SSH
429 rate_limited — destroy limit reached; wait Retry-After seconds (details.retry_after_sec)
503 compute_unavailable — console service unavailable; retry later

نمونهٔ curl

curl

curl -X POST \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  "https://iranclaud.ir/api/v1/vms/YOUR_UUID/console"

بازگشت به فهرست این بخش

POST /api/v1/vms/{uuid}/security/password #

Set the root password

دسترسی لازم: vm:write محدودیت نرخ: تغییر

پارامترهای مسیر (۱)

uuid string: الزامی Server UUID (from GET /api/v1/vms)

فیلدهای بدنه (JSON) (۱)

password string: الزامی Min 12 characters with at least one letter and one digit — min 12 chars

نمونهٔ بدنهٔ درخواست (JSON)

application/json

{
    "password": "YOUR_NEW_PASSWORD_1"
}

پاسخ‌ها (۸)

204 Password set; never echoed back
401 unauthenticated — Authorization header missing or not "Bearer …"; token_invalid — token unknown, expired, revoked or the account is not active
403 scope_missing — the token lacks vm:write (details.required_scope)
404 not_found — unknown server or owned by another account
409 not_supported — dedicated server (change it inside the server over SSH); suspended_unpaid — server suspended for an unpaid balance
422 validation_failed — password too short or missing a letter/digit
429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)
503 compute_unavailable — the server platform did not answer; retry later

نمونهٔ curl

curl

curl -X POST \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password":"YOUR_NEW_PASSWORD_1"}' \
  "https://iranclaud.ir/api/v1/vms/YOUR_UUID/security/password"

بازگشت به فهرست این بخش

POST /api/v1/vms/{uuid}/security/hostname #

Set the server hostname

دسترسی لازم: vm:write محدودیت نرخ: تغییر

پارامترهای مسیر (۱)

uuid string: الزامی Server UUID (from GET /api/v1/vms)

فیلدهای بدنه (JSON) (۱)

hostname string: الزامی 1-63 chars a-z 0-9 -, starts and ends alphanumeric; upper case is lower-cased — max 63 chars; pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

نمونهٔ بدنهٔ درخواست (JSON)

application/json

{
    "hostname": "web-01"
}

پاسخ‌ها (۸)

200 Hostname set data: vm_uuidhostname
401 unauthenticated — Authorization header missing or not "Bearer …"; token_invalid — token unknown, expired, revoked or the account is not active
403 scope_missing — the token lacks vm:write (details.required_scope)
404 not_found — unknown server or owned by another account
409 not_supported — dedicated server (change it inside the server over SSH); suspended_unpaid — server suspended for an unpaid balance
422 validation_failed — invalid hostname
429 rate_limited — write limit reached; wait Retry-After seconds (details.retry_after_sec)
503 compute_unavailable — the server platform did not answer; retry later

نمونهٔ curl

curl

curl -X POST \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"web-01"}' \
  "https://iranclaud.ir/api/v1/vms/YOUR_UUID/security/hostname"

بازگشت به فهرست این بخش

محصولات

پشتیبانی

List your servers

Create a cloud server (the first hour is charged to the wallet)

Get a server

Rename a server (display_name is the only writable field)

Power action: start | shutdown | reboot | kill

Open a web-console session (short-lived websocket URL)

Set the root password

Set the server hostname