SNG Hosting API · v1

تحكّم في خوادمك من الكود الخاص بك

التشغيل والاستهلاك وعناوين IP وrDNS والترافيك والجدار الناري وحماية DDoS لكل خوادم VPS والخوادم المخصصة لدى SNG، بتوكن واحد وواجهة واحدة متّسقة.

إنشاء توكن تصفّح المرجع

الطلب

curl -X POST https://api.snghosting.com/api/v1/servers/ded_6a4b…/actions \
  -H "Authorization: Bearer $SNG_API_TOKEN" \
  -H "Idempotency-Key: 5f0c…" \
  -d '{"action":"reboot"}'

202 Accepted

{
  "data": {
    "operation": {
      "id": "6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11",
      "action": "reboot",
      "status": "running",
      "requestedAt": "2026-10-07T12:00:00.000Z"
    }
  }
}

مقدمة

واجهة SNG هي API بصيغة JSON عبر HTTPS. كل المسارات تحت العنوان الأساسي أدناه، وكل رد يحتوي إما data أو error، ولا يجتمعان أبدًا.

كل ما تستطيع فعله في لوحة التحكم لخادم وشبكته وحماية DDoS متاح هنا، وبنفس فحوصات الملكية: التوكن لا يرى إلا خوادم الحساب الذي أنشأه.

العنوان الأساسيhttps://api.snghosting.com/api/v1

البداية السريعة

افتح API و MCP في لوحة تحكم SNG وأنشئ توكن وصول شخصي، واختر فقط الصلاحيات التي يحتاجها تكاملك.
انسخ التوكن؛ تعرضه SNG مرة واحدة ولا تحفظ إلا بصمته المشفّرة.
استدعِ GET /connect للتأكد من أن التوكن يعمل، ثم GET /servers لعرض خوادمك.

curl "https://api.snghosting.com/api/v1/servers" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/servers", {
  headers: { Authorization: `Bearer ${process.env.SNG_API_TOKEN}` },
});
const { data: servers } = await response.json();

import os, requests

servers = requests.get(
    "https://api.snghosting.com/api/v1/servers",
    headers={"Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}"},
    timeout=30,
).json()["data"]

$ch = curl_init("https://api.snghosting.com/api/v1/servers");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SNG_API_TOKEN")],
]);
$servers = json_decode(curl_exec($ch), true)["data"];

المصادقة

أرسل التوكن في ترويسة Authorization مع كل طلب: Authorization: Bearer sng_pat_v1_….

للتوكن تاريخ انتهاء (30 يومًا افتراضيًا و90 كحد أقصى)، ويمكن إلغاؤه في أي وقت. يمكنك حصره في حتى عشرة عناوين IP، وتوكنات الموزعين تتطلب قائمة عناوين دائمًا.

لا تضع التوكن أبدًا في كود الواجهة الأمامية أو في مستودع عام. إن تسرّب، ألغِه من لوحة التحكم وسيُرفض أول طلب بعدها.

الصلاحيات

لكل توكن صلاحيات محددة. أي طلب خارجها يُرفض بالرمز insufficient_scope، ولا توجد صلاحية تمنح كل شيء.

الصلاحية	تسمح بـ
`servers:read`	عرض الخوادم وتفاصيلها واستهلاكها وحالة العمليات.
`servers:power`	تشغيل الخوادم وإعادة تشغيلها.
`servers:control`	إيقاف الخوادم وفصل تشغيلها وإعادة ضبطها من العتاد. تُستخدم مع servers:power.
`network:read`	عرض عناوين IP وrDNS والترافيك وحماية DDoS والهجمات وقواعد الفلترة وجدار VPS الناري.
`network:write`	تعديل rDNS ووصف عناوين IP ووضع حماية DDoS وجدار VPS الناري.

الطلبات والردود

أرسل JSON مع Content-Type: application/json، والحد الأقصى لحجم الجسم 10 كيلوبايت.

معرّفات الخوادم بالشكل vps_1_4021 أو ded_<uuid>. خذها من GET /servers ولا تبنِها بنفسك.

كل رد يحمل ترويسة X-Request-Id؛ أرفقها عند تواصلك مع الدعم.

