همهٔ سیستم‌ها عملیاتی‌اند
ایران‌کلاد
ورود ثبت‌نام
سرویس فعال — REST API نسخهٔ ۱

زیرساختتان را با کد مدیریت کنید

REST API ایران‌کلاد برای ساخت و مدیریت سرور ابری، فایروال، DNS‏، CDN، بکاپ، دیتابیس و فضای ذخیره‌سازی. توکن با دسترسی محدود، فایل OpenAPI 3 و مستندات فارسی با نمونهٔ curl.

ساخت توکن API مستندات API

حساب دارید؟ وارد شوید

استفاده از API رایگان است،  منابع ساخته‌شده طبق تعرفهٔ پنل از کیف پول کسر می‌شوند

درخواست نمونه · bash 
curl -X POST \
  https://iranclaud.ir/api/v1/vms \
  -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_slug": "mini",
       "os_template_slug": "debian-12"}'

پاسخ HTTP 202

{"data": {"uuid": "6b29…",
          "status": "creating"}}

معرفی

API برای مدیریت زیرساخت با کد

REST API ایران‌کلاد به شما اجازه می‌دهد سرور، فایروال، DNS‏، CDN، بکاپ، دیتابیس و کیف پول را با کد مدیریت کنید. توکن‌ها با دسترسی محدود ساخته می‌شوند تا هر اسکریپت دقیقاً به اندازهٔ نیازش اختیار داشته باشد.

این رابط برای خودکارسازی، اتصال به خط لولهٔ CI/CD و ساخت داشبورد داخلی مناسب است. نشانی پایه https://iranclaud.ir/api/v1 است و مستندات فارسی هر بخش با نمونهٔ curl در کنار آن منتشر شده است.

گروه در مرجع API
۱۸
بیش از ۱۱۰ endpoint، از سرور و DNS تا اپلیکیشن‌ها
جزئیات : گروه در مرجع API
scope مستقل
۳۰+
دسترسی دقیق برای هر توکن
جزئیات : scope مستقل
فایل مشخصات
OpenAPI 3
JSON و YAML، تولید کلاینت
جزئیات : فایل مشخصات

امکانات

ساخته‌شده برای اتوماسیون جدی

توکن با دسترسی محدود

یک توکن فقط DNS را تغییر می‌دهد، توکن دیگر فقط سرورها را می‌خواند. کمترین اختیار لازم برای هر اسکریپت.

احراز هویت Bearer

ساده و استاندارد؛ با هر کلاینت HTTP، از curl تا کلاینت تولیدشده از OpenAPI.

مشخصات OpenAPI 3

فایل JSON و YAML عمومی؛ تولید کلاینت با openapi-generator و آزمون در Postman.

سقف درخواست شفاف

در هر دقیقه ۱۲۰ خواندن، ۳۰ تغییر و ۱۰ بار باز کردن کنسول برای هر توکن؛ با هدرهای X-RateLimit-*.

انقضا و ابطال توکن

انقضای ۳۰، ۹۰ یا ۳۶۵ روزه؛ ابطال یک توکن یا همهٔ توکن‌ها با یک دکمه و نمایش آخرین استفاده.

مستندات فارسی

هر endpoint با توضیح فارسی، scope لازم و نمونهٔ curl آمادهٔ کپی، به‌اضافهٔ راهنمای شروع سریع.

ساخت سرور ابری از API

نمونهٔ کامل با کلید SSH؛ شناسهٔ پلن و سیستم‌عامل را از /api/v1/plans و /api/v1/os-templates و شناسهٔ کلید را از /api/v1/account/ssh-keys بخوانید. همهٔ فیلدها در مرجع سرورهای ابری آمده‌اند.

provision.sh 
curl -X POST https://iranclaud.ir/api/v1/vms \
  -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"]
  }'

# HTTP 202  (Location: /api/v1/vms/<uuid>)
# { "data": { "uuid": "6b29...", "status": "creating" },
#   "meta": { "request_id": "..." } }
# hostname: after creation via POST /api/v1/vms/<uuid>/security/hostname

امنیت

