> 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/nl/docs/response-format # Antwoordindeling DomScan-API: Alle antwoorden zijn JSON. Elk domeinresultaat bevat deze algemene velden: Alle antwoorden zijn JSON. Elk domeinresultaat bevat deze algemene velden: - `domain` - Volledige domeinnaam - `available` - Booleaanse beschikbaarheidsstatus - `source` - "rdap" of "cache" - `checked_at` - ISO 8601-tijdstempel - `error` - Aanwezig als er een fout is opgetreden ### Metadata van de response Elke API-response bevat een request-ID en een waarde voor dataversheid. Wanneer beschikbaar tonen response-headers ook de aangevraagde, in rekening gebrachte, terugbetaalde en resterende credits, plus uw plan, limiet, resterende capaciteit en beleid voor snelheidslimieten. Een waarde voor dataversheid van `unknown` betekent dat de dataversheid voor die response niet kon worden vastgesteld. Het betekent niet dat de gegevens actueel zijn. ### Veldselectie en compacte antwoorden Voeg `fields` of `compact` toe aan de querystring van een GET- of POST-verzoek om een kleiner JSON-antwoord te ontvangen. Beide zijn optioneel. Bij POST-verzoeken staan ze in de querystring, niet in de body. Geen van beide wijzigt de creditkosten. #### Velden selecteren `fields` accepteert door komma's gescheiden puntpaden, zoals `fields=domain,classification.status,records.data`. Als een pad door een lijst loopt, geldt het voor elk item. Items behouden hun positie en een item zonder geselecteerd veld wordt `{}`. Een null-waarde langs een pad blijft null. Stuur maximaal 50 paden, elk met maximaal 6 segmenten van 1 tot 64 letters, cijfers of underscores. Elke andere waarde geeft 400 INVALID_PARAMETER terug voordat het verzoek wordt uitgevoerd, dus er wordt niets in rekening gebracht. Paden die niets in het antwoord opleveren, worden weggelaten en vermeld in de antwoordheader `X-Fields-Ignored`, tot maximaal 20 paden. #### Compacte antwoorden `compact=true` verwijdert uitsluitend het volgende, en alleen op het hoogste niveau van het antwoord: - In het object `meta`: `served_by` en de timingsleutels `duration_ms`, `query_time_ms`, `total_ms`, `total_time_ms`, `latency_ms`, `generation_ms` en `check_duration_ms`. Het object `meta` zelf wordt verwijderd als er niets anders in overblijft. - `warnings`, `caveats`, `notes` en `errors` wanneer het lege lijsten zijn. - `request_id` wanneer het de header `X-Request-Id` herhaalt. Gegevensvelden, `classification`, geneste objecten en lijstitems worden nooit verwijderd. Als beide parameters worden verzonden, wordt eerst compact toegepast en daarna fields. Alleen geslaagde JSON-antwoorden worden hervormd. Foutantwoorden, CSV-, tekst- en streamingantwoorden en `dry_run`-schattingen worden ongewijzigd teruggegeven. Hervormde antwoorden worden zonder inspringing verzonden. Met een `Idempotency-Key` maken `fields` en `compact` deel uit van het verzoek. Een nieuwe poging met dezelfde waarden geeft het opgeslagen, hervormde antwoord terug. Hergebruik van de sleutel met andere waarden geeft 422 IDEMPOTENCY_KEY_REUSED terug. MCP-tools accepteren dezelfde optionele argumenten `fields` en `compact`. Paden zonder overeenkomst worden vermeld in `_meta.fields_ignored` van het toolresultaat. #### Voorbeeld ```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-sleutels (naming) De meeste responsesleutels zijn al snake_case, maar enkele endpoints geven een aantal camelCase-sleutels terug, zoals `registrarName` in prijsresultaten, `tldTier` in waarderingsfactoren en `eventDate` in RDAP-events. Voeg `naming=snake` toe aan de querystring, of stuur de header `DomScan-Naming: snake` mee, om al die sleutels in snake_case te ontvangen. Zonder deze optie behouden responses hun huidige sleutels. Een sleutel verandert alleen als hij met een kleine letter begint, uitsluitend letters en cijfers bevat en minstens één hoofdletter heeft. Elk nieuw woord krijgt een underscore en de sleutel wordt omgezet naar kleine letters. Afkortingen blijven bij elkaar, waaronder `IPv4` en meervouden zoals `IPs`: `registrarName` wordt `registrar_name`, `secureDNS` wordt `secure_dns`, `ipv4Address` wordt `ipv4_address` en `nameserverIPs` wordt `nameserver_ips`. Sleutels die gegevens zijn in plaats van veldnamen behouden hun exacte schrijfwijze, bijvoorbeeld DNS-recordtypen zoals `A` en `MX`, scores zoals `A+`, domeinnamen, headernamen en technologienamen. Waarden worden nooit gewijzigd, en geneste objecten en lijsten worden op elk niveau omgezet. Als een object de snake_case-naam al heeft, bijvoorbeeld zowel `fooBar` als `foo_bar`, behoudt `foo_bar` zijn waarde en behoudt `fooBar` zijn oorspronkelijke naam, zodat er niets verloren gaat. De volgorde van de sleutels verandert niet. De queryparameter heeft voorrang op de header, dus met `naming=default` schakelt u een opt-in via de header voor één verzoek uit. Geaccepteerde waarden zijn `snake` en `default`. Elke andere waarde geeft 400 INVALID_PARAMETER terug voordat het verzoek wordt uitgevoerd, dus er worden geen kosten in rekening gebracht. Responses bevatten `Vary: DomScan-Naming`. `naming` wordt uitgevoerd vóór `compact` en `fields`, dus schrijf `fields`-paden in snake_case, zoals `fields=factors.tld_tier`. Foutresponses zijn al snake_case en veranderen nooit, en de kredietkosten blijven gelijk. Bij een `Idempotency-Key` maakt de naamgevingskeuze deel uit van het verzoek, ongeacht of die uit de parameter of de header komt, zodat een nieuwe poging dezelfde sleutels teruggeeft. MCP-tools accepteren hetzelfde optionele argument `naming`. MCP-aanroepen lezen de header niet. ```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 } } ``` ### Versheidsbeheer (max_age) Endpoints die kunnen antwoorden met recent gecontroleerde gegevens accepteren `max_age`, een geheel aantal seconden van 0 tot 2592000 (30 dagen). Gegevens die ouder zijn dan `max_age` worden opnieuw gecontroleerd voordat ze worden teruggegeven, en `max_age=0` controleert altijd opnieuw. Zonder `max_age` behoudt elk endpoint zijn gebruikelijke gedrag. Elk geslaagd antwoord van deze endpoints bevat een `cache_age_s` op het hoogste niveau: de leeftijd in seconden van de gebruikte gegevens, of 0 als ze net opnieuw zijn gecontroleerd. Dezelfde waarde wordt meegestuurd in de responsheader `X-Cache-Age`. Als een antwoord meerdere items bevat, zoals een beschikbaarheidscontrole voor meerdere domeinen, is het de leeftijd van het oudste item, en behouden items hun eigen `cache_age_s` waar ze er al een hadden. `max_age` verandert nooit hoe een resultaat wordt geclassificeerd. Een resultaat dat niet kon worden bevestigd blijft `unknown`, hoe recent het ook is, en recente gegevens worden nooit als aanwezig of afwezig getoond tenzij de oorspronkelijke controle dat heeft bevestigd. `max_age` verandert niets aan de kosten van een verzoek. Een nieuwe controle en een antwoord uit recente gegevens kosten evenveel credits. Op `/v1/status` en `/v1/status/bulk` zijn geforceerde nieuwe controles (`max_age=0`) per client beperkt om registers te beschermen. Boven die limiet wordt het verzoek beantwoord alsof `max_age` niet was verstuurd, en `cache_age_s` toont de leeftijd van wat u hebt ontvangen. Een `max_age` die geen geheel getal van 0 tot 2592000 is, geeft 400 INVALID_PARAMETER terug voordat het verzoek wordt uitgevoerd, zodat er niets in rekening wordt gebracht. Endpoints die `max_age` accepteren: `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` #### Oudere cacheparameters Deze parameters blijven werken en zijn nu verouderde aliassen van `max_age`. Als u ook `max_age` meestuurt, heeft `max_age` voorrang. | Parameter | Endpoints | Gelijk aan | | --- | --- | --- | | `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` | Op `/v1/subdomains` behoudt `prefer_cache` ook zijn gedrag met alleen cache: als er nog niets is opgeslagen, geeft het verzoek 202 terug zonder kosten en start het de opzoeking op de achtergrond. MCP-tools voor deze endpoints accepteren hetzelfde optionele argument `max_age`, en hun resultaten bevatten `cache_age_s`. ### Paginering (limit en cursor) Endpoints die lange lijsten teruggeven accepteren `limit` en `cursor`, en elk antwoord bevat `has_more` en `next_cursor`. Herhaal het verzoek met `cursor` ingesteld op `next_cursor` om de volgende pagina op te halen. Op de laatste pagina is `has_more` false en is `next_cursor` null. Zonder `limit` geeft elk endpoint hetzelfde aantal items terug als voorheen, zodat bestaande verzoeken ongewijzigd blijven. U kunt `limit` van pagina tot pagina wijzigen. Cursors zijn ondoorzichtig en ondertekend. Een cursor werkt alleen voor het account dat hem heeft ontvangen en voor dezelfde query, bijvoorbeeld hetzelfde domein en dezelfde filters. Een cursor die is aangepast, bij een ander account hoort of met andere filters wordt verstuurd, geeft 400 INVALID_CURSOR terug. Pagina's volgen een vaste volgorde, zodat items die tussen verzoeken worden toegevoegd of verwijderd niet worden herhaald of overgeslagen. Bij de geschiedenis-endpoints beschrijven samenvattingsvelden de items op de huidige pagina. Elke pagina is een gewoon verzoek en kost de gebruikelijke credits van het endpoint, precies zoals een verzoek met `limit` voorheen. Gratis endpoints blijven gratis. Oudere parameters blijven werken: `offset` op `/v1/email/blacklist` en de numerieke `pagination.next_cursor` op `/v1/certificates`. | Endpoint | Standaardpaginagrootte | Maximale 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` | Hele lijst | 100 | | `GET /v1/watchlist/expiring` | Hele lijst | 100 | | `GET /v1/watchlist/available` | Hele lijst | 100 | | `GET /v1/brand-monitor` | Hele lijst | 100 | | `GET /v1/email/blacklist` | 1000 | 10000 | #### Voorbeeld ```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..." ``` ### Classificatiestatus Endpoints die aangeven of iets bestaat (domeinregistratie, social handles, DNS- en e-mailauthenticatierecords, security.txt, robots.txt, sitemaps, beveiligingsheaders, parking, typosquat-registraties en SSL-certificaten) voegen naast hun bestaande velden een `classification`-object toe. Bestaande velden behouden hun naam en betekenis. - `status` - `present`, `absent` of `unknown`. Present en absent worden alleen teruggegeven als de controle exact, gezaghebbend bewijs opleverde. - `reason` - Wordt alleen teruggegeven als de status `unknown` is. Legt uit waarom er geen eenduidig antwoord mogelijk was. - `evidence` - Waar het antwoord vandaan komt: `source`, `method`, `observed_at` en een optioneel `detail` zoals `http_404` of `nxdomain`. - `checked_at` - Wanneer DomScan de classificatie heeft bepaald. Bij gecachete resultaten ligt `evidence.observed_at` eerder. #### Redenen voor unknown - `blocked` - Het doel weigerde toegang, bijvoorbeeld met HTTP 401, 403 of een botcontrole. - `rate_limited` - Het doel of het register vroeg ons te vertragen, bijvoorbeeld met HTTP 429. - `timeout` - De controle was niet klaar binnen het tijdsbudget. - `ambiguous` - Er kwam een antwoord, maar dat bewees geen aanwezigheid of afwezigheid, bijvoorbeeld een onverwachte statuscode of een onjuist opgebouwd record. - `upstream_error` - De gegevensbron faalde, bijvoorbeeld door een storing van de DNS-server of een HTTP 5xx-antwoord. - `unsupported` - Deze controle is niet beschikbaar voor de invoer, bijvoorbeeld bij een niet-ondersteunde TLD of een platform zonder betrouwbare controle. ```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" } } ``` Een geblokkeerde, beperkte, verlopen of mislukte controle wordt nooit als absent gemeld. Zie `unknown` als “probeer het later opnieuw” en niet als “bestaat niet”, en beschouw afwezigheid nooit als bewijs dat een naam te claimen is. #### Scores en cijfers met onbekende controles Scores tellen een onbekende controle nooit als ontbrekend. De DNS-beveiligingsscore en het cijfer voor e-mailauthenticatie laten onbekende controles buiten beschouwing, melden ze in `checks_unknown` en zetten `score_confidence` op `partial`. Wanneer alle controles onbekend zijn, zijn de score en het cijfer `null`. Het SSL-cijfer en de SSL-score zijn `null` met `grade_reason` ingesteld op `certificate_not_retrieved` wanneer er geen certificaat kon worden gelezen, en de reputatiescore meldt onbekende parking als `null` in plaats van niet geparkeerd.