أوامر لا تتكرر

كل طلب يغيّر شيئًا يحتاج ترويسة Idempotency-Key: قيمة فريدة من 8 إلى 128 حرفًا لكل أمر تقصده، مثل UUID.

إن انقطع الاتصال وأعدت المحاولة بنفس المفتاح، تُرجع SNG النتيجة الأولى (مع Idempotent-Replayed: true) بدل إعادة تشغيل الخادم مرتين. واستخدام المفتاح نفسه بجسم مختلف يُرفض بالرمز idempotency_key_reused.

الأوامر تُنفَّذ في الخلفية. الرد 202 يحتوي عملية؛ تابعها عبر GET /servers/{serverId}/operations/{operationId} حتى تصبح succeeded أو failed أو timed_out أو outcome_unknown. لا تعلن الواجهة النجاح قبل أن يؤكده الخادم.

حدود الطلبات

لكل توكن 120 طلبًا و10 أوامر في الدقيقة، وللحساب 300 طلب في الدقيقة عبر كل توكناته. كل رد يوضّح أضيق حد ينطبق عليه:

`RateLimit-Limit`	عدد الطلبات المسموح بها في الفترة.
`RateLimit-Remaining`	الطلبات المتبقية في الفترة.
`RateLimit-Reset`	الثواني المتبقية حتى تتجدد الفترة.
`Retry-After`	مع 429 فقط: الثواني التي تنتظرها قبل إعادة المحاولة.

البيانات الحيّة والمخزّنة

قراءات الشبكة والبنية التحتية تُخزَّن لثوانٍ وتُشارك بين الطلبات، فيبقى الاستعلام المتكرر سريعًا ولا يبطئ أحدًا.

إن تعذّرت البيانات الحيّة لحظيًا، تُرجع الواجهة آخر قيمة صحيحة مع meta.stale: true وmeta.observedAt بدل الفشل. أما الرفض، مثل خادم لم يعد ملكك، فلا يُجاب أبدًا من المخزّن.

الأخطاء

الأخطاء برموز ثابتة يمكنك الاعتماد عليها في الكود، أما الرسالة فهي للقراءة وقد تتغير.

Error

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API token does not have the network:read scope.",
    "requestId": "req_8f2kQ1mZx0aLr3Ts"
  }
}

HTTP	الرمز	المعنى
400	`validation_failed`	الجسم أو أحد المعاملات غير صالح، و`fields` يوضّح كل مشكلة.
400	`idempotency_key_required`	أُرسل طلب تعديل بدون Idempotency-Key.
401	`unauthorized`	التوكن مفقود أو غير صالح أو منتهٍ أو ملغى.
403	`insufficient_scope`	التوكن لا يملك الصلاحية المطلوبة.
403	`ip_not_allowed`	الطلب من عنوان لا يسمح به التوكن.
403	`primary_owner_required`	الخادم مُشارَك معك؛ وحده مالكه يستطيع تعديله.
404	`not_found`	الخادم أو العنوان أو العملية غير موجودة في هذا الحساب.
409	`action_unsupported`	نوع الخادم لا يدعم هذا الطلب.
409	`idempotency_request_in_progress`	طلب بهذا المفتاح ما زال قيد التنفيذ.
422	`idempotency_key_reused`	المفتاح استُخدم من قبل لطلب مختلف.
423	`service_locked`	الخدمة موقوفة أو مقفلة.
429	`rate_limited`	طلبات كثيرة؛ انتظر مدة Retry-After.
502	`action_failed`	أبلغ الخادم أن الأمر فشل.
503	`outcome_unknown`	أُرسل الأمر لكن تعذّر تأكيد نتيجته؛ تحقّق من الخادم قبل إعادة المحاولة.
503	`temporarily_unavailable`	حاول مجددًا بعد قليل.
504	`action_timeout`	لم يؤكد الخادم الأمر في الوقت المحدد.

مرجع الـ API

الحساب

اختبار التوكن

GET/connect

الصلاحية أي توكن صالح

يتأكد أن التوكن يعمل ويعرض صلاحياته. لا يحتاج صلاحية.

الرد `200`

