أنشئ رمزًا بأصغر نطاق صلاحيات يعمل
يتم إنشاء الرموز في اللوحة ضمن الحساب وتحمل نطاقات صلاحيات: read، write، billing. الرمز الذي يحمل write يمكنه طلب خوادم، وهذا يعني أن تسريبه يكلفك المال. أعطِ سكربت المراقبة صلاحية read فقط ولا شيء أكثر.
إعدادان جديران بالاستخدام أثناء وجودك هناك: تاريخ انتهاء الصلاحية، وتقييد المصدر الذي يثبت الرمز بالبادئة التي تعمل منها أتمتتك. كلاهما اختياري. كلاهما رخيص.
تُعرض القيمة مرة واحدة فقط، لأننا نخزن تجزئة منها بدلاً من الرمز نفسه. فقدانها يعني إنشاء رمز آخر.
export Paragon_TOKEN=...أفضل من سجل الأوامر، على جهاز يعمل دون مراقبة:
systemd-creds encrypt token.txt /etc/credstore.encrypted/paragon-tokenالاستدعاء الأول
curl -s https://paragonvps.com/api/v1/account -H "Authorization: Bearer $Paragon_TOKEN" | jq .كل شيء JSON، وكل شيء يقع تحت /api/v1، وكل استجابة تحمل ترويسة request_id. اذكر ذلك في تذكرة وسنجد الاستدعاء الدقيق خلال ثوانٍ بدلاً من سؤالك عن الوقت الذي حدث فيه ذلك.
curl -s https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" | jq -r '.[] | .id + " " + .hostname + " " + .site + " " + .state'طلب خادم
curl -s -X POST https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: 2026-07-16-edge-01" -d '{"plan":"r-8","site":"AMS-01","image":"debian-13","hostname":"edge-01","ssh_keys":["primary"]}'أرسل ترويسة Idempotency-Key. إعادة محاولة POST بدونها هي الطريقة التي ينتهي بها الأمر بشخصين وخادمين ونية واحدة؛ يتم تذكر المفتاح لمدة أربع وعشرين ساعة ويعيد النتيجة الأصلية بدلاً من بناء مثيل ثانٍ. تُرسل بيانات user-data الخاصة بـ cloud-init في نفس الجسم، مرمزة بـ base64، تحت user_data_b64.
يتم السحب من رصيد حسابك عند الطلب عندما يغطي الرصيد الدورة الأولى. وإلا يحمل الرد فاتورة وعنوان دفع، ويظهر المثيل بمجرد تسوية الفاتورة.
حدود المعدل والأخطاء
ستمائة طلب في الدقيقة لكل رمز. تجاوزها وستحصل على 429 مع ترويسة Retry-After، وهي موجودة لقراءتها بدلاً من استبدالها بنوم ثابت في حلقة.
الأخطاء هي JSON تحمل code، وmessage إنسانيًا، وrequest_id. الحالة تعطيك الفئة: 400 أرسلت شيئًا خاطئًا، 401 الرمز غير صالح أو تم إبطاله، 403 الرمز يفتقر إلى النطاق، 404 غير موجود أو ليس لك، 409 المثيل في حالة لا تسمح بذلك، و5xx من جهتنا.
الترقيم والاستطلاع
تأخذ المجموعات ?page= و?per_page= وتعيد ترويسة Link. العمليات الطويلة تعطيك وظيفة بدلاً من الحظر، وهذا يغطي الإعداد والترحيل والاستعادة:
curl -s https://paragonvps.com/api/v1/jobs/<job-id> -H "Authorization: Bearer $Paragon_TOKEN" | jq -r .stateاستطلها كل بضع ثوانٍ، أو سجل webhook وتوقف عن الاستطلاع تمامًا. Webhooks موقعة؛ تحقق من التوقيع قبل التعامل معها.
الإبطال
فوري، من اللوحة أو برمز آخر:
curl -s -X DELETE https://paragonvps.com/api/v1/tokens/<token-id> -H "Authorization: Bearer $Paragon_TOKEN"تنجز الطلبات قيد التنفيذ، ويحصل التالي على 401. إذا اشتبهت في تسريب رمز، قم بالإبطال أولاً وحقق بعد ذلك. لا يمكن للرمز تغيير بريد حسابك أو عامل المصادقة الثاني، ولكنه بالتأكيد ينفق المال.
المرجع الكامل، كل نقطة نهاية وكل حقل، موجود في /docs/api.