> 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/pl/docs/response-format

# Format odpowiedzi

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

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

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

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

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

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

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

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

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

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.