چرا دسترسی محدود اهمیت دارد

توکنی که به دست اشتباه بیفتد، با همان اختیاراتی که دارد کار می‌کند. با scope محدود، اگر توکن CI شما نشت کند، آسیب به همان بخش محدود می‌ماند؛ توکن استقرار DNS نمی‌تواند سرور بسازد و توکن گزارش‌گیری نمی‌تواند چیزی را تغییر دهد. حذف سرور هم اصلاً از API ممکن نیست و فقط از پنل انجام می‌شود.

بیش از ۳۰ scope مستقل وجود دارد؛ از vm:read، vm:create و vm:console تا dns:write، wallet:read، backup:write و edge:toggle. هنگام ساخت توکن دقیقاً انتخاب می‌کنید چه چیزی مجاز است و نه بیشتر. فهرست کامل scope‌ها

  • جداسازی خواندن از تغییر
  • سقف جدا برای خواندن، تغییر و کنسول
  • scope جدا برای ساخت سرور
  • نمایش آخرین استفادهٔ هر توکن

مقایسه

API یا پنل؟

ویژگی API پنل
ساخت سرور، DNS و بکاپ دارد دارد
تکرار خودکار در CI و اسکریپت دارد ندارد
دسترسی محدود به یک بخش با scope توکن دسترسی کامل حساب
حذف سرور ندارد دارد
شارژ کیف پول فقط خواندن موجودی دارد
دنبال کردن وضعیت خواندن دوره‌ای نمایش زنده در پنل

سناریو

استقرار خودکار با DNS و گزارش هزینه

تیمی پنج‌نفره نسخهٔ جدید سایت را روی سرور تازه بالا می‌آورد و پس از آزمون سلامت، اسکریپت استقرار رکورد A را با یک توکن dns:write به سرور جدید اشاره می‌دهد. یک کار زمان‌بندی‌شدهٔ دیگر هر صبح با توکن فقط‌خواندنی، موجودی کیف پول و فهرست سرورهای روشن را در کانال تیم می‌فرستد تا سرور فراموش‌شده‌ای بی‌دلیل هزینه نسازد.

  • بدون کار دستی تکراری هنگام استقرار
  • هر اسکریپت فقط با scope لازم
  • گزارش روزانهٔ هزینه با wallet:read
  • حذف سرورهای قدیمی، آگاهانه از پنل

۵ گام تا شروع

از توکن تا اولین اتوماسیون

از ساخت توکن تا اولین درخواست موفق و اتصال به CI/CD

  1. گام ۱: ساخت توکن API

    در پنل به صفحهٔ ساخت توکن بروید، یک نام توضیحی بنویسید و فقط دسترسی‌های لازم را انتخاب کنید (مثلاً vm:read و vm:create برای خواندن و ساخت سرور).

  2. گام ۲: ذخیرهٔ امن توکن

    توکن فقط یک بار نمایش داده می‌شود. آن را در متغیر محیطی IRANCLAUD_TOKEN یا بخش secrets سامانهٔ CI ذخیره کنید، نه در کد.

  3. گام ۳: آزمون اولین درخواست

    دستور curl -H "Authorization: Bearer $IRANCLAUD_TOKEN" https://iranclaud.ir/api/v1/vms باید فهرست سرورهایتان را برگرداند.

  4. گام ۴: اتصال به CI/CD

    در GitHub Actions یا GitLab CI توکن را به‌عنوان secret اضافه کنید و در اسکریپت با curl یا کلاینت تولیدشده استفاده کنید.

  5. گام ۵: تولید کلاینت از OpenAPI (اختیاری)

    با ابزار متن‌باز openapi-generator از فایل مشخصات کلاینت بسازید، مثلاً برای Go: openapi-generator-cli generate -i https://iranclaud.ir/api/openapi.json -g go -o ./client

راهنمای کامل

راهنمای کامل API ابری ایران‌کلاد