`accountId` integer
`token` object
`token.name` string
`token.type` string	`personal_token` `reseller_token`
`token.scopes` string[]
`sourceIp` string
`apiVersion` string	`v1`

الأخطاء

400 401 403 404 429

curl -X GET "https://api.snghosting.com/api/v1/connect" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/connect", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/connect",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/connect");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "accountId": 0,
    "token": {
      "name": "game-01",
      "type": "personal_token",
      "scopes": [
        "string"
      ]
    },
    "sourceIp": "198.51.100.7",
    "apiVersion": "v1"
  }
}

الخوادم

عرض الخوادم

GET/servers

الصلاحية servers:read

كل خوادم VPS وVDS والمخصصة في الحساب، بما فيها المُشارَكة معك.

الرد `200`

`id` string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`type` string	`vps` `vds` `dedicated`
`name` string
`hostname` string أو null
`status` string	حالة الخدمة. الأوامر لا تُقبل إلا في حالة `active`. `active` `provisioning` `building` `suspended` `failed` `terminated`
`power` string	`running` `stopped` `unknown`
`ipv4` string[]
`ipv6` string[]
`os` string أو null
`resources` object
`resources.cpuCores` number أو null
`resources.memoryMb` number أو null
`resources.storageGb` number أو null
`resources.trafficGb` number أو null	الترافيك الشهري المسموح؛ null إن كان غير محدود.
`accessRole` string	`secondary` تعني أن الخادم مُشارَك مع هذا الحساب: قراءة فقط. `primary` `secondary`
`serviceId` integer أو null	رقم الخدمة في فوترة SNG.
`createdAt` string أو null	وقت بصيغة ISO 8601.

الأخطاء

400 401 403 404 429

curl -X GET "https://api.snghosting.com/api/v1/servers" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/servers", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/servers",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": [
    {
      "id": "vps_1_4021",
      "type": "vps",
      "name": "game-01",
      "hostname": "game-01.example.com",
      "status": "active",
      "power": "running",
      "ipv4": [
        "string"
      ],
      "ipv6": [
        "string"
      ],
      "os": "Ubuntu 24.04",
      "resources": {
        "cpuCores": 0,
        "memoryMb": 0,
        "storageGb": 0,
        "trafficGb": 0
      },
      "accessRole": "primary",
      "serviceId": null,
      "createdAt": "2026-10-07T12:00:00.000Z"
    }
  ]
}

تفاصيل خادم

GET/servers/{serverId}

الصلاحية servers:read

تشمل أوامر التشغيل التي يستطيع هذا التوكن تنفيذها الآن وأي أمر قيد التنفيذ.

المعاملات

serverId مسار · مطلوب

string

معرّف الخادم من GET /servers، مثل vps_1_4021 أو ded_<uuid>.

الرد `200`

`id` string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`type` string	`vps` `vds` `dedicated`
`name` string
`hostname` string أو null
`status` string	حالة الخدمة. الأوامر لا تُقبل إلا في حالة `active`. `active` `provisioning` `building` `suspended` `failed` `terminated`
`power` string	`running` `stopped` `unknown`
`ipv4` string[]
`ipv6` string[]
`os` string أو null
`resources` object
`resources.cpuCores` number أو null
`resources.memoryMb` number أو null
`resources.storageGb` number أو null
`resources.trafficGb` number أو null	الترافيك الشهري المسموح؛ null إن كان غير محدود.
`accessRole` string	`secondary` تعني أن الخادم مُشارَك مع هذا الحساب: قراءة فقط. `primary` `secondary`
`serviceId` integer أو null	رقم الخدمة في فوترة SNG.
`createdAt` string أو null	وقت بصيغة ISO 8601.
`actions` string[]	أوامر التشغيل التي يستطيع هذا التوكن تنفيذها على الخادم الآن. `start` `shutdown` `power_off` `reboot` `reset`
`currentOperation` object أو null
`currentOperation.id` string
`currentOperation.serverId` string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`currentOperation.action` string
`currentOperation.status` string	`outcome_unknown` تعني أن الطلب أُرسل لكن تعذّر تأكيد نتيجته؛ تحقّق من حالة الخادم قبل إعادة المحاولة. `queued` `running` `succeeded` `failed` `timed_out` `outcome_unknown`
`currentOperation.message` string أو null
`currentOperation.requestedAt` string أو null	وقت بصيغة ISO 8601.
`currentOperation.completedAt` string أو null	وقت بصيغة ISO 8601.

