مرجع نقاط النهاية

KernelHost API

تُعيد كل نقاط النهاية application/json. تتبع الأخطاء RFC 7807 (Problem+JSON). كل استجابة تحمل ترويسة X-Request-Id للربط مع سجل التدقيق على الخادم.

MethodPathالنطاقالغرض
GET/v1/healthpublicفحص صحة بلا مصادقة.
GET/v1/meanyمعلومات حسابك مع بيانات وصفية لمفتاح API.
GET/v1/productsread:productsقائمة بكل المنتجات المدرجة علناً مع الأسعار.
GET/v1/products/{id}read:productsتفاصيل المنتج بما فيها خيارات التكوين.
POST/v1/orderswrite:ordersإنشاء طلبية. Idempotency-Key مطلوب.
GET/v1/orders/{id}read:ordersحالة طلبيتك.
GET/v1/servicesread:servicesقائمة بخدماتك (بصفحات).
GET/v1/services/{id}read:servicesتفاصيل خدمة من خدماتك.
GET/v1/services/{id}/credentialsread:credentialsبيانات اعتماد الخدمة (نطاق منفصل، مُسجَّل في التدقيق).
POST/v1/services/{id}/actionswrite:servicesإجراء على الخدمة: start أو stop أو reboot أو cancel (في نهاية فترة الفوترة) أو cancel_revoke.
GET/v1/services/{id}/metricsread:servicesمقاييس الخادم لخدمة تملكها (المعالج والذاكرة والشبكة).
GET/v1/services/{id}/ddos/profilesread:ddosملفات Advanced DDoS Protection المتاحة.
GET/v1/services/{id}/ddos/rulesread:ddosالقواعد الحالية لعنوان IP المحمي المخصص.
POST/v1/services/{id}/ddos/ruleswrite:ddosإضافة قاعدة حماية واحدة. يلزم Idempotency-Key.
DELETE/v1/services/{id}/ddos/rules/{rule_id}write:ddosحذف قاعدة واحدة تملكها. يلزم Idempotency-Key.
GET/v1/services/{id}/ddos/attacksread:ddosالهجمات المكتشفة على عنوان IP المحمي (Remote DDoS Protection).
GET/v1/services/{id}/ddos/attacks/{attack_id}read:ddosتفاصيل هجوم واحد: حركة المرور والتوزيعات.
GET/v1/billing/balanceread:billingالرصيد.
GET/v1/billing/invoicesread:billingقائمة فواتيرك (بصفحات).
GET/v1/billing/invoices/{id}/pdfread:billingملف PDF للفاتورة.
GET/v1/webhooksread:webhooksعنوان Webhook الحالي.
PUT/v1/webhookswrite:webhooksتعيين أو إزالة عنوان Webhook.

قواعد Advanced DDoS Protection

تتطلب هذه الواجهات خدمة Advanced DDoS Protection تابعة لحسابك. تتوفر القراءة في حالة active أو suspended، بينما تتطلب التغييرات حالة active. فعّل read:ddos للقراءة وwrite:ddos للتغييرات صراحة في مفتاح API. لا تحصل المفاتيح الحالية على صلاحيات جديدة تلقائيا. لا تتوفر إدارة الأنفاق أو قائمة السماح.

اختر app_code من كتالوج ملفات الحماية. يجب أن تكون port عددا صحيحا من 1 إلى 65535؛ مع icmp احذفها أو أرسل 0. يربط الكائن الاختياري extra_ports أسماء المنافذ المطابقة تماما للكتالوج بأرقام منافذ صحيحة؛ تستخدم الأسماء المحذوفة القيم الافتراضية للملف. يحدد الخادم البروتوكولات، لذلك لا ترسل protocol. تؤدي الحقول أو الأسماء غير المعروفة إلى HTTP 400.

GET /v1/services/{id}/ddos/profiles

{
  "data": [{
    "app_code": "rust",
    "name": "Rust",
    "default_port": 28015,
    "protocol": "UDP",
    "extra_ports": [
      {"name": "Query", "port": 28016, "protocol": "UDP"},
      {"name": "RCON", "port": 28016, "protocol": "TCP"},
      {"name": "RustPlus", "port": 28082, "protocol": "TCP"}
    ]
  }],
  "meta": {"service_id": 1234, "protection_ip": "192.0.2.10", "max_rules": 1000}
}

POST /v1/services/{id}/ddos/rules

{
  "app_code": "rust",
  "port": 28015,
  "extra_ports": {"Query": 28016, "RCON": 28016, "RustPlus": 28082}
}

يعيد POST الحالة HTTP 201 مع القاعدة المنشأة في data. يعيد GET القواعد وmeta التي تحتوي على service_id وprotection_ip وmax_rules. يستخدم DELETE جسما فارغا ويعيد HTTP 200 كما في المثال أدناه. يلزم Idempotency-Key لكل من POST وDELETE.