API ایران‌کلاد همان کارهایی را که در پنل انجام می‌دهید، از طریق کد در دسترس می‌گذارد. این راهنما توضیح می‌دهد API چه بخش‌هایی را پوشش می‌دهد، توکن و دسترسی‌ها چطور کار می‌کنند، پاسخ‌ها و خطاها چه شکلی دارند و کجا محدودیت دارد. برای جزئیات هر endpoint به مستندات API و برای اولین درخواست به راهنمای شروع سریع سر بزنید.

۹ بخش حدود ۴ دقیقه مطالعه

فهرست مطالب

API ابری چیست و به چه کاری می‌آید؟

API یک رابط REST روی HTTPS است که پاسخ‌هایش JSON هستند. با آن می‌توانید سرور بسازید، رکورد DNS تغییر دهید، از سرور بکاپ بگیرید یا موجودی کیف پول را بخوانید؛ بدون ورود به پنل و بدون کلیک. نشانی پایه https://iranclaud.ir/api/v1 است و همین نشانی بدون توکن هم نام سرویس، نسخه و فهرست دسته‌های اصلی را برمی‌گرداند.

کاربرد اصلی API خودکارسازی است: ساختن محیط آزمایش در خط لولهٔ CI، به‌روز کردن DNS هنگام استقرار، گزارش‌گیری روزانه از هزینه‌ها یا اتصال ایران‌کلاد به داشبورد و ابزارهای داخلی تیم. اگر فقط گاهی یک سرور می‌سازید، پنل ساده‌تر است؛ وقتی کاری را بارها تکرار می‌کنید، API وقت شما را آزاد می‌کند.

API کدام بخش‌ها را پوشش می‌دهد؟

مرجع API بیش از ۱۱۰ endpoint را در ۱۸ گروه مستند کرده است (ریشهٔ /api/v1 همین‌ها را در ۱۴ دستهٔ اصلی خلاصه می‌کند):

گروهنمونهٔ کار
سرور ابریساخت، خواندن، تغییر نام، روشن و خاموش کردن، کنسول، رمز روت و نام میزبان، متریک مصرف
ترافیک ماهانهسهمیهٔ ترافیک هر سرور و خرید بستهٔ ترافیک اضافه از کیف پول
فایروالقوانین فایروال هر سرور و گروه‌های قانون مشترک
DNSزون‌ها و رکوردها، خروجی گرفتن از زون
CDN و Edgeفهرست رکوردهای پراکسی‌شده، روشن و خاموش کردن، تنظیمات و مصرف
بکاپفهرست، ساخت، حذف و بازگردانی بکاپ سرور
دیتابیس و فضای ذخیره‌سازینمونه‌های دیتابیس، باکت‌ها و کلیدهای دسترسی
اپلیکیشن‌های مدیریت‌شدهسایت‌های وردپرس، نکست‌کلاد و مترموست: ساخت، حذف، رمز مدیر و کش
حساب، کیف پول، تیکت و فعالیتکلیدهای SSH، موجودی و تراکنش‌ها، تیکت پشتیبانی، تاریخچهٔ فعالیت
فهرست‌های عمومیپلن‌ها و سیستم‌عامل‌ها، بدون توکن

بازگشت به فهرست مطالب

توکن، انقضا و ابطال

هر درخواست، به‌جز فهرست‌های عمومی، با توکن Bearer احراز هویت می‌شود. توکن‌ها شکل ic_pat_ به‌اضافهٔ یک شناسه و بخش مخفی دارند؛ پیشوند ثابت کمک می‌کند ابزارهای اسکن کد، توکنی را که اشتباهی در مخزن کد قرار گرفته پیدا کنند. هنگام ساخت، انقضای ۳۰، ۹۰ یا ۳۶۵ روزه یا بدون انقضا انتخاب می‌کنید و توکن فقط همان یک بار نمایش داده می‌شود.

در صفحهٔ توکن‌ها زمان آخرین استفادهٔ هر توکن را می‌بینید و می‌توانید یک توکن یا همهٔ توکن‌ها را یک‌جا باطل کنید. ساخت توکن، مثل بقیهٔ کارهایی که در حساب منبع می‌سازند، پس از تأیید موبایل و احراز هویت ممکن است.

بازگشت به فهرست مطالب