الأخطاء

400 401 403 404 429

curl -X GET "https://api.snghosting.com/api/v1/servers/vps_1_4021" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/servers/vps_1_4021", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/servers/vps_1_4021",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/vps_1_4021");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "id": "vps_1_4021",
    "type": "vps",
    "name": "game-01",
    "hostname": "game-01.example.com",
    "status": "active",
    "power": "running",
    "ipv4": [
      "string"
    ],
    "ipv6": [
      "string"
    ],
    "os": "Ubuntu 24.04",
    "resources": {
      "cpuCores": 0,
      "memoryMb": 0,
      "storageGb": 0,
      "trafficGb": 0
    },
    "accessRole": "primary",
    "serviceId": null,
    "createdAt": "2026-10-07T12:00:00.000Z",
    "actions": [
      "start"
    ],
    "currentOperation": {
      "id": "q48211",
      "serverId": "vps_1_4021",
      "action": "reboot",
      "status": "queued",
      "message": null,
      "requestedAt": "2026-10-07T12:00:00.000Z",
      "completedAt": null
    }
  }
}

الاستهلاك

GET/servers/{serverId}/metrics

الصلاحية servers:read

المعالج والذاكرة والقرص والترافيك الشهري. الخوادم المخصصة تُبلغ عن الاستهلاك عبر وكيل SNG.

المعاملات

serverId مسار · مطلوب

string

معرّف الخادم من GET /servers، مثل vps_1_4021 أو ded_<uuid>.

الرد `200`

`sampledAt` string أو null	وقت بصيغة ISO 8601.
`cpuPercent` number أو null
`memory` object أو null
`memory.totalBytes` number
`memory.usedBytes` number
`memory.usagePercent` number أو null
`storage` object[]
`storage.mount` string
`storage.totalBytes` number
`storage.usedBytes` number
`storage.usagePercent` number أو null
`bandwidth` object أو null	الترافيك المستخدم في شهر الفوترة الحالي، إن أبلغ عنه الخادم.
`bandwidth.usedBytes` number
`bandwidth.limitBytes` number أو null

الأخطاء

400 401 403 404 429

curl -X GET "https://api.snghosting.com/api/v1/servers/vps_1_4021/metrics" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/servers/vps_1_4021/metrics", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/servers/vps_1_4021/metrics",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/vps_1_4021/metrics");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "sampledAt": "2026-10-07T12:00:00.000Z",
    "cpuPercent": 0,
    "memory": {
      "totalBytes": 0,
      "usedBytes": 0,
      "usagePercent": 0
    },
    "storage": [
      {
        "mount": "/",
        "totalBytes": 0,
        "usedBytes": 0,
        "usagePercent": 0
      }
    ],
    "bandwidth": {
      "usedBytes": 0,
      "limitBytes": 0
    }
  }
}

تنفيذ أمر تشغيل

POST/servers/{serverId}/actions

الصلاحية servers:power

start وreboot يحتاجان servers:power، وshutdown وpower_off وreset تحتاج أيضًا servers:control. يبدأ الأمر ويُرجع عملية؛ الرد 202 يعني أنه ما زال جاريًا، فتابع GET /servers/{serverId}/operations/{operationId} حتى يصل إلى حالة نهائية. لا تعلن الواجهة النجاح قبل أن يؤكده الخادم.

المعاملات

`serverId` مسار · مطلوب string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`Idempotency-Key` ترويسة · مطلوب string	قيمة فريدة لكل أمر تقصده (8–128 حرفًا). تكرار الطلب بنفس المفتاح يُرجع النتيجة الأولى بدل تنفيذ الأمر مرة أخرى.

جسم الطلب

action

string

shutdown وreboot يطلبان ذلك من نظام التشغيل، أما power_off وreset فيعملان على العتاد فورًا.

start shutdown power_off reboot reset

الرد `202`