GET /v1/services/{id}/ddos/rules

{
  "data": [{
    "id": "example-rule-id",
    "app_code": "rust",
    "port": 28015,
    "protocol": "UDP",
    "extra_ports": [
      {"name": "Query", "port": 28016, "protocol": "UDP"},
      {"name": "RCON", "port": 28016, "protocol": "TCP"},
      {"name": "RustPlus", "port": 28082, "protocol": "TCP"}
    ]
  }],
  "meta": {"service_id": 1234, "protection_ip": "192.0.2.10", "max_rules": 1000}
}

DELETE /v1/services/{id}/ddos/rules/{rule_id}

{"data": {"id": "example-rule-id", "deleted": true}}

تتشارك اللوحة وAPI نوافذ UTC ثابتة: 10 محاولات كتابة في الدقيقة لكل حساب، و5 في الدقيقة لكل عنوان IP محمي، و200 في اليوم بتوقيت UTC لكل حساب. تحتسب المحاولات المقبولة غير الصالحة أو الفاشلة؛ ولا تحتسب إعادات الطلب الناجحة باستخدام مفتاح منع التكرار. تتشارك قراءات DDoS عبر API حد 30 طلبا في الدقيقة لكل حساب. الحد الأقصى 1000 قاعدة لكل عنوان IP محمي.

HTTP 404: خدمة غير معروفة أو لا تملكها، أو قاعدة لا تملكها أو مفقودة أو خاصة بالنظام. HTTP 409: الخدمة ليست Advanced DDoS Protection (not_supported_for_product)، أو خدمة غير نشطة أو تعارض منافذ أو تغيير متزامن. HTTP 429: بلوغ الحد، التزم بـRetry-After. HTTP 502: تعذر على خدمة الحماية إكمال الطلب. قاعدة النظام block مخفية ولا يمكن حذفها. HTTP 503: تعذر التحقق من حدود الطلبات مؤقتا، التزم بـRetry-After.

تقارير هجمات DDoS

تتطلب هذه الواجهات خدمة Remote DDoS Protection تابعة لحسابك في حالة active أو suspended، إضافة إلى الصلاحية read:ddos التي يجب تفعيلها صراحة. تعرض القائمة هجمات DDoS المكتشفة على عنوان IP المحمي للخدمة، بدءًا بالأحدث.

معاملات الاستعلام: from وto بصيغة تاريخ (YYYY-MM-DD) أو تاريخ ووقت وفق ISO 8601 مع المنطقة الزمنية (الافتراضي: آخر 30 يومًا)، وlimit من 1 إلى 100 (الافتراضي 25)، وoffset من 0 إلى 9999 (الافتراضي 0). لا تمتد الفترة أبدًا إلى أكثر من 90 يومًا في الماضي، ولا إلى ما قبل تخصيص عنوان IP المحمي لهذه الخدمة؛ ويعرض meta.from وmeta.to الفترة المستخدمة فعليًا.

GET /v1/services/{id}/ddos/attacks?from=2026-10-10

{
  "data": [{
    "id": "3f6c1a2e-9b47-4d8a-b5e2-7c0d9e4a1f63",
    "type": "ddos_attack",
    "started_at": "2026-11-07T18:34:06Z",
    "ended_at": null,
    "detected_bps": 20938227712,
    "detected_pps": 1998848,
    "source_ip_count": 341,
    "target_ip": "203.0.113.111",
    "details_available": true
  }],
  "paging": {"limit": 25, "offset": 0, "total": 1, "truncated": false},
  "meta": {"service_id": 5678, "protected_ip": "203.0.113.111", "from": "2026-10-10T00:00:00Z", "to": "2026-11-09T11:10:16Z", "retention_days": 90}
}

يحتوي كل هجوم على id (UUID) وtype (ddos_attack، أو blackhole إذا حُجب عنوان IP المستهدف مؤقتًا عبر توجيهه إلى مسار فارغ) وstarted_at وended_at (قد تكون null) وdetected_bps وdetected_pps وsource_ip_count وtarget_ip وdetails_available. تمثل detected_bps وdetected_pps المعدل لحظة الاكتشاف، وكانت التصفية قد بدأت حينها، لذلك قد تكون أقل من الذروة الواردة في التفاصيل. يحتوي paging على limit وoffset وtotal وtruncated (true إذا تضمنت الفترة أكثر من 500 هجوم)، ويحتوي meta على service_id وprotected_ip وfrom وto وretention_days (90). تُخزَّن القوائم مؤقتًا لمدة 60 ثانية.

GET /v1/services/{id}/ddos/attacks/{attack_id}

