Rayno DocsRayno Cloud v2.2.0
docsapi-reference

مرجع API

احراز هویت، ساختار پاسخ‌ها، محدودیت نرخ و نمونه‌های curl.

همه درخواست‌های API با HTTPS و پیشوند نسخه‌دار ارائه می‌شوند. API عمومی کاربران و کنسول از https://api.rayno.cloud/api/v1 و API داخلی Agent از مسیر محافظت‌شده‌ی /api/v1/agent استفاده می‌کند. مسیرهای داخلی سرویس و عملیات زیرساخت بخشی از API عمومی نیستند.

احراز هویت

  • Bearer JWT برای نشست کاربر: Authorization: Bearer <access_token>
  • کلید API برای CI/CD و اتوماسیون: Authorization: Bearer psk_live_...

توکن‌های دسترسی کوتاه‌عمرند. برای تمدید از POST /api/v1/auth/refresh استفاده کنید. اگر حساب 2FA داشته باشد، ورود با چالش MFA تکمیل می‌شود.

پاسخ و خطاها

پاسخ موفق JSON است. خطاها دارای error.code و error.message هستند.

وضعیتکد متداولمعنی
400validation_failedورودی نامعتبر
401unauthenticatedتوکن نامعتبر یا منقضی
403forbiddenمجوز کافی نیست یا مرحله MFA لازم است
404not_foundمنبع پیدا نشد یا متعلق به حساب شما نیست
409conflictنام تکراری یا وضعیت ناسازگار
422BUILD_MUST_RUN_IN_CIباید ایمیج را در CI بسازید و سپس مستقر کنید
429rate_limitedسقف درخواست رد شده است
500internal_errorخطای داخلی سرور

محدودیت نرخ و صفحه‌بندی

  • ورود و درخواست کد: ۱۰ درخواست در دقیقه برای هر IP.
  • مسیرهای احراز هویت‌شده: ۱۲۰ درخواست در دقیقه برای هر کاربر.
  • فهرست‌ها limit و offset می‌پذیرند؛ limit پیش‌فرض ۵۰ و سقف آن ۲۰۰ است.
GET /api/v1/apps?limit=50&offset=0

مسیرهای عمومی

GET  /api/v1/health
GET  /api/v1/pricing/current
POST /api/v1/pricing/calculate
GET  /api/v1/public/stats

مسیرهای کاربر

گروهمسیر
حسابGET/PATCH /api/v1/user/profile
نشست‌هاGET /api/v1/auth/sessions، DELETE /api/v1/auth/sessions/{id}
کلید APIGET/POST /api/v1/user/api-keys، POST .../{id}/rotate، DELETE .../{id}
کیف پولGET /api/v1/wallet، GET /api/v1/wallet/transactions، POST /api/v1/wallet/topup
فاکتورGET /api/v1/invoices، GET /api/v1/invoices/{id}
برنامهGET/POST /api/v1/apps، GET/PATCH/DELETE /api/v1/apps/{name}
دیتابیسGET/POST /api/v1/databases، GET/PATCH/DELETE /api/v1/databases/{name}
فضای ذخیره‌سازیGET/POST /api/v1/storage/buckets، DELETE /api/v1/storage/buckets/{name}
پشتیبانGET/POST /api/v1/backups و مسیرهای دانلود/بازیابی همان منبع
پشتیبانیGET/POST /api/v1/tickets، POST /api/v1/tickets/{id}/messages
اعلانGET /api/v1/notifications و مسیرهای خواندن اعلان

ورود CLI با Device Flow

POST /api/v1/auth/cli/device
GET  /api/v1/auth/cli/device?code=...
POST /api/v1/auth/cli/device/approve
POST /api/v1/auth/cli/device/token
POST /api/v1/auth/cli/device/mfa

کنسول کد دستگاه را تایید می‌کند و CLI توکن را دریافت می‌کند. توکن را در مخزن کد قرار ندهید.

نمونه

BASE=https://api.rayno.cloud/api/v1
curl -s "$BASE/pricing/current" | jq

برای مشاهده برنامه‌های خود، درخواست را با هدر Authorization: Bearer $RAYNO_TOKEN بفرستید. کلید API را در Secretهای CI ذخیره کنید؛ از قرار دادن آن در URL یا log عمومی خودداری کنید.

آخرین به‌روزرسانی: مستندات نسخه پلتفرم (Rayno Cloud v2.2.0)مشکلی در مستندات پیدا کردید؟ تیکت بزنید