`operation` object
`operation.id` string
`operation.serverId` string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`operation.action` string
`operation.status` string	`outcome_unknown` تعني أن الطلب أُرسل لكن تعذّر تأكيد نتيجته؛ تحقّق من حالة الخادم قبل إعادة المحاولة. `queued` `running` `succeeded` `failed` `timed_out` `outcome_unknown`
`operation.message` string أو null
`operation.requestedAt` string أو null	وقت بصيغة ISO 8601.
`operation.completedAt` string أو null	وقت بصيغة ISO 8601.

الأخطاء

400 401 403 404 409 422 423 429 502 503 504

curl -X POST "https://api.snghosting.com/api/v1/servers/vps_1_4021/actions" \
  -H "Authorization: Bearer $SNG_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"action":"reboot"}'

const response = await fetch("https://api.snghosting.com/api/v1/servers/vps_1_4021/actions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "action": "reboot"
  }),
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.post(
    "https://api.snghosting.com/api/v1/servers/vps_1_4021/actions",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "action": "reboot"
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/vps_1_4021/actions");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => '{"action":"reboot"}',
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "operation": {
      "id": "q48211",
      "serverId": "vps_1_4021",
      "action": "reboot",
      "status": "queued",
      "message": null,
      "requestedAt": "2026-10-07T12:00:00.000Z",
      "completedAt": null
    }
  }
}

حالة عملية

GET/servers/{serverId}/operations/{operationId}

الصلاحية servers:read

المعاملات

`serverId` مسار · مطلوب string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`operationId` مسار · مطلوب string	معرّف العملية الذي يُرجعه الأمر.

الرد `200`

`id` string
`serverId` string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`action` string
`status` string	`outcome_unknown` تعني أن الطلب أُرسل لكن تعذّر تأكيد نتيجته؛ تحقّق من حالة الخادم قبل إعادة المحاولة. `queued` `running` `succeeded` `failed` `timed_out` `outcome_unknown`
`message` string أو null
`requestedAt` string أو null	وقت بصيغة ISO 8601.
`completedAt` string أو null	وقت بصيغة ISO 8601.

الأخطاء

400 401 403 404 429

curl -X GET "https://api.snghosting.com/api/v1/servers/vps_1_4021/operations/q48211" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/servers/vps_1_4021/operations/q48211", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/servers/vps_1_4021/operations/q48211",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/vps_1_4021/operations/q48211");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "id": "q48211",
    "serverId": "vps_1_4021",
    "action": "reboot",
    "status": "queued",
    "message": null,
    "requestedAt": "2026-10-07T12:00:00.000Z",
    "completedAt": null
  }
}

الشبكة

عناوين IP

GET/servers/{serverId}/ips

الصلاحية network:read

المعاملات

serverId مسار · مطلوب

string

معرّف الخادم من GET /servers، مثل vps_1_4021 أو ded_<uuid>.

الرد `200`

`address` string
`version` string	`ipv4` `ipv6`
`primary` boolean

الأخطاء

400 401 403 404 429

curl -X GET "https://api.snghosting.com/api/v1/servers/vps_1_4021/ips" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/servers/vps_1_4021/ips", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/servers/vps_1_4021/ips",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/vps_1_4021/ips");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": [
    {
      "address": "203.0.113.20",
      "version": "ipv4",
      "primary": true
    }
  ]
}

إعدادات عنوان IP

GET/servers/{serverId}/ips/{ip}

الصلاحية network:read

rDNS والوصف ووضع حماية DDoS لعنوان واحد.

المعاملات

`serverId` مسار · مطلوب string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`ip` مسار · مطلوب string · ipv4	عنوان IPv4 مخصّص للخادم.

الرد `200`

`address` string
`rdns` string أو null
`description` string أو null
`protection` object أو null	وضع حماية DDoS. `dynamic` يفلتر أثناء الهجوم فقط، و`permanent` يفلتر طوال الوقت. وفي الطبقة 7 يفلتر `only` حركة الويب فقط.
`protection.layer4` string	`dynamic` `permanent`
`protection.layer7` string	`off` `permanent` `only`
`editable` object
`editable.rdns` boolean
`editable.description` boolean
`editable.protection` boolean

