مرجع 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 هستند.
| وضعیت | کد متداول | معنی |
|---|---|---|
| 400 | validation_failed | ورودی نامعتبر |
| 401 | unauthenticated | توکن نامعتبر یا منقضی |
| 403 | forbidden | مجوز کافی نیست یا مرحله MFA لازم است |
| 404 | not_found | منبع پیدا نشد یا متعلق به حساب شما نیست |
| 409 | conflict | نام تکراری یا وضعیت ناسازگار |
| 422 | BUILD_MUST_RUN_IN_CI | باید ایمیج را در CI بسازید و سپس مستقر کنید |
| 429 | rate_limited | سقف درخواست رد شده است |
| 500 | internal_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} |
| کلید API | GET/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 عمومی خودداری کنید.