پیش از شروع:
بدون توکن میتوانید فهرست API را ببینید با
curl https://iranclaud.ir/api/v1
— service-name، نسخه، docs-link، و ۱۴ گروه endpoint برمیگردد.
وارد پنل توکنها شوید و توکنی با مجوزهای موردنیاز ایجاد کنید. توکن فقط همان یکبار قابل مشاهده است — همان لحظه ذخیره کنید.
توکن را در هدر Authorization: Bearer … قرار دهید.
curl -H "Authorization: Bearer ic_pat_xxxxxxxx_yy…" \
https://iranclaud.ir/api/v1/vmsهمهٔ پاسخها در یکی از سه قالب زیر هستند:
// success (single)
{ "data": { … }, "meta": { "request_id": "req_…" } }
// success (list)
{ "data": [ … ], "meta": { "request_id": "…", "next_cursor": null, "has_more": false, "total": 7 } }
// error
{ "error": { "code": "scope_missing", "message": "…", "details": { … } },
"meta": { "request_id": "…" } }| code | HTTP | معنی |
|---|---|---|
| unauthenticated | 401 | هدر Bearer گم/خراب |
| token_invalid | 401 | توکن نامعتبر/منقضی/ابطالشده |
| scope_missing | 403 | دامنهٔ مجوز کافی نیست |
| not_found | 404 | منبع یافت نشد یا متعلق به شما نیست |
| validation_failed | 422 | بدنه نامعتبر — در details فیلدها |
| rate_limited | 429 | با Retry-After صبر کنید |
| compute_unavailable | 503 | سرویس محاسبه موقتاً در دسترس نیست |
هدرهای X-RateLimit-Remaining و Retry-After در هر پاسخ وضعیت را گزارش میکنند.