Dokumentacja dla deweloperów

Format odpowiedzi

DomScan API do analizy domen: Wszystkie odpowiedzi są w formacie JSON. Wynik każdej domeny zawiera te wspólne pola:

Format odpowiedzi

Wszystkie odpowiedzi są w formacie JSON. Wynik każdej domeny zawiera te wspólne pola:

  • domain - Pełna nazwa domeny
  • available - Logiczny status dostępności
  • source - „rdap” lub „cache”
  • checked_at - Znacznik czasu ISO 8601
  • error - Obecne, jeśli wystąpił błąd

Metadane odpowiedzi

Każda odpowiedź API zawiera identyfikator żądania i wartość aktualności danych. Jeśli są dostępne, nagłówki odpowiedzi pokazują również żądane, naliczone, zwrócone i pozostałe kredyty, a także plan limitu szybkości, limit, pozostałą przepustowość i zasady. Wartość aktualności unknown oznacza, że nie udało się ustalić aktualności dla tej odpowiedzi. Nie oznacza to, że dane są aktualne.

Wybór pól i zwarte odpowiedzi

Dodaj fields lub compact do ciągu zapytania dowolnego żądania GET lub POST, aby otrzymać mniejszą odpowiedź JSON. Oba parametry są opcjonalne. W żądaniach POST podaje się je w ciągu zapytania, a nie w treści. Żaden z nich nie zmienia kosztu w kredytach.

Wybieranie pól

fields przyjmuje ścieżki z kropkami rozdzielone przecinkami, na przykład fields=domain,classification.status,records.data. Gdy ścieżka przechodzi przez listę, dotyczy każdego elementu. Elementy zachowują swoją pozycję, a element bez żadnego wybranego pola staje się {}. Wartość null na ścieżce pozostaje null.

Możesz wysłać do 50 ścieżek, każdą z maksymalnie 6 segmentami złożonymi z 1 do 64 liter, cyfr lub podkreśleń. Każda inna wartość zwraca 400 INVALID_PARAMETER przed wykonaniem żądania, więc nic nie jest naliczane.

Ścieżki, które do niczego w odpowiedzi nie pasują, są pomijane i wymienione w nagłówku odpowiedzi X-Fields-Ignored, do 20 ścieżek.

Zwarte odpowiedzi

compact=true usuwa wyłącznie poniższe elementy i tylko na najwyższym poziomie odpowiedzi:

  • W obiekcie meta: served_by oraz klucze czasu duration_ms, query_time_ms, total_ms, total_time_ms, latency_ms, generation_ms i check_duration_ms. Sam obiekt meta jest usuwany, gdy nic innego w nim nie zostanie.
  • warnings, caveats, notes i errors, gdy są pustymi listami.
  • request_id, gdy powtarza nagłówek X-Request-Id.

Pola z danymi, classification, obiekty zagnieżdżone i elementy list nigdy nie są usuwane. Gdy wysłano oba parametry, najpierw działa compact, a potem fields.

Przekształcane są tylko udane odpowiedzi JSON. Odpowiedzi z błędami, odpowiedzi CSV, tekstowe i strumieniowe oraz szacunki dry_run są zwracane bez zmian. Przekształcone odpowiedzi są wysyłane bez wcięć.

Gdy użyto Idempotency-Key, fields i compact stanowią część żądania. Ponowienie z tymi samymi wartościami zwraca zapisaną, przekształconą odpowiedź. Ponowne użycie klucza z innymi wartościami zwraca 422 IDEMPOTENCY_KEY_REUSED.

Narzędzia MCP akceptują te same opcjonalne argumenty fields i compact. Ścieżki, które do niczego nie pasują, są wymienione w _meta.fields_ignored wyniku narzędzia.

Przykład

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

Klucze snake_case (naming)

Większość kluczy odpowiedzi jest już w snake_case, ale kilka endpointów zwraca część kluczy w camelCase, na przykład registrarName w wynikach cen, tldTier w czynnikach wyceny i eventDate w zdarzeniach RDAP. Dodaj naming=snake do ciągu zapytania lub wyślij nagłówek DomScan-Naming: snake, aby otrzymać wszystkie te klucze w snake_case. Bez tego odpowiedzi zachowują dotychczasowe klucze.

Klucz zmienia się tylko wtedy, gdy zaczyna się od małej litery, zawiera wyłącznie litery i cyfry oraz ma co najmniej jedną wielką literę. Przed każdym nowym słowem pojawia się podkreślenie, a klucz zapisywany jest małymi literami. Akronimy pozostają razem, także IPv4 i liczby mnogie takie jak IPs: registrarName staje się registrar_name, secureDNS staje się secure_dns, ipv4Address staje się ipv4_address, a nameserverIPs staje się nameserver_ips.