{
  "data": {
    "id": "3f6c1a2e-9b47-4d8a-b5e2-7c0d9e4a1f63",
    "type": "ddos_attack",
    "started_at": "2026-11-07T18:34:06Z",
    "ended_at": null,
    "detected_bps": 20938227712,
    "detected_pps": 1998848,
    "source_ip_count": 341,
    "target_ip": "203.0.113.111",
    "details_available": true,
    "peak_bps": 20938227712,
    "peak_pps": 1998848,
    "total_bytes": 104809201664,
    "total_packets": 81887232,
    "interval_seconds": 1,
    "traffic": [{"time": "2026-11-07T18:34:06Z", "bps": 20938227712, "pps": 1998848}],
    "protocols": [{"protocol": "UDP", "avg_bps": 695618765, "avg_pps": 65645, "bytes": 104342814720, "packets": 78774272, "bps_percent": 99.56, "pps_percent": 96.2}],
    "destination_ports": [{"port": 58675, "protocol": "UDP", "avg_bps": 695556506, "avg_pps": 65481, "bps_percent": 99.55, "pps_percent": 95.96}],
    "source_ports": [{"port": 53, "protocol": "UDP", "avg_bps": 41896312, "avg_pps": 3511, "bps_percent": 5.996, "pps_percent": 5.15}],
    "source_countries": [{"country": "MX", "avg_bps": 96051528, "avg_pps": 8656}],
    "source_ips": [{"ip": "198.51.100.7", "avg_bps": 46162248, "avg_pps": 4151, "bps_percent": 6.61, "pps_percent": 6.08}],
    "packet_sizes": [{"range": "1400-1499", "avg_bps": 374806938, "percent": 54.076}]
  },
  "meta": {"service_id": 5678, "cached": false}
}

تتضمن التفاصيل جميع حقول القائمة إضافة إلى peak_bps وpeak_pps وtotal_bytes وtotal_packets وinterval_seconds. يسرد traffic حركة مرور الهجوم الواردة لكل فترة ({time, bps, pps}) كما رصدتها شبكة التصفية، من نحو 10 دقائق قبل الاكتشاف إلى نحو 10 دقائق بعده. تحتوي التوزيعات protocols وdestination_ports وsource_ports وsource_countries وsource_ips وpacket_sizes عادةً على أكبر 5 إدخالات: avg_bps وavg_pps متوسطات على نافذة القياس، وbps_percent وpps_percent حصص نسبية. ويحتوي protocols أيضًا على bytes وpackets، ويحتوي packet_sizes على range وavg_bps وpercent. تُخزَّن التفاصيل مؤقتًا لمدة تصل إلى 15 دقيقة.

HTTP 400 validation_failed: قيمة غير صالحة أو معامل استعلام غير معروف. HTTP 404: خدمة غير معروفة أو لا تملكها، أو معرّف هجوم غير معروف، أو هجوم على عنوان IP آخر. HTTP 409 not_supported_for_product: الخدمة ليست Remote DDoS Protection (مثل Advanced DDoS Protection أو خادم). HTTP 409 service_not_active: الخدمة ليست في حالة active أو suspended. HTTP 409 protection_not_ready: لا يزال إعداد الحماية جاريًا.

مقاييس الخادم

تتطلب هذه الواجهة خدمة نشطة تابعة لحسابك والصلاحية read:services. توفر خوادم Edge Unlimited Traffic VPS بيانات المعالج والذاكرة وحركة الشبكة الواردة والصادرة (بالبت في الثانية والحزم في الثانية)، إضافة إلى حركة المرور الصادرة لكل يوم ومنذ بداية الشهر. أما خوادم Unlimited Traffic VPS العادية في مواقع أوروبا وألمانيا وفرنسا وشرق كندا والمملكة المتحدة وبولندا، فتوفر حركة الشبكة الواردة والصادرة بالبت في الثانية فقط.

معامل الاستعلام range: إحدى القيم 1h أو 6h أو 24h أو 7d أو 14d (الافتراضي 1h). تعتمد المسافة بين النقاط على الفترة: في Edge Unlimited Traffic VPS نحو 15 ثانية (1h) و20 ثانية (6h) ودقيقتان (24h) و10 دقائق (7d) و20 دقيقة (14d)، وفي Unlimited Traffic VPS العادية 5 دقائق حتى 24h و30 دقيقة مع 7d وساعتان مع 14d. ويعرض step_seconds المسافة المستخدمة في الاستجابة.

GET /v1/services/{id}/metrics?range=24h

