> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL. Source: https://domscan.net/tr/docs/response-format # Yanıt biçimi Alan adı analizi için DomScan API: Tüm yanıtlar JSON biçimindedir. Her alan adı sonucu şu ortak alanları içerir: 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 ```bash 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. ```bash 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. | Parametre | Endpoint'ler | Eşdeğeri | | --- | --- | --- | | `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` ü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`. | Endpoint | Varsayılan sayfa boyutu | En yüksek 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` | Tüm liste | 100 | | `GET /v1/watchlist/expiring` | Tüm liste | 100 | | `GET /v1/watchlist/available` | Tüm liste | 100 | | `GET /v1/brand-monitor` | Tüm liste | 100 | | `GET /v1/email/blacklist` | 1000 | 10000 | #### Örnek ```bash 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. ```json { "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" } } ``` Engellenen, hız sınırına takılan, zaman aşımına uğrayan veya başarısız olan bir kontrol asla absent olarak bildirilmez. `unknown` değerini “daha sonra tekrar dene” olarak yorumlayın, “yok” olarak değil; yokluğu da bir adın alınabileceğinin kanıtı saymayın. #### 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.