Klucze, które są danymi, a nie nazwami pól, zachowują dokładną pisownię, na przykład typy rekordów DNS, takie jak A i MX, oceny, takie jak A+, nazwy domen, nazwy nagłówków i nazwy technologii. Wartości nigdy się nie zmieniają, a zagnieżdżone obiekty i listy są konwertowane na każdym poziomie.

Jeśli obiekt ma już nazwę w snake_case, na przykład zarówno fooBar, jak i foo_bar, klucz foo_bar zachowuje swoją wartość, a fooBar zachowuje pierwotną nazwę, więc nic nie zostaje utracone. Kolejność kluczy się nie zmienia.

Parametr zapytania ma pierwszeństwo przed nagłówkiem, więc naming=default wyłącza włączenie opcji nagłówkiem dla jednego żądania. Dozwolone wartości to snake i default. Każda inna wartość zwraca błąd 400 INVALID_PARAMETER, zanim żądanie zostanie wykonane, więc nic nie jest naliczane. Odpowiedzi zawierają Vary: DomScan-Naming.

naming jest wykonywany przed compact i fields, więc ścieżki w fields zapisuj w snake_case, na przykład fields=factors.tld_tier. Odpowiedzi z błędami są już w snake_case i nigdy się nie zmieniają, a koszt w kredytach jest taki sam.

W przypadku Idempotency-Key wybór nazewnictwa jest częścią żądania, niezależnie od tego, czy pochodzi z parametru, czy z nagłówka, więc ponowienie zwraca te same klucze.

Narzędzia MCP przyjmują ten sam opcjonalny argument naming. Wywołania MCP nie odczytują nagłówka.

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

Kontrola świeżości danych (max_age)

Endpointy, które mogą odpowiadać na podstawie niedawno sprawdzonych danych, akceptują max_age, czyli liczbę całkowitą sekund od 0 do 2592000 (30 dni). Dane starsze niż max_age są sprawdzane ponownie przed zwróceniem, a max_age=0 zawsze wymusza nowe sprawdzenie. Bez max_age każdy endpoint zachowuje się jak dotychczas.

Każda udana odpowiedź tych endpointów zawiera pole cache_age_s na najwyższym poziomie: wiek użytych danych w sekundach lub 0, gdy dane sprawdzono na nowo. Ta sama wartość jest wysyłana w nagłówku odpowiedzi X-Cache-Age. Gdy odpowiedź zawiera kilka elementów, na przykład sprawdzenie dostępności wielu domen, jest to wiek najstarszego elementu, a elementy zachowują własne cache_age_s, jeśli już je miały.

max_age nigdy nie zmienia sposobu klasyfikacji wyniku. Wynik, którego nie udało się potwierdzić, pozostaje unknown bez względu na to, jak jest świeży, a niedawne dane nigdy nie są pokazywane jako obecne lub nieobecne, chyba że potwierdziło to pierwotne sprawdzenie.

max_age nie zmienia kosztu żądania. Nowe sprawdzenie i odpowiedź z niedawnych danych kosztują tyle samo kredytów.

W /v1/status i /v1/status/bulk wymuszone nowe sprawdzenia (max_age=0) są ograniczone na klienta, aby chronić rejestry. Po przekroczeniu limitu żądanie jest obsługiwane tak, jakby max_age nie zostało wysłane, a cache_age_s pokazuje wiek otrzymanych danych. Wartość max_age, która nie jest liczbą całkowitą od 0 do 2592000, zwraca 400 INVALID_PARAMETER przed wykonaniem żądania, więc nic nie jest naliczane.

Endpointy akceptujące 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

Starsze parametry pamięci podręcznej

Te parametry nadal działają i są teraz przestarzałymi aliasami max_age. Gdy wyślesz też max_age, pierwszeństwo ma max_age.

ParametrEndpointyOdpowiada
prefer_cache/v1/status, /v1/subdomainsmax_age=2592000
skip_cache/v1/status, /v1/tech, /v1/categorize, /v1/identity-assets, /v1/identity-resolution, /v1/url-intelligence, /v1/agent-readiness, /v1/robotsmax_age=0
cache_skip/v1/statusmax_age=0
cache-skip/v1/statusmax_age=0
options.prefer_cache (body)/v1/status/bulkmax_age=2592000
prefer_cache (body)/v1/status/bulkmax_age=2592000
options.skip_cache (body)/v1/status/bulkmax_age=0
options.cache_skip (body)/v1/status/bulkmax_age=0
options.cache-skip (body)/v1/status/bulkmax_age=0
refresh/v1/ssl/deep-scanmax_age=0

W /v1/subdomains parametr prefer_cache zachowuje też swoje działanie tylko na podstawie pamięci podręcznej: gdy nic jeszcze nie zapisano, żądanie zwraca 202 bez naliczania opłat i uruchamia wyszukiwanie w tle.