دسترسی‌ها (scope): کمترین اختیار لازم

هر endpoint یک scope مشخص لازم دارد و توکن فقط کاری را انجام می‌دهد که هنگام ساخت برایش تیک زده‌اید. اسکریپت گزارش‌گیری فقط به scope‌های :read نیاز دارد؛ اسکریپت استقرار DNS فقط dns:write. اگر چنین توکنی نشت کند، آسیب به همان بخش محدود می‌ماند و نه سرورها در خطرند و نه کیف پول.

حوزهscope‌ها
سرور ابریvm:read · vm:write · vm:create · vm:console
فایروالvm:firewall:read · vm:firewall:write · firewall:read · firewall:write
DNS و CDNdns:read · dns:write · edge:read · edge:toggle
بکاپ و ترافیکbackup:read · backup:write · traffic:read · traffic:topup
حساب و کیف پولaccount:read · account:write · wallet:read
دیتابیس و ذخیره‌سازیdatabase:read · database:write · storage:read · storage:write
اپلیکیشن‌های مدیریت‌شدهwordpress:read · wordpress:write · nextcloud:read · nextcloud:write · mattermost:read · mattermost:write
تیکت و فعالیتtickets:read · tickets:write · activity:read

بازگشت به فهرست مطالب

قالب پاسخ، صفحه‌بندی و خطاها

پاسخ‌ها همیشه JSON و یکی از سه شکل‌اند: یک مورد در data، فهرست در data همراه با meta، یا خطا در error. هر پاسخ یک request_id دارد که در هدر X-Request-Id هم می‌آید؛ آن را در لاگ‌ها نگه دارید تا پیگیری با پشتیبانی سریع باشد. فهرست سرورها با limit و offset صفحه‌بندی می‌شود و فیلتر وضعیت و جست‌وجو هم دارد.

برنامهٔ خود را بر اساس error.code بنویسید، نه متن پیام. کدهایی مثل unauthenticated و token_invalid (401)، scope_missing (403)، not_found (404)، validation_failed (422) و rate_limited (429) ثابت‌اند. اگر موجودی کیف پول برای ساخت سرور کافی نباشد، پاسخ 422 با دلیل insufficient_balance می‌گیرید. فهرست کامل کدهای خطا

بازگشت به فهرست مطالب

سقف درخواست‌ها

سقف‌ها برای هر توکن و هر نوع درخواست جداگانه حساب می‌شوند؛ پنجرهٔ دقیقه‌ای سر هر دقیقه و پنجرهٔ روزانه سر هر روز (UTC) از نو شروع می‌شود.

نوع درخواستدر دقیقهدر روز
خواندن (GET)۱۲۰۵۰٬۰۰۰
تغییر (POST‏، PATCH‏، DELETE)۳۰۵٬۰۰۰
باز کردن کنسول سرور۱۰۲۰۰
مجموع همهٔ توکن‌های حساب—۱۰۰٬۰۰۰

پس از پاسخ 429، به اندازهٔ هدر Retry-After صبر کنید؛ درخواست‌های ردشده هم در شمارش حساب می‌شوند.

بازگشت به فهرست مطالب

ساخت سرور ابری با API در سه قدم

اول شناسهٔ پلن و سیستم‌عامل را از فهرست‌های عمومی /api/v1/plans و /api/v1/os-templates بخوانید؛ این دو درخواست توکن لازم ندارند. بعد با توکنی که دسترسی vm:create دارد، درخواست POST /api/v1/vms را با plan_slug و os_template_slug بفرستید و برای ورود رمز عبور، کلید SSH یا هر دو را انتخاب کنید.

پاسخ موفق کد 202 دارد و شناسهٔ سرور در data.uuid می‌آید. هزینهٔ ساعت اول همان لحظه از کیف پول کسر می‌شود. سپس وضعیت را با GET /api/v1/vms/{uuid} چند ثانیه یک بار بخوانید تا به running برسد. نرخ ساعتی هر پلن در صفحهٔ قیمت‌ها آمده است.

بازگشت به فهرست مطالب

سناریوهای رایج خودکارسازی

