Yanıt biçimi

Yanıt biçimi

Tüm yanıtlar JSON biçimindedir. Her alan adı sonucu şu ortak alanları içerir:

• domain - Eksiksiz alan adı
• available - Boolean uygunluk durumu
• source - "rdap" veya "cache"
• checked_at - ISO 8601 timestamp
• error - Bir hata oluştuğunda bulunur

Yanıt meta verileri

Her API yanıtı bir istek kimliği ve veri güncelliği değeri içerir. Kullanılabilir olduğunda yanıt başlıklarında istenen, ücretlendirilen, iade edilen ve kalan kredilerin yanı sıra hız sınırı planınız, sınırınız, kalan kapasiteniz ve politikanız da gösterilir. unknown veri güncelliği değeri, bu yanıtın güncelliğinin belirlenemediği anlamına gelir. Verilerin güncel olduğu anlamına gelmez.

Alan seçimi ve kompakt yanıtlar

Daha küçük bir JSON yanıtı almak için herhangi bir GET veya POST isteğinin sorgu dizesine fields veya compact ekleyin. İkisi de isteğe bağlıdır. POST isteklerinde gövdeye değil, sorgu dizesine yazılırlar. Hiçbiri kredi maliyetini değiştirmez.

Alan seçme

fields, fields=domain,classification.status,records.data gibi virgülle ayrılmış nokta yolları alır. Bir yol bir listeden geçiyorsa her öğeye uygulanır. Öğeler konumunu korur ve seçili hiçbir alanı olmayan öğe {} olur. Bir yol boyunca karşılaşılan null değer null olarak kalır.

En fazla 50 yol gönderin; her yol, 1 ile 64 arasında harf, rakam veya alt çizgiden oluşan en fazla 6 bölüm içerebilir. Başka herhangi bir değer, istek çalışmadan önce 400 INVALID_PARAMETER döndürür, dolayısıyla hiçbir ücret alınmaz.

Yanıtta hiçbir şeyle eşleşmeyen yollar çıkarılır ve en fazla 20 yol olacak şekilde X-Fields-Ignored yanıt başlığında listelenir.

Kompakt yanıtlar

compact=true yalnızca aşağıdakileri ve yalnızca yanıtın en üst düzeyinde kaldırır:

• meta nesnesinde: served_by ile duration_ms, query_time_ms, total_ms, total_time_ms, latency_ms, generation_ms ve check_duration_ms süre anahtarları. İçinde başka bir şey kalmazsa meta nesnesinin kendisi de kaldırılır.
• Boş liste olduklarında warnings, caveats, notes ve errors.
• X-Request-Id başlığını tekrar ettiğinde request_id.

Veri alanları, classification, iç içe nesneler ve liste öğeleri asla kaldırılmaz. Her iki parametre de gönderildiğinde önce compact, ardından fields çalışır.

Yalnızca başarılı JSON yanıtları yeniden biçimlendirilir. Hata yanıtları, CSV, metin ve akış yanıtları ile dry_run tahminleri değiştirilmeden döndürülür. Yeniden biçimlendirilen yanıtlar girinti olmadan gönderilir.

Bir Idempotency-Key ile fields ve compact isteğin parçası sayılır. Aynı değerlerle yapılan yeniden deneme, saklanan ve yeniden biçimlendirilmiş yanıtı döndürür. Anahtarı farklı değerlerle yeniden kullanmak 422 IDEMPOTENCY_KEY_REUSED döndürür.

MCP araçları aynı isteğe bağlı fields ve compact argümanlarını kabul eder. Eşleşmeyen yollar, araç sonucundaki _meta.fields_ignored içinde listelenir.

Örnek

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 anahtarları (naming)

Yanıt anahtarlarının çoğu zaten snake_case biçimindedir, ancak bazı uç noktalar fiyat sonuçlarındaki registrarName, değerleme faktörlerindeki tldTier ve RDAP olaylarındaki eventDate gibi bazı anahtarları camelCase olarak döndürür. Bu anahtarların tümünü snake_case olarak almak için sorgu dizesine naming=snake ekleyin veya DomScan-Naming: snake başlığını gönderin. Bunu yapmazsanız yanıtlar mevcut anahtarlarını korur.

