صيغة الرد
باستخدام DomScan API، جميع الاستجابات بصيغة JSON. تحتوي نتيجة كل نطاق على هذه الحقول المشتركة:
صيغة الرد
جميع الاستجابات بصيغة JSON. تحتوي نتيجة كل نطاق على هذه الحقول المشتركة:
domain- اسم النطاق الكاملavailable- حالة التوفر المنطقيةsource- "rdap" or "cache"checked_at- ISO 8601 timestamperror- موجود عند حدوث خطأ
بيانات الاستجابة الوصفية
تتضمن كل استجابة من API معرّف طلب وقيمة للحداثة. عند توفرها، تعرض رؤوس الاستجابة أيضًا الأرصدة المطلوبة والمحصّلة والمستردة والمتبقية، بالإضافة إلى خطة حد المعدل الخاصة بك، والحد، والسعة المتبقية، والسياسة. تعني قيمة الحداثة unknown تعذر تحديد حداثة تلك الاستجابة. ولا تعني أن البيانات حديثة.
اختيار الحقول والاستجابات المضغوطة
أضف fields أو compact إلى سلسلة الاستعلام في أي طلب GET أو POST لتحصل على استجابة JSON أصغر. كلاهما اختياري. في طلبات POST يوضعان في سلسلة الاستعلام لا في جسم الطلب. لا يغيّر أي منهما تكلفة الأرصدة.
اختيار الحقول
يقبل fields مسارات منقوطة مفصولة بفواصل، مثل fields=domain,classification.status,records.data. عندما يعبر المسار قائمة، يُطبَّق على كل عنصر فيها. تحتفظ العناصر بمواضعها، ويتحول العنصر الذي لا يحتوي على أي حقل محدد إلى {}. وتبقى القيمة null الواقعة على المسار كما هي null.
أرسل ما يصل إلى 50 مساراً، لكل منها حتى 6 أجزاء، وكل جزء من 1 إلى 64 حرفاً أو رقماً أو شرطة سفلية. أي قيمة أخرى تعيد الخطأ 400 INVALID_PARAMETER قبل تنفيذ الطلب، ولذلك لا تُحتسب أي رسوم.
المسارات التي لا تطابق أي شيء في الاستجابة تُستبعد وتُدرج في ترويسة الاستجابة X-Fields-Ignored، بحد أقصى 20 مساراً.
الاستجابات المضغوطة
يزيل compact=true العناصر التالية فقط، وعلى المستوى الأعلى من الاستجابة فقط:
- في الكائن
meta: المفتاحserved_byومفاتيح الأزمنةduration_msوquery_time_msوtotal_msوtotal_time_msوlatency_msوgeneration_msوcheck_duration_ms. يُزال الكائنmetaنفسه عندما لا يتبقى فيه شيء آخر. warningsوcaveatsوnotesوerrorsعندما تكون قوائم فارغة.request_idعندما يكرر قيمة الترويسةX-Request-Id.
لا تُزال أبداً حقول البيانات ولا classification ولا الكائنات المتداخلة ولا عناصر القوائم. عند إرسال المعاملين معاً يُنفَّذ compact أولاً ثم fields.
تُعاد صياغة استجابات JSON الناجحة فقط. تُعاد استجابات الأخطاء واستجابات CSV والنصوص والبث المتدفق وتقديرات dry_run دون تغيير. تُرسل الاستجابات المعاد صياغتها بلا مسافات بادئة.
عند استخدام Idempotency-Key، يصبح fields وcompact جزءاً من الطلب. تعيد إعادة المحاولة بالقيم نفسها الاستجابة المخزنة المعاد صياغتها. أما إعادة استخدام المفتاح بقيم مختلفة فتعيد الخطأ 422 IDEMPOTENCY_KEY_REUSED.
تقبل أدوات MCP الوسيطين الاختياريين نفسيهما fields وcompact. تُدرج المسارات غير المطابقة في _meta.fields_ignored ضمن نتيجة الأداة.
مثال
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/dns?domain=google.com&type=TXT&fields=domain,status,records.data,records.ttl,owner&compact=true"
X-Fields-Ignored: owner
{
"domain": "google.com",
"records": [
{
"data": "v=spf1 include:_spf.google.com ~all",
"ttl": 300
},
{
"data": "google-site-verification=abc123",
"ttl": 300
}
],
"status": "success"
}
مفاتيح snake_case (naming)
معظم مفاتيح الاستجابة مكتوبة بنمط snake_case بالفعل، لكن بعض نقاط النهاية تُرجع بعض المفاتيح بنمط camelCase، مثل registrarName في نتائج التسعير وtldTier في عوامل التقييم وeventDate في أحداث RDAP. أضف naming=snake إلى سلسلة الاستعلام، أو أرسل الترويسة DomScan-Naming: snake، لتحصل على كل هذه المفاتيح بنمط snake_case. وبدون ذلك تحتفظ الاستجابات بمفاتيحها الحالية.
لا يتغير المفتاح إلا إذا بدأ بحرف صغير، واحتوى على أحرف وأرقام فقط، وضم حرفًا كبيرًا واحدًا على الأقل. تُضاف شرطة سفلية قبل كل كلمة جديدة ويُحوَّل المفتاح كله إلى أحرف صغيرة. وتبقى الاختصارات متصلة، ومنها IPv4 وصيغ الجمع مثل IPs: يصبح registrarName هو registrar_name، ويصبح secureDNS هو secure_dns، ويصبح ipv4Address هو ipv4_address، ويصبح nameserverIPs هو nameserver_ips.
المفاتيح التي تمثل بيانات وليست أسماء حقول تحتفظ بكتابتها كما هي، مثل أنواع سجلات DNS (A وMX) والدرجات مثل A+ وأسماء النطاقات وأسماء الترويسات وأسماء التقنيات. لا تتغير القيم أبدًا، وتُحوَّل الكائنات والقوائم المتداخلة في كل مستوى.
إذا كان الكائن يحتوي بالفعل على الاسم بنمط snake_case، كأن يوجد fooBar وfoo_bar معًا، فيحتفظ foo_bar بقيمته ويحتفظ fooBar باسمه الأصلي، فلا يضيع شيء. ولا يتغير ترتيب المفاتيح.
تكون الأولوية لمعامل الاستعلام على الترويسة، لذا يتيح naming=default إيقاف الاشتراك المفعّل عبر الترويسة لطلب واحد. القيم المقبولة هي snake وdefault. أي قيمة أخرى تُرجع الخطأ 400 INVALID_PARAMETER قبل تنفيذ الطلب، فلا يتم خصم أي رصيد. وتتضمن الاستجابات الترويسة Vary: DomScan-Naming.
يُنفَّذ naming قبل compact وfields، لذا اكتب مسارات fields بنمط snake_case، مثل fields=factors.tld_tier. استجابات الأخطاء مكتوبة بنمط snake_case أصلًا ولا تتغير أبدًا، وتكلفة الاعتمادات هي نفسها.
عند استخدام Idempotency-Key، يُعدّ اختيار التسمية جزءًا من الطلب سواء جاء من المعامل أو من الترويسة، لذا تُرجع إعادة المحاولة المفاتيح نفسها.
تقبل أدوات MCP وسيطة naming الاختيارية نفسها. ولا تقرأ استدعاءات MCP الترويسة.
curl -H "X-API-Key: $DOMSCAN_API_KEY" -H "DomScan-Naming: snake" "https://domscan.net/v1/value?domain=example.com&fields=domain,factors.tld_tier,factors.has_hyphens"
{
"domain": "example.com",
"factors": {
"tld_tier": "premium",
"has_hyphens": false
}
}
التحكم في حداثة البيانات (max_age)
تقبل نقاط النهاية التي يمكنها الرد من بيانات جرى فحصها حديثًا المعامل max_age، وهو عدد صحيح من الثواني بين 0 و2592000 (30 يومًا). تُفحص البيانات الأقدم من max_age مرة أخرى قبل إرجاعها، ويؤدي max_age=0 إلى فحص جديد دائمًا. وإذا لم تُرسل max_age، تحتفظ كل نقطة نهاية بسلوكها المعتاد.
تتضمن كل استجابة ناجحة من نقاط النهاية هذه الحقل cache_age_s في المستوى الأعلى: عمر البيانات المستخدمة بالثواني، أو 0 إذا جرى الفحص من جديد. وتُرسل القيمة نفسها في ترويسة الاستجابة X-Cache-Age. وعندما تحتوي الاستجابة على عدة عناصر، مثل فحص توفر عدة نطاقات، تكون القيمة عمر أقدم عنصر، وتحتفظ العناصر بقيمة cache_age_s الخاصة بها إن كانت تتضمنها أصلًا.
لا يغيّر max_age طريقة تصنيف النتيجة أبدًا. فالنتيجة التي تعذّر تأكيدها تبقى unknown مهما كانت حديثة، ولا تُعرض البيانات الحديثة على أنها موجودة أو غير موجودة ما لم يؤكد الفحص الأصلي ذلك.
لا يغيّر max_age تكلفة الطلب. الفحص الجديد والرد من بيانات حديثة يستهلكان الرصيد نفسه.
في /v1/status و/v1/status/bulk، تخضع عمليات الفحص الجديد الإجبارية (max_age=0) لحد لكل عميل لحماية سجلات النطاقات. وبعد بلوغ هذا الحد يُرد على الطلب كما لو لم يُرسل max_age، ويُظهر cache_age_s عمر ما استلمته. وإذا لم يكن max_age عددًا صحيحًا بين 0 و2592000، تُرجع الاستجابة 400 INVALID_PARAMETER قبل تنفيذ الطلب، فلا تُحتسب أي رسوم.
نقاط النهاية التي تقبل max_age: GET /v1/status, POST /v1/status/bulk, GET /v1/subdomains, GET /v1/certificates, GET /v1/tech, GET /v1/categorize, GET /v1/identity-assets, GET /v1/avatar, GET /v1/logo/:domain, GET /v1/brand, GET /v1/identity-resolution, GET /v1/url-intelligence, GET /v1/agent-readiness, GET /v1/robots, GET /v1/ssl/deep-scan
معاملات التخزين المؤقت القديمة
ما زالت هذه المعاملات تعمل، وأصبحت الآن أسماء بديلة مهجورة للمعامل max_age. وإذا أرسلت max_age معها، فإن max_age هو الذي يُعتمد.
| المعامل | نقاط النهاية | يعادل |
|---|---|---|
prefer_cache | /v1/status, /v1/subdomains | max_age=2592000 |
skip_cache | /v1/status, /v1/tech, /v1/categorize, /v1/identity-assets, /v1/identity-resolution, /v1/url-intelligence, /v1/agent-readiness, /v1/robots | max_age=0 |
cache_skip | /v1/status | max_age=0 |
cache-skip | /v1/status | max_age=0 |
options.prefer_cache (body) | /v1/status/bulk | max_age=2592000 |
prefer_cache (body) | /v1/status/bulk | max_age=2592000 |
options.skip_cache (body) | /v1/status/bulk | max_age=0 |
options.cache_skip (body) | /v1/status/bulk | max_age=0 |
options.cache-skip (body) | /v1/status/bulk | max_age=0 |
refresh | /v1/ssl/deep-scan | max_age=0 |
في /v1/subdomains، يحتفظ prefer_cache أيضًا بسلوك الاعتماد على التخزين المؤقت فقط: عندما لا توجد بيانات مخزنة بعد، يُرجع الطلب 202 دون أي رسوم ويبدأ البحث في الخلفية.
تقبل أدوات MCP الخاصة بنقاط النهاية هذه الوسيط الاختياري max_age نفسه، وتتضمن نتائجها cache_age_s.
ترقيم الصفحات (limit وcursor)
تقبل نقاط النهاية التي تُرجع قوائم طويلة المعاملين limit وcursor، وتتضمن كل استجابة has_more وnext_cursor. للحصول على الصفحة التالية، كرّر الطلب مع ضبط cursor على قيمة next_cursor. وفي الصفحة الأخيرة تكون قيمة has_more هي false وقيمة next_cursor هي null.
إذا لم تُرسل limit، تُرجع كل نقطة نهاية عدد العناصر نفسه كما في السابق، فلا تتغير الطلبات الحالية. ويمكنك تغيير limit من صفحة إلى أخرى.
المؤشرات (cursor) غير شفافة وموقّعة. ولا يعمل المؤشر إلا للحساب الذي تسلّمه وللاستعلام نفسه، مثل النطاق والمرشحات نفسها. وأي مؤشر جرى تعديله أو يخص حسابًا آخر أو أُرسل مع مرشحات مختلفة يُرجع 400 INVALID_CURSOR.
تتبع الصفحات ترتيبًا ثابتًا، فلا تتكرر العناصر ولا تُتخطى إذا أُضيفت أو أُزيلت بين الطلبات. وفي نقاط نهاية السجل التاريخي، تصف حقول الملخص العناصر الموجودة في الصفحة الحالية.
كل صفحة طلب عادي وتكلّف الرصيد المعتاد لنقطة النهاية، تمامًا كما كان الطلب مع limit من قبل. وتبقى نقاط النهاية المجانية مجانية.
ما زالت المعاملات القديمة تعمل: offset في /v1/email/blacklist، وpagination.next_cursor الرقمي في /v1/certificates.
| نقطة النهاية | حجم الصفحة الافتراضي | الحد الأقصى لـ limit |
|---|---|---|
GET /v1/whois/history | 50 | 100 |
GET /v1/dns/history | 100 | 1000 |
GET /v1/subdomains | 500 | 2000 |
GET /v1/certificates | 100 | 1000 |
GET /v1/watchlist | القائمة كاملة | 100 |
GET /v1/watchlist/expiring | القائمة كاملة | 100 |
GET /v1/watchlist/available | القائمة كاملة | 100 |
GET /v1/brand-monitor | القائمة كاملة | 100 |
GET /v1/email/blacklist | 1000 | 10000 |
مثال
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/whois/history?domain=example.com&limit=20"
{
"domain": "example.com",
"snapshots": [
"..."
],
"has_more": true,
"next_cursor": "eyJvIjoi..."
}
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/whois/history?domain=example.com&limit=20&cursor=eyJvIjoi..."
حالة التصنيف
تضيف نقاط النهاية التي تفيد بوجود شيء ما (تسجيل النطاقات، حسابات وسائل التواصل الاجتماعي، سجلات DNS ومصادقة البريد، وsecurity.txt وrobots.txt وخرائط الموقع، ورؤوس الأمان، وركن النطاقات، وتسجيلات انتحال الأسماء typosquat، وشهادات SSL) كائنًا باسم classification بجانب حقولها الحالية. تحتفظ الحقول الحالية باسمها ومعناها.
status- إحدى القيمpresent(موجود) أوabsent(غير موجود) أوunknown(غير معروف). لا تُعاد القيمتان present وabsent إلا عندما يقدّم الفحص دليلًا دقيقًا وموثوقًا.reason- يُعاد فقط عندما تكون الحالةunknown. ويوضّح سبب تعذّر تقديم إجابة قاطعة.evidence- مصدر الإجابة:sourceوmethodوobserved_atإضافةً إلىdetailاختياري مثلhttp_404أوnxdomain.checked_at- وقت إنشاء DomScan للتصنيف. وفي النتائج المخزّنة مؤقتًا يكونevidence.observed_atأسبق.
أسباب القيمة unknown
blocked- رفضت الجهة المستهدفة الوصول، مثلًا برمز HTTP 401 أو 403 أو بتحدّي التحقق من الروبوتات.rate_limited- طلبت منا الجهة المستهدفة أو السجل التمهّل، مثلًا برمز HTTP 429.timeout- لم ينتهِ الفحص ضمن المهلة المحددة له.ambiguous- وصلت استجابة لكنها لم تثبت الوجود ولا الغياب، مثل رمز حالة غير متوقع أو سجل مشوّه.upstream_error- فشل مصدر البيانات، مثل عطل في خادم DNS أو استجابة HTTP 5xx.unsupported- هذا الفحص غير متاح لهذا المُدخل، مثل نطاق TLD غير مدعوم أو منصة بلا أداة تحقق موثوقة.
{
"classification": {
"status": "unknown",
"reason": "rate_limited",
"evidence": {
"source": "rdap",
"method": "rdap_lookup",
"observed_at": "2026-10-10T09:30:00.000Z",
"detail": "http_429"
},
"checked_at": "2026-10-10T09:30:00.000Z"
}
}
unknown على أنها «حاول لاحقًا» وليس «غير موجود»، ولا تعتبر الغياب دليلًا على إمكانية المطالبة بالاسم.الدرجات والتقديرات مع الفحوصات المجهولة
لا تحتسب الدرجات أبدًا الفحص المجهول على أنه مفقود. تستبعد درجة أمان DNS وتقدير مصادقة البريد الفحوصات المجهولة، وتبلّغ عنها في checks_unknown، وتضبط score_confidence على partial. وعندما تكون جميع الفحوصات مجهولة، تكون الدرجة والتقدير null. ويكون تقدير SSL ودرجته null مع ضبط grade_reason على certificate_not_retrieved عندما يتعذر قراءة أي شهادة، وتبلّغ درجة السمعة عن حالة الركن المجهولة بالقيمة null بدلًا من غير مركون.