الأخطاء

400 401 403 404 429 503

curl -X GET "https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "address": "203.0.113.20",
    "rdns": "mail.example.com",
    "description": "Game server",
    "protection": {
      "layer4": "dynamic",
      "layer7": "off"
    },
    "editable": {
      "rdns": true,
      "description": true,
      "protection": true
    }
  }
}

تعديل إعدادات عنوان IP

PATCH/servers/{serverId}/ips/{ip}

الصلاحية network:write

تعديل rDNS أو الوصف أو وضع حماية DDoS لعنوان خادم مخصص. تعديل واحد لكل طلب.

المعاملات

`serverId` مسار · مطلوب string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`ip` مسار · مطلوب string · ipv4	عنوان IPv4 مخصّص للخادم.
`Idempotency-Key` ترويسة · مطلوب string	قيمة فريدة لكل أمر تقصده (8–128 حرفًا). تكرار الطلب بنفس المفتاح يُرجع النتيجة الأولى بدل تنفيذ الأمر مرة أخرى.

جسم الطلب

تعديل واحد بالضبط لكل طلب: rdns أو description أو protection.

واحد من · 1
`rdns` string
واحد من · 2
`description` string
واحد من · 3
`protection` object
`protection.layer4` string	`dynamic` `permanent`
`protection.layer7` string	`off` `permanent` `only`

الرد `200`

`address` string
`rdns` string أو null
`description` string أو null
`protection` object أو null	وضع حماية DDoS. `dynamic` يفلتر أثناء الهجوم فقط، و`permanent` يفلتر طوال الوقت. وفي الطبقة 7 يفلتر `only` حركة الويب فقط.
`protection.layer4` string	`dynamic` `permanent`
`protection.layer7` string	`off` `permanent` `only`
`editable` object
`editable.rdns` boolean
`editable.description` boolean
`editable.protection` boolean

الأخطاء

400 401 403 404 409 422 423 429 503

curl -X PATCH "https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20" \
  -H "Authorization: Bearer $SNG_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"rdns":"mail.example.com"}'

const response = await fetch("https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "rdns": "mail.example.com"
  }),
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.patch(
    "https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "rdns": "mail.example.com"
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => '{"rdns":"mail.example.com"}',
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "address": "203.0.113.20",
    "rdns": "mail.example.com",
    "description": "Game server",
    "protection": {
      "layer4": "dynamic",
      "layer7": "off"
    },
    "editable": {
      "rdns": true,
      "description": true,
      "protection": true
    }
  }
}

الترافيك

GET/servers/{serverId}/traffic

الصلاحية network:read

الخوادم المخصصة تُرجع سرعات المنفذ بالـ Mbps لآخر 24 ساعة (kind: rates)، وخوادم VPS تُرجع الاستهلاك لكل شهر فوترة (kind: monthly).

المعاملات

serverId مسار · مطلوب

string

معرّف الخادم من GET /servers، مثل vps_1_4021 أو ded_<uuid>.

الرد `200`

واحد من · 1
`kind` string	`rates`
`from` string	وقت بصيغة ISO 8601.
`to` string	وقت بصيغة ISO 8601.
`totals` object أو null	حجم النقل خلال الفترة.
`totals.incomingGb` number
`totals.outgoingGb` number
`interfaces` object[]
`interfaces.incoming` object[]
`interfaces.incoming.time` string	وقت بصيغة ISO 8601.
`interfaces.incoming.mbps` number
`interfaces.outgoing` object[]
`interfaces.outgoing.time` string	وقت بصيغة ISO 8601.
`interfaces.outgoing.mbps` number
واحد من · 2
`kind` string	`monthly`
`months` object[]
`months.start` string	وقت بصيغة ISO 8601.
`months.end` string	وقت بصيغة ISO 8601.
`months.rxBytes` number
`months.txBytes` number
`months.totalBytes` number
`months.limitGb` number أو null

الأخطاء

400 401 403 404 429 503

