واجهة REST البرمجية

أنشئ مفتاحًا من الإعدادات ← مفاتيح الواجهة البرمجية. يُعرض المفتاح بصيغته النصية مرة واحدة فقط ولا يمكن استعادته بعدها؛ ولا يُخزَّن منه بصيغة مقروءة سوى بادئته. أرسله كرمز bearer مع كل طلب.

curl https://api.namescope.dev/v1/usage \
  -H "Authorization: Bearer ns_live_..."

يحمل كل مفتاح مجموعة من النطاقات. أي طلب يحتاج نطاقًا لا يملكه المفتاح يُرفض برمز 403، لذا فإن مفتاحًا تسلّمه لتكامل للقراءة فقط لا يستطيع بدء فحص مدفوع.

يُدفع مقابل كل فحص بالأرصدة، سواء بدأته من هنا أو من تطبيق الويب. تكلفة الفحص هي مجموع الوحدات التي يشغّلها: 100 رصيد مع الوحدات الخمس الافتراضية، وأقل عند استبعاد إحداها. تمنحك خطتك رصيدًا شهريًا، والأرصدة غير المستهلكة تُرحَّل.

يُسجَّل الخصم قبل إدراج أي عمل في الطابور، لذا فإن الفحص الذي يتعذّر دفع ثمنه لا يُشغَّل ولا يترك أي سجل خلفه. وإذا أخفق الإدراج في الطابور بعد الخصم، تُعاد الأرصدة تلقائيًا.

• الرصيد غير كافٍ ← 429 مع مستند مشكلة يوضّح مقدار العجز
• خطة بلا وصول إلى الواجهة البرمجية ← 402 مع رابط للترقية
• إنفاق الأرصدة معطَّل لمساحة العمل ← 403

يدرج POST /v1/scans فحصًا في الطابور ويردّ برمز 202 فورًا. الفحص غير متزامن: تحمل الاستجابة قيمة scanId لا النتيجة.

curl -X POST https://api.namescope.dev/v1/scans \
  -H "Authorization: Bearer ns_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tion studios",
    "regions": ["TR", "EM", "US"],
    "niceClasses": [9, 41],
    "tlds": ["com", "io"],
    "modules": ["trademark", "domain", "social"]
  }'

{ "scanId": "scn_...", "totalJobs": 12, "creditsSpent": 100, "balance": 1900 }

استعلم دوريًا عن GET /v1/scans/{id} حتى تصبح قيمة status هي completed أو completed_partial. ينتهي الفحص المعتاد في أقل من دقيقة؛ استعلم مرة كل ثانية تقريبًا ووسّع الفاصل الزمني كلما طال الانتظار، كي لا يستنزف الفحص الطويل حدّ معدّل طلباتك.

curl https://api.namescope.dev/v1/scans/scn_... \
  -H "Authorization: Bearer ns_live_..."

كل مدخلة في checks هي إجابة مصدر واحد عن هدف واحد، ولها حكمها الخاص، ورابط sourceUrl الذي قُرئت منه، وطابع الوقت fetchedAt. أما كائن summary فيظهر بعد انتهاء الفحص ويحمل الدرجة، ونطاق المخاطرة، وحصيلة العلامات التجارية.

أربع نقاط نهاية مرجعية تصف ما يمكن أن يتضمنه طلب الفحص. وهي تحتاج نطاق reference:read ولا تكلّف شيئًا.

تُرسَل الأخطاء بوصفها مستندات مشكلة وفق معيار RFC 9457 بنوع المحتوى application/problem+json. يحدّد حقل type نوع الإخفاق، ويشرحه detail، ويحمل بعضها بيانات إضافية مثل upgradeUrl.

{
  "type": "https://namescope.dev/errors/quota-exceeded",
  "title": "Quota exceeded",
  "status": 429,
  "detail": "Not enough credits (balance 0, need 100). Top up or switch off a module to continue."
}

تُحسب حدود المعدّل لكل مفتاح على مدى دقيقة منزلقة، ويُبلَّغ عنها في كل استجابة، فيمكنك التراجع قبل أن يُرفض طلبك.

x-ratelimit-limit: 60
x-ratelimit-remaining: 58
x-ratelimit-reset: 41

يُقدَّم الوصف الكامل المقروء آليًا على /v1/openapi.json. وهو لا يحتاج أي مصادقة، فيمكنك توليد عميل منه قبل أن تحصل على مفتاح.