Bir anahtar yalnızca küçük harfle başlıyorsa, yalnızca harf ve rakam içeriyorsa ve en az bir büyük harf barındırıyorsa değişir. Her yeni sözcüğün önüne alt çizgi gelir ve anahtar küçük harfe çevrilir. Kısaltmalar bir arada kalır; buna IPv4 ve IPs gibi çoğul biçimler de dahildir: registrarName anahtarı registrar_name, secureDNS anahtarı secure_dns, ipv4Address anahtarı ipv4_address ve nameserverIPs anahtarı nameserver_ips olur.

Alan adı olmayıp veri olan anahtarlar yazımını aynen korur; örneğin A ve MX gibi DNS kayıt türleri, A+ gibi notlar, alan adları, başlık adları ve teknoloji adları. Değerler asla değiştirilmez; iç içe nesneler ve listeler her düzeyde dönüştürülür.

Bir nesnede snake_case adı zaten varsa, örneğin hem fooBar hem de foo_bar mevcutsa, foo_bar değerini korur, fooBar ise özgün adıyla kalır; böylece hiçbir şey kaybolmaz. Anahtar sırası değişmez.

Sorgu parametresi başlığa göre önceliklidir; bu nedenle naming=default, başlıkla yapılan tercihi tek bir istek için kapatır. Kabul edilen değerler snake ve default değerleridir. Başka herhangi bir değer, istek çalıştırılmadan önce 400 INVALID_PARAMETER döndürür, dolayısıyla ücret alınmaz. Yanıtlar Vary: DomScan-Naming başlığını içerir.

naming, compact ve fields işlemlerinden önce çalışır; bu yüzden fields yollarını fields=factors.tld_tier gibi snake_case olarak yazın. Hata yanıtları zaten snake_case biçimindedir ve asla değişmez; kredi maliyeti de aynıdır.

Idempotency-Key kullanıldığında, adlandırma tercihi parametreden de başlıktan da gelse isteğin bir parçasıdır; bu nedenle yeniden deneme aynı anahtarları döndürür.

MCP araçları aynı isteğe bağlı naming argümanını kabul eder. MCP çağrıları başlığı okumaz.

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
  }
}

Güncellik denetimi (max_age)

Yakın zamanda kontrol edilmiş verilerden yanıt verebilen endpoint'ler, 0 ile 2592000 (30 gün) arasında tam sayı olarak saniye alan max_age parametresini kabul eder. max_age değerinden eski veriler döndürülmeden önce yeniden kontrol edilir ve max_age=0 her zaman yeni kontrol yapar. max_age gönderilmezse her endpoint her zamanki davranışını korur.

Bu endpoint'lerin her başarılı yanıtı, en üst düzeyde bir cache_age_s alanı içerir: kullanılan verinin saniye cinsinden yaşı, veri yeni kontrol edildiyse 0. Aynı değer X-Cache-Age yanıt başlığında da gönderilir. Bir yanıt birden fazla öğe içerdiğinde, örneğin birden çok alan adı için yapılan bir kullanılabilirlik kontrolünde, bu değer en eski öğenin yaşıdır ve öğeler zaten sahip oldukları kendi cache_age_s değerlerini korur.

max_age bir sonucun nasıl sınıflandırıldığını asla değiştirmez. Doğrulanamayan bir sonuç ne kadar yeni olursa olsun unknown olarak kalır ve yakın zamanlı veriler, ilk kontrol doğrulamadıkça asla var veya yok olarak gösterilmez.

max_age bir isteğin maliyetini değiştirmez. Yeni bir kontrol ile yakın zamanlı verilerden verilen yanıt aynı krediye mal olur.

/v1/status ve /v1/status/bulk üzerinde, zorunlu yeni kontroller (max_age=0) kayıt kuruluşlarını korumak için istemci başına sınırlandırılmıştır. Bu sınırın ötesinde istek, max_age gönderilmemiş gibi yanıtlanır ve cache_age_s aldığınız verinin yaşını gösterir. 0 ile 2592000 arasında tam sayı olmayan bir max_age, istek çalıştırılmadan önce 400 INVALID_PARAMETER döndürür, bu nedenle ücret alınmaz.

max_age kabul eden endpoint'ler: 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/identity-resolution, GET /v1/url-intelligence, GET /v1/agent-readiness, GET /v1/robots, GET /v1/ssl/deep-scan

Eski önbellek parametreleri

Bu parametreler çalışmaya devam eder ve artık max_age için kullanımdan kaldırılmış takma adlardır. max_age de gönderirseniz max_age geçerli olur.