curl -X GET "https://api.snghosting.com/api/v1/servers/vps_1_4021/traffic" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/servers/vps_1_4021/traffic", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/servers/vps_1_4021/traffic",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/vps_1_4021/traffic");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "kind": "rates",
    "from": "string",
    "to": "string",
    "totals": {
      "incomingGb": 0,
      "outgoingGb": 0
    },
    "interfaces": [
      {
        "incoming": [
          {
            "time": "string",
            "mbps": 0
          }
        ],
        "outgoing": [
          {
            "time": "string",
            "mbps": 0
          }
        ]
      }
    ]
  }
}

حماية DDoS

حماية DDoS والهجمات

GET/servers/{serverId}/ddos

الصلاحية network:read

حالة الحماية وآخر الهجمات لعنوان واحد من الخادم (العنوان الأساسي افتراضيًا).

المعاملات

`serverId` مسار · مطلوب string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`ip` استعلام string · ipv4	العنوان المراد فحصه.

الرد `200`

`address` string أو null
`status` string	`protected` `unavailable`
`incidents` object[]
`incidents.id` string
`incidents.startedAt` string	وقت بصيغة ISO 8601.
`incidents.endedAt` string أو null	وقت بصيغة ISO 8601.
`incidents.durationSeconds` number أو null
`incidents.peak` string أو null	ذروة الهجوم، مثل `12.4 Gbps`.
`incidents.attackTypes` string[]
`totalIncidents` integer
`addresses` string[]	كل عناوين الخادم التي يمكنك الاستعلام عنها بـ `ip`.

الأخطاء

400 401 403 404 429 503

curl -X GET "https://api.snghosting.com/api/v1/servers/vps_1_4021/ddos" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/servers/vps_1_4021/ddos", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/servers/vps_1_4021/ddos",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/vps_1_4021/ddos");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "address": "203.0.113.20",
    "status": "protected",
    "incidents": [
      {
        "id": "vps_1_4021",
        "startedAt": "2026-10-07T12:00:00.000Z",
        "endedAt": null,
        "durationSeconds": null,
        "peak": "12.4 Gbps",
        "attackTypes": [
          "string"
        ]
      }
    ],
    "totalIncidents": 0,
    "addresses": [
      "string"
    ]
  }
}

قواعد فلترة DDoS

GET/servers/{serverId}/ips/{ip}/ddos/rules

الصلاحية network:read

قواعد الفلترة المطبّقة على عنوان واحد من خادم مخصص.

المعاملات

`serverId` مسار · مطلوب string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`ip` مسار · مطلوب string · ipv4	عنوان IPv4 مخصّص للخادم.

الرد `200`

`address` string
`available` boolean
`rules` object[]
`rules.protocol` string
`rules.port` number
`rules.state` string

الأخطاء

400 401 403 404 429 503

curl -X GET "https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20/ddos/rules" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20/ddos/rules", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20/ddos/rules",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/ded_6a4b2a40-6d0e-4c1b-9c1d-1c7c8f3f0a11/ips/203.0.113.20/ddos/rules");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "address": "203.0.113.20",
    "available": true,
    "rules": [
      {
        "protocol": "tcp",
        "port": 30120,
        "state": "string"
      }
    ]
  }
}

الجدار الناري

مجموعات قواعد الجدار الناري

GET/firewall/rulesets

الصلاحية network:read

مجموعات القواعد التي يمكن تطبيقها على جدار VPS الناري.

الرد `200`

`id` integer
`name` string

الأخطاء

400 401 403 404 429

curl -X GET "https://api.snghosting.com/api/v1/firewall/rulesets" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/firewall/rulesets", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/firewall/rulesets",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/firewall/rulesets");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": [
    {
      "id": 0,
      "name": "game-01"
    }
  ]
}

جدار VPS الناري

GET/servers/{serverId}/firewall

الصلاحية network:read

المعاملات

serverId مسار · مطلوب

string

معرّف الخادم من GET /servers، مثل vps_1_4021 أو ded_<uuid>.

الرد `200`

`enabled` boolean
`rulesets` integer[]	معرّفات مجموعات القواعد المطبّقة.

الأخطاء

400 401 403 404 429

curl -X GET "https://api.snghosting.com/api/v1/servers/vps_1_4021/firewall" \
  -H "Authorization: Bearer $SNG_API_TOKEN"

