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 domenyavailable- Logiczny status dostępnościsource- „rdap” lub „cache”checked_at- Znacznik czasu ISO 8601error- 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_byoraz klucze czasuduration_ms,query_time_ms,total_ms,total_time_ms,latency_ms,generation_msicheck_duration_ms. Sam obiektmetajest usuwany, gdy nic innego w nim nie zostanie. warnings,caveats,notesierrors, gdy są pustymi listami.request_id, gdy powtarza nagłówekX-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.
| Parametr | Endpointy | Odpowiada |
|---|---|---|
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 |
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.
| Endpoint | Domyślny rozmiar strony | Maksymalny 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 | Cała lista | 100 |
GET /v1/watchlist/expiring | Cała lista | 100 |
GET /v1/watchlist/available | Cała lista | 100 |
GET /v1/brand-monitor | Cała lista | 100 |
GET /v1/email/blacklist | 1000 | 10000 |
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,absentlubunknown. Present i absent są zwracane tylko wtedy, gdy sprawdzenie dało dokładny, wiarygodny dowód.reason- Zwracane tylko wtedy, gdy status tounknown. Wyjaśnia, dlaczego nie udało się podać jednoznacznej odpowiedzi.evidence- Skąd pochodzi odpowiedź:source,method,observed_atoraz opcjonalnedetail, na przykładhttp_404lubnxdomain.checked_at- Kiedy DomScan wygenerował klasyfikację. W wynikach z pamięci podręcznejevidence.observed_atjest 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"
}
}
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.