Antwoordindeling

Antwoordindeling

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

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.

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.

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.

Voorbeeld

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.

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

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.