const response = await fetch("https://api.snghosting.com/api/v1/servers/vps_1_4021/firewall", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
  },
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.get(
    "https://api.snghosting.com/api/v1/servers/vps_1_4021/firewall",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/vps_1_4021/firewall");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
    ],
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "enabled": true,
    "rulesets": [
      0
    ]
  }
}

تعديل جدار VPS الناري

PUT/servers/{serverId}/firewall

الصلاحية network:write

تشغيل الجدار الناري أو إيقافه واختيار مجموعات القواعد المطبّقة.

المعاملات

`serverId` مسار · مطلوب string	معرّف الخادم من GET /servers، مثل `vps_1_4021` أو `ded_<uuid>`.
`Idempotency-Key` ترويسة · مطلوب string	قيمة فريدة لكل أمر تقصده (8–128 حرفًا). تكرار الطلب بنفس المفتاح يُرجع النتيجة الأولى بدل تنفيذ الأمر مرة أخرى.

جسم الطلب

`enabled` اختياري boolean
`rulesets` اختياري integer[]

الرد `200`

`enabled` boolean
`rulesets` integer[]	معرّفات مجموعات القواعد المطبّقة.

الأخطاء

400 401 403 404 409 422 429

curl -X PUT "https://api.snghosting.com/api/v1/servers/vps_1_4021/firewall" \
  -H "Authorization: Bearer $SNG_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"rulesets":[3]}'

const response = await fetch("https://api.snghosting.com/api/v1/servers/vps_1_4021/firewall", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.SNG_API_TOKEN}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "enabled": true,
    "rulesets": [
      3
    ]
  }),
});
const { data, error } = await response.json();

import os, uuid, requests

response = requests.put(
    "https://api.snghosting.com/api/v1/servers/vps_1_4021/firewall",
    headers={
        "Authorization": f"Bearer {os.environ['SNG_API_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "enabled": True,
      "rulesets": [
        3
      ]
    },
    timeout=30,
)
data = response.json()

$ch = curl_init("https://api.snghosting.com/api/v1/servers/vps_1_4021/firewall");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNG_API_TOKEN"),
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => '{"enabled":true,"rulesets":[3]}',
]);
$data = json_decode(curl_exec($ch), true);

مثال على الرد

{
  "data": {
    "enabled": true,
    "rulesets": [
      0
    ]
  }
}

تحكّم في خوادمك من الكود الخاص بك

مقدمة

البداية السريعة

المصادقة

الصلاحيات

الطلبات والردود

أوامر لا تتكرر

حدود الطلبات

البيانات الحيّة والمخزّنة

الأخطاء

مرجع الـ API

الحساب

اختبار التوكن

الرد 200

الأخطاء

الخوادم

عرض الخوادم

الرد 200

الأخطاء

تفاصيل خادم

المعاملات

الرد 200

الأخطاء

الاستهلاك

المعاملات

الرد 200

الأخطاء

تنفيذ أمر تشغيل

المعاملات

جسم الطلب

الرد 202

الأخطاء

حالة عملية

المعاملات

الرد 200

الأخطاء

الشبكة

عناوين IP

المعاملات

الرد 200

الأخطاء

إعدادات عنوان IP

المعاملات

الرد 200

الأخطاء

تعديل إعدادات عنوان IP

المعاملات

جسم الطلب

الرد 200

الأخطاء

الترافيك

المعاملات

الرد 200

الأخطاء

حماية DDoS

حماية DDoS والهجمات

المعاملات

الرد 200

الأخطاء

قواعد فلترة DDoS

المعاملات

الرد 200

الأخطاء

الجدار الناري

مجموعات قواعد الجدار الناري

الرد 200

الأخطاء

جدار VPS الناري

المعاملات

الرد 200

الأخطاء

تعديل جدار VPS الناري

المعاملات

جسم الطلب

الرد 200

الأخطاء

الرد `200`

الرد `200`

الرد `200`

الرد `200`

الرد `202`

الرد `200`

الرد `200`

الرد `200`

الرد `200`

الرد `200`

الرد `200`

الرد `200`

الرد `200`

الرد `200`

الرد `200`