رابط برنامه‌نویسی FLUX Monitoring

نشانی پایه و قالب پاسخ

تمام مسیرهای نسخه یک از JSON استفاده می‌کنند و با نشانی زیر آغاز می‌شوند. سند عمومی OpenAPI 3.1 قرارداد کامل و قابل خواندن برای ابزارهاست.

نشانی پایه سرویس اصلیURL

https://monitoring.fluxcdn.cloud/api/v1

احراز هویت و سطح دسترسی

توکن را از داشبورد ← تنظیمات ← API بسازید. فقط دسترسی لازم را انتخاب کنید و تاریخ انقضای مناسبی بگذارید. توکن باید در هدر Authorization ارسال شود.

سطح دسترسی	کاربرد
`account:read`	مشاهده مصرف و محدودیت‌های فضای کاری.
`monitors:read`	فهرست و جزئیات سرویس‌های تحت پایش.
`monitors:write`	ساخت، جایگزینی تنظیمات و حذف پایش.
`incidents:read`	فهرست و جزئیات رخدادها.

درخواست دارای توکنcURL

curl --request GET \
  --url https://monitoring.fluxcdn.cloud/api/v1/account \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN'

مسیرهای در دسترس

روش	مسیر	کاربرد	دسترسی
`GET`	`/account`	مصرف و محدودیت‌ها	`account:read`
`GET`	`/monitors`	فهرست پایش‌ها	`monitors:read`
`POST`	`/monitors`	ساخت پایش	`monitors:write`
`GET`	`/monitors/{id}`	جزئیات پایش	`monitors:read`
`PUT`	`/monitors/{id}`	جایگزینی تنظیمات	`monitors:write`
`DELETE`	`/monitors/{id}`	حذف پایش	`monitors:write`
`GET`	`/incidents`	فهرست رخدادها	`incidents:read`
`GET`	`/incidents/{id}`	جزئیات رخداد	`incidents:read`

صفحه‌بندی

فهرست‌ها از صفحه‌بندی مبتنی بر نشانگر استفاده می‌کنند. مقدار per_page باید بین ۱ تا ۱۰۰ باشد. اگر meta.next_cursor مقدار داشت، آن را بدون تغییر در پارامتر cursor درخواست بعدی بفرستید.

دریافت صفحه بعدcURL

curl --get \
  --url https://monitoring.fluxcdn.cloud/api/v1/monitors \
  --data-urlencode 'per_page=25' \
  --data-urlencode 'cursor=CURSOR_FROM_PREVIOUS_RESPONSE' \
  --header 'Authorization: Bearer YOUR_TOKEN'

تکرار ایمن درخواست‌های تغییردهنده

درخواست‌های POST، PUT و DELETE به هدر Idempotency-Key با طول ۸ تا ۱۰۰ نویسه نیاز دارند. در آن فقط از حرف، عدد، زیرخط، نقطه، دونقطه و خط تیره استفاده کنید. برای هر تغییر موردنظر یک کلید تازه بسازید و کلید قبلی را فقط برای تکرار دقیق همان روش، مسیر و بدنه به‌کار ببرید.

اگر درخواست نخست کامل شده باشد، پاسخ ذخیره‌شده می‌تواند دوباره برگردانده شود. استفاده از یک کلید با محتوای متفاوت، به‌جای انجام تغییر دوم و نامطمئن، پاسخ تداخل می‌دهد.

هدرهای درخواست تغییردهندهHTTP

Authorization: Bearer YOUR_TOKEN
Accept: application/json
Content-Type: application/json
Idempotency-Key: deploy-2026-08-01-0001

محدودیت درخواست و خطاها

پاسخ موفق دارای X-RateLimit-Limit و X-RateLimit-Remaining است. پاسخ 429 نیز Retry-After را بر حسب ثانیه می‌فرستد. به‌اندازه همان زمان صبر کنید و سپس با فاصله افزایشی تلاش کنید؛ درخواست‌ها را یک‌باره تکرار نکنید.

خطاها یک کد و پیام قابل فهم دارند و خطای اعتبارسنجی ممکن است جزئیات فیلدها را نیز شامل شود. 401 یعنی توکن نامعتبر یا منقضی، 403 یعنی نبود دسترسی، 404 یعنی منبع در فضای کاری توکن وجود ندارد، 409 یعنی تداخل کلید و 422 یعنی ورودی نادرست است.

فهرست بررسی اتصال امن

توکن را در کد منبع، جاوااسکریپت مرورگر، تیکت یا پیام گفت‌وگو قرار ندهید.
برای هر اتصال یک توکن جدا بسازید تا مستقل لغو شود.
کمترین سطح دسترسی و تاریخ انقضای واقعی را انتخاب کنید.
پیش از استفاده، فیلدهای پاسخ را بررسی کنید و افزودن فیلد اختیاری جدید را بپذیرید.
از HTTPS، مهلت معقول، فاصله افزایشی و کلید تکرار ایمن استفاده کنید.
اگر احتمال افشای توکن وجود دارد، همان لحظه آن را لغو کنید.