Narzędzia MCP dla tych endpointów akceptują ten sam opcjonalny argument max_age, a ich wyniki zawierają cache_age_s.

Paginacja (limit i cursor)

Endpointy zwracające długie listy akceptują limit i cursor, a każda odpowiedź zawiera has_more i next_cursor. Aby pobrać następną stronę, powtórz żądanie z cursor ustawionym na next_cursor. Na ostatniej stronie has_more ma wartość false, a next_cursor ma wartość null.

Bez limit każdy endpoint zwraca tyle samo elementów co dotychczas, więc istniejące żądania się nie zmieniają. Wartość limit możesz zmieniać między kolejnymi stronami.

Kursory są nieprzejrzyste i podpisane. Kursor działa tylko dla konta, które go otrzymało, i dla tego samego zapytania, na przykład tej samej domeny i tych samych filtrów. Kursor, który zmodyfikowano, należy do innego konta lub wysłano z innymi filtrami, zwraca 400 INVALID_CURSOR.

Strony mają stabilną kolejność, więc elementy dodane lub usunięte między żądaniami nie są powtarzane ani pomijane. W endpointach historii pola podsumowania opisują elementy z bieżącej strony.

Każda strona to zwykłe żądanie i kosztuje zwykłą liczbę kredytów endpointu, dokładnie tak jak wcześniej żądanie z limit. Darmowe endpointy pozostają darmowe.

Starsze parametry nadal działają: offset w /v1/email/blacklist oraz numeryczny pagination.next_cursor w /v1/certificates.

EndpointDomyślny rozmiar stronyMaksymalny limit
GET /v1/whois/history50100
GET /v1/dns/history1001000
GET /v1/subdomains5002000
GET /v1/certificates1001000
GET /v1/watchlistCała lista100
GET /v1/watchlist/expiringCała lista100
GET /v1/watchlist/availableCała lista100
GET /v1/brand-monitorCała lista100
GET /v1/email/blacklist100010000

Przykład

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

Status klasyfikacji

Endpointy, które informują, czy coś istnieje (rejestracja domen, nazwy w mediach społecznościowych, rekordy DNS i uwierzytelniania poczty, security.txt, robots.txt, mapy witryn, nagłówki bezpieczeństwa, parkowanie, rejestracje typosquat i certyfikaty SSL), dodają obiekt classification obok dotychczasowych pól. Istniejące pola zachowują nazwy i znaczenie.

  • status - present, absent lub unknown. Present i absent są zwracane tylko wtedy, gdy sprawdzenie dało dokładny, wiarygodny dowód.
  • reason - Zwracane tylko wtedy, gdy status to unknown. Wyjaśnia, dlaczego nie udało się podać jednoznacznej odpowiedzi.
  • evidence - Skąd pochodzi odpowiedź: source, method, observed_at oraz opcjonalne detail, na przykład http_404 lub nxdomain.
  • checked_at - Kiedy DomScan wygenerował klasyfikację. W wynikach z pamięci podręcznej evidence.observed_at jest wcześniejsze.

Powody unknown

  • blocked - Cel odmówił dostępu, na przykład kodem HTTP 401, 403 lub weryfikacją antybotową.
  • rate_limited - Cel lub rejestr poprosił nas o zwolnienie tempa, na przykład kodem HTTP 429.
  • timeout - Sprawdzenie nie zakończyło się w przydzielonym czasie.
  • ambiguous - Odpowiedź nadeszła, ale nie dowodziła ani obecności, ani braku, na przykład nieoczekiwany kod statusu lub nieprawidłowy rekord.
  • upstream_error - Źródło danych zawiodło, na przykład awaria serwera DNS lub odpowiedź HTTP 5xx.
  • unsupported - To sprawdzenie nie jest dostępne dla podanych danych, na przykład dla nieobsługiwanej domeny TLD lub platformy bez wiarygodnego weryfikatora.
{
  "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"
  }
}
Zablokowane, ograniczone limitem, przeterminowane lub nieudane sprawdzenie nigdy nie jest zgłaszane jako absent. Traktuj unknown jako „spróbuj później”, a nie „nie istnieje”, i nigdy nie uznawaj braku za dowód, że nazwę można zająć.

Wyniki i oceny przy nieznanych sprawdzeniach

Wyniki nigdy nie liczą nieznanego sprawdzenia jako brakującego. Wynik bezpieczeństwa DNS i ocena uwierzytelniania poczty pomijają nieznane sprawdzenia, zgłaszają je w checks_unknown i ustawiają score_confidence na partial. Gdy wszystkie sprawdzenia są nieznane, wynik i ocena mają wartość null. Ocena i wynik SSL mają wartość null, a grade_reason ma wartość certificate_not_retrieved, gdy nie udało się odczytać certyfikatu, a wynik reputacji zgłasza nieznane parkowanie jako null zamiast niezaparkowane.