چند کاربرد که تیم‌ها معمولاً اول سراغشان می‌روند:

  • استقرار با DNS: اسکریپت استقرار پس از بالا آمدن نسخهٔ جدید، رکورد A را با توکنی که فقط dns:write دارد به‌روز می‌کند
  • محیط آزمایش در CI: خط لوله با vm:create سرور آزمایشی می‌سازد و پس از پایان کار، تیم آن را از پنل حذف می‌کند
  • گزارش هزینه: یک کار زمان‌بندی‌شده با wallet:read و vm:read موجودی، تراکنش‌ها و سرورهای روشن را در داشبورد داخلی می‌نویسد
  • بکاپ پیش از تغییر: پیش از به‌روزرسانی بزرگ، اسکریپت با backup:write از سرور بکاپ می‌گیرد
  • مدیریت CDN: روشن و خاموش کردن Edge Proxy برای رکوردها و خواندن مصرف ماهانه

بازگشت به فهرست مطالب

محدودیت‌های فعلی API

پیش از طراحی اتوماسیون، این محدودیت‌ها را در نظر بگیرید:

  • webhook برای رویدادها وجود ندارد؛ وضعیت را با خواندن دوره‌ای دنبال کنید
  • هدر Idempotency-Key پشتیبانی نمی‌شود؛ پیش از تکرار درخواست ساخت، فهرست را بخوانید
  • حذف سرور فقط از پنل انجام می‌شود
  • کیت توسعهٔ (SDK) رسمی منتشر نشده است؛ کلاینت را از فایل OpenAPI تولید کنید یا مستقیم با HTTP کار کنید
  • شارژ کیف پول از طریق API ممکن نیست؛ API فقط موجودی و تراکنش‌ها را می‌خواند

بازگشت به فهرست مطالب بازگشت به ابتدای راهنما

پرسش و پاسخ،  ۱۰ پرسش

سؤالات متداول دربارهٔ API

پاسخ پرسش خود را پیدا نکردید؟ با پشتیبانی در تماس باشید.

فایل OpenAPI در دسترس است؟
بله. مشخصات OpenAPI 3.0 در دو قالب /api/openapi.json و /api/openapi.yaml منتشر می‌شود و مستندات فارسی هر endpoint با مثال curl در صفحهٔ مستندات API است. همهٔ endpoint‌های مستندات در همین فایل هم آمده‌اند. با ابزارهایی مثل openapi-generator می‌توانید از همین فایل کلاینت برای زبان دلخواه (Go‏، Python‏، TypeScript و …) بسازید یا آن را در Postman وارد کنید؛ کیت توسعهٔ (SDK) رسمی جداگانه‌ای منتشر نشده است.
احراز هویت چگونه است؟
با توکن Bearer. در صفحهٔ توکن‌های API پنل، توکنی با دسترسی‌های لازم (مثلاً vm:read، vm:create، dns:write یا wallet:read) بسازید و تاریخ انقضا را ۳۰، ۹۰ یا ۳۶۵ روز یا بدون انقضا بگذارید. توکن در هدر Authorization: Bearer <token> ارسال می‌شود و فقط یک بار، هنگام ساخت، نمایش داده می‌شود.
سقف درخواست (rate limit) چقدر است؟
سقف برای هر توکن و بر اساس نوع درخواست حساب می‌شود: در هر دقیقه ۱۲۰ درخواست خواندن، ۳۰ درخواست تغییر (POST، PATCH و DELETE) و ۱۰ بار باز کردن کنسول سرور. سقف روزانه (بر پایهٔ روز UTC) هم برای هر توکن و برای مجموع توکن‌های حساب وجود دارد. هدرهای X-RateLimit-Limit و X-RateLimit-Remaining در پاسخ درخواست‌های توکن‌دار برمی‌گردند و با عبور از سقف، پاسخ 429 با هدر Retry-After می‌گیرید. جدول کامل سقف‌ها
صفحه‌بندی و فیلتر چطور کار می‌کند؟
فهرست سرورها و تراکنش‌ها با پارامتر limit (۱ تا ۲۰۰، پیش‌فرض ۵۰) و offset صفحه‌بندی می‌شوند و meta.total تعداد کل را می‌گوید؛ تیکت‌ها و گزارش فعالیت با page و per_page کار می‌کنند. فیلترهای هر endpoint در مستندات آمده‌اند؛ مثلاً فهرست سرورها با ?status=running فیلتر می‌شود و با ?q= در شناسه، IP و نام سرور جست‌وجو می‌کند.
webhook برای رویدادها وجود دارد؟
فعلاً خیر؛ API در حال حاضر webhook برای مشتری ندارد و برای دنبال کردن وضعیت از خواندن دوره‌ای استفاده کنید. مثلاً بعد از ساخت سرور، وضعیت آن را با GET /api/v1/vms/{uuid} هر چند ثانیه یک بار بخوانید تا از creating به running برسد. هر خواندن از سقف ۱۲۰ درخواست در دقیقه کم می‌کند؛ فاصلهٔ ۱۰ ثانیه کافی است.
خواندن دوره‌ای · bash 
until curl -s -H "Authorization: Bearer $IRANCLAUD_TOKEN" \
    "https://iranclaud.ir/api/v1/vms/YOUR_VM_UUID" | grep -q '"status":"running"'; do
  sleep 10