/v1/subdomains üzerinde prefer_cache yalnızca önbellek davranışını da korur: henüz hiçbir şey depolanmamışsa istek ücretlendirilmeden 202 döndürür ve aramayı arka planda başlatır.

Bu endpoint'ler için MCP araçları aynı isteğe bağlı max_age bağımsız değişkenini kabul eder ve sonuçları cache_age_s içerir.

Sayfalama (limit ve cursor)

Uzun listeler döndüren endpoint'ler limit ve cursor kabul eder ve her yanıt has_more ile next_cursor içerir. Sonraki sayfayı almak için isteği cursor değeri next_cursor olarak ayarlanmış şekilde tekrarlayın. Son sayfada has_more false, next_cursor ise null olur.

limit olmadan her endpoint daha önce olduğu kadar öğe döndürür, bu nedenle mevcut istekler değişmez. limit değerini bir sayfadan diğerine değiştirebilirsiniz.

Cursor'lar opaktır ve imzalıdır. Bir cursor yalnızca onu alan hesap için ve aynı sorgu için, örneğin aynı alan adı ve aynı filtreler için çalışır. Düzenlenmiş, başka bir hesaba ait veya farklı filtrelerle gönderilen bir cursor 400 INVALID_CURSOR döndürür.

Sayfalar sabit bir sırayı izler, bu nedenle istekler arasında eklenen veya kaldırılan öğeler tekrarlanmaz ya da atlanmaz. Geçmiş endpoint'lerinde özet alanları geçerli sayfadaki öğeleri açıklar.

Her sayfa normal bir istektir ve daha önce limit içeren bir istekte olduğu gibi endpoint'in olağan kredisine mal olur. Ücretsiz endpoint'ler ücretsiz kalır.

Eski parametreler çalışmaya devam eder: /v1/email/blacklist üzerinde offset ve /v1/certificates üzerinde sayısal pagination.next_cursor.

Örnek

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..."

Sınıflandırma durumu

Bir şeyin var olup olmadığını bildiren endpoint'ler (alan adı kaydı, sosyal medya kullanıcı adları, DNS ve e-posta kimlik doğrulama kayıtları, security.txt, robots.txt, site haritaları, güvenlik başlıkları, park durumu, typosquat kayıtları ve SSL sertifikaları) mevcut alanlarının yanına bir classification nesnesi ekler. Mevcut alanlar adlarını ve anlamlarını korur.

• status - present, absent veya unknown. Present ve absent yalnızca kontrol kesin ve güvenilir kanıt ürettiğinde döndürülür.
• reason - Yalnızca durum unknown olduğunda döndürülür. Neden kesin bir yanıt verilemediğini açıklar.
• evidence - Yanıtın nereden geldiği: source, method, observed_at ve http_404 ya da nxdomain gibi isteğe bağlı bir detail.
• checked_at - DomScan'in sınıflandırmayı ne zaman ürettiği. Önbellekten gelen sonuçlarda evidence.observed_at daha eskidir.

Unknown nedenleri

• blocked - Hedef erişimi reddetti, örneğin HTTP 401, 403 veya bir bot doğrulamasıyla.
• rate_limited - Hedef veya kayıt kuruluşu yavaşlamamızı istedi, örneğin HTTP 429 ile.
• timeout - Kontrol zaman bütçesi içinde tamamlanmadı.
• ambiguous - Bir yanıt geldi ancak varlığı ya da yokluğu kanıtlamadı, örneğin beklenmeyen bir durum kodu veya hatalı biçimlendirilmiş bir kayıt.
• upstream_error - Veri kaynağı başarısız oldu, örneğin bir DNS sunucusu hatası veya HTTP 5xx yanıtı.
• unsupported - Bu kontrol girdi için kullanılamıyor, örneğin desteklenmeyen bir TLD veya güvenilir denetleyicisi olmayan bir platform.

{
  "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"
  }
}

Bilinmeyen kontroller içeren puanlar ve notlar

Puanlar bilinmeyen bir kontrolü asla eksik saymaz. DNS güvenlik puanı ve e-posta kimlik doğrulama notu bilinmeyen kontrolleri dışarıda bırakır, bunları checks_unknown içinde bildirir ve score_confidence değerini partial yapar. Tüm kontroller bilinmiyorsa puan ve not null olur. Hiçbir sertifika okunamadığında SSL notu ve puanı null olur ve grade_reason değeri certificate_not_retrieved olarak ayarlanır; itibar puanı ise bilinmeyen park durumunu park edilmemiş yerine null olarak bildirir.