{
  "data": {
    "service_id": 1234,
    "range": "24h",
    "step_seconds": 120,
    "available": ["cpu_percent", "memory_percent", "network_in_bps", "network_out_bps", "network_in_pps", "network_out_pps"],
    "summary": {
      "cpu_percent": {"avg": 3.1, "max": 41.7, "last": 2.9},
      "network_in_bps": {"avg": 64012.5, "max": 912345.0, "last": 60026.2}
    },
    "points": [
      {"time": "2026-11-08T11:12:00Z", "cpu_percent": 3.254, "memory_percent": 43.001, "network_in_bps": 68515.425, "network_out_bps": 650.767, "network_in_pps": 119.992, "network_out_pps": 0.775},
      {"time": "2026-11-08T11:14:00Z", "cpu_percent": 3.118, "memory_percent": 43.004, "network_in_bps": 66120.871, "network_out_bps": 702.134, "network_in_pps": 115.317, "network_out_pps": 0.825}
    ],
    "traffic": {
      "month_to_date_out_bytes": 111844510,
      "daily": [{"date": "2026-11-09", "out_bytes": 10485760, "final": false}],
      "as_of": "2026-11-09T11:00:01Z",
      "unit": "bytes",
      "direction": "outbound"
    }
  },
  "meta": {"generated_at": "2026-11-09T11:12:30Z", "cached": false, "measured_at": "server_network_interface"}
}

تُقاس القيم على واجهة الشبكة في الخادم، لذلك تعرض حركة المرور التي وصلت فعليًا إلى الخادم. تتطلب بيانات الذاكرة وكيل الضيف (guest agent) داخل الخادم. القيم التي تعذر قياسها تكون null؛ ويسرد available المقاييس التي تتوفر لها قيم مقيسة، ويعرض summary لكل منها avg وmax وlast. يحتوي traffic على حركة المرور الصادرة بالبايت لكل يوم ومنذ بداية الشهر (تصبح قيمة final هي true عند اكتمال اليوم)، ويكون null للمنتجات التي لا تحتوي على عداد لحركة المرور. تُخزَّن الاستجابات مؤقتًا من 30 ثانية (1h) حتى 10 دقائق (14d)، ويوضح meta.cached ما إذا كانت الاستجابة قد جاءت من الذاكرة المؤقتة.

HTTP 400 validation_failed: قيمة أخرى للمعامل range أو معامل استعلام غير معروف. HTTP 404: خدمة غير معروفة أو لا تملكها. HTTP 409 not_supported_for_product: لا تتوفر مقاييس لهذه الخدمة (منتجات ومواقع أخرى). HTTP 409 service_not_active: الخدمة غير نشطة.

تنطبق حدود المعدل العامة على مقاييس الخادم وتقارير الهجمات. وإضافة إلى ذلك، يقتصر جلب البيانات الذي لا يمكن الرد عليه من الذاكرة المؤقتة على 20 طلبًا في الدقيقة لكل حساب لهذه الواجهات الثلاث مجتمعة، وعند تجاوز ذلك تتلقى HTTP 429 مع Retry-After. HTTP 502 monitoring_unavailable أو reports_unavailable: مصدر البيانات غير متاح مؤقتًا، أعد المحاولة لاحقًا. HTTP 503 temporarily_unavailable مع Retry-After: طلب موازٍ يجهّز البيانات نفسها حاليًا.

غير متاح عبر API: تقارير الهجمات لخدمة Advanced DDoS Protection وللخوادم مثل Edge Unlimited Traffic VPS؛ وإحصاءات حركة المرور النظيفة أو المُسقَطة لكل عنوان IP محمي؛ وبيانات المعالج والذاكرة لخوادم Unlimited Traffic VPS العادية؛ وتسليم webhooks والتصدير بصيغة CSV.

عَدَمية الأثر

يتطلب كل من POST /v1/orders وPOST /v1/services/{id}/actions ترويسة Idempotency-Key (من 1 إلى 80 حرفًا من [A-Za-z0-9_.-]). ويرتبط هذا المفتاح بالطريقة والمسار والجسم. فإذا كررت الطلب نفسه بالمفتاح نفسه خلال ساعة واحدة، فستحصل على الاستجابة المخزّنة؛ وبعد ذلك ستتلقى الرمز 410 مع reason بقيمة replay_stale، وعليك حينها إرسال مفتاح جديد. أما استخدام المفتاح نفسه مع جسم مختلف أو على نقطة نهاية أخرى فيُرفَض بالرمز 409 idempotency_conflict.

حدود المعدل

الحدود الافتراضية: 60 طلبًا في الدقيقة (بالإضافة إلى دفعة من 20 طلبًا) و5000 طلب في اليوم لكل مفتاح، و120 طلبًا في الدقيقة لكل حساب عبر جميع مفاتيحه، و600 طلب في الدقيقة لكل عنوان IP مصدر. وعند تجاوز أي حد، تتلقى استجابة HTTP 429 مع ترويسة Retry-After. وتُظهر ترويستا الاستجابة X-RateLimit-Remaining وX-RateLimit-Reset الحالة الراهنة لحد المفتاح.