done
اگر درخواست ساخت سرور را دوباره بفرستم چه می‌شود؟
هر درخواست POST یک عملیات جدید است و API هدر Idempotency-Key را پشتیبانی نمی‌کند؛ ارسال دوباره یعنی سرور دوم و هزینهٔ دوم. اگر پاسخ به‌دلیل قطعی شبکه نرسید، قبل از تکرار، فهرست سرورها را بخوانید و ببینید سرور ساخته شده یا نه. پاسخ 503 با کد compute_unavailable هم یعنی سفارش ثبت و ساعت اول پرداخت شده و سرور پس از آزاد شدن ظرفیت خودکار ساخته می‌شود؛ آن را هم تکرار نکنید.
می‌توانم سرور را با API حذف کنم؟
در نسخهٔ فعلی خیر. با API سرور می‌سازید، مشخصات و وضعیت را می‌خوانید، تنظیمات را تغییر می‌دهید و سرور را روشن، خاموش یا راه‌اندازی دوباره می‌کنید؛ حذف سرور از پنل انجام می‌شود. این انتخاب جلوی پاک شدن ناخواستهٔ سرور با یک توکن نشت‌کرده را هم می‌گیرد.
توکن گم شد، چه کنم؟
در صفحهٔ توکن‌های API پنل، توکن قدیمی را باطل کنید و یک توکن جدید بسازید، سپس آن را در CI و کد جایگزین کنید. توکن باطل‌شده دیگر کار نمی‌کند، حتی اگر شخص دیگری آن را پیدا کند. اگر مطمئن نیستید کدام توکن نشت کرده، همهٔ توکن‌ها را با یک دکمه باطل کنید.
چطور بفهمم توکن کجا استفاده شده؟
در صفحهٔ توکن‌های API برای هر توکن زمان آخرین استفاده نمایش داده می‌شود و آخرین IP و تعداد استفاده هم ثبت می‌شود. ساخت و ابطال توکن‌ها در تاریخچهٔ فعالیت حساب می‌آید؛ توکنی که مدت‌ها استفاده نشده را باطل کنید.
استفاده از API هزینه دارد؟
خیر. خود API و توکن‌ها رایگان‌اند؛ فقط منابعی که با API می‌سازید، مثل سرور ابری یا دیتابیس، طبق همان تعرفهٔ پنل از کیف پول کسر می‌شوند. ساخت توکن مثل بقیهٔ کارهای حساب، پس از تأیید موبایل و احراز هویت ممکن است.

پاسخ پرسش خود را پیدا نکردید؟ با پشتیبانی در تماس باشید.

آماده‌اید زیرساخت را خودکار کنید؟

توکن بسازید، اولین curl را اجرا کنید و نتیجه را در پنل ببینید.

ساخت توکن API مستندات API

حساب دارید؟ وارد شوید