Antwortformat

Antwortformat

Alle Antworten sind JSON. Jedes Domain-Ergebnis enthält diese gemeinsamen Felder:

• domain - Vollständiger Domainname
• available - Boolescher Verfügbarkeitsstatus
• source - "rdap" oder "cache"
• checked_at - ISO-8601-Zeitstempel
• error - Vorhanden, wenn ein Fehler aufgetreten ist

Antwortmetadaten

Jede API-Antwort enthält eine Anfrage-ID und einen Aktualitätswert. Wenn verfügbar, zeigen Antwort-Header außerdem angeforderte, abgerechnete, erstattete und verbleibende Credits sowie Ihren Ratenlimitplan, das Limit, die verbleibende Kapazität und die Richtlinie. Ein Aktualitätswert von unknown bedeutet, dass die Aktualität für diese Antwort nicht festgestellt werden konnte. Das bedeutet nicht, dass die Daten aktuell sind.

Feldauswahl und kompakte Antworten

Fügen Sie fields oder compact dem Query-String einer beliebigen GET- oder POST-Anfrage hinzu, um eine kleinere JSON-Antwort zu erhalten. Beide sind optional. Bei POST-Anfragen gehören sie in den Query-String, nicht in den Body. Keiner von beiden ändert die Credit-Kosten.

Felder auswählen

fields akzeptiert kommagetrennte Punktpfade, etwa fields=domain,classification.status,records.data. Führt ein Pfad durch eine Liste, gilt er für jedes Element. Die Elemente behalten ihre Position, und ein Element ohne ausgewähltes Feld wird zu {}. Ein Nullwert entlang eines Pfads bleibt als null erhalten.

Senden Sie bis zu 50 Pfade mit jeweils bis zu 6 Segmenten aus 1 bis 64 Buchstaben, Ziffern oder Unterstrichen. Jeder andere Wert liefert 400 INVALID_PARAMETER, bevor die Anfrage ausgeführt wird, sodass nichts berechnet wird.

Pfade ohne Treffer in der Antwort werden weggelassen und im Antwort-Header X-Fields-Ignored aufgeführt, bis zu 20 Pfade.

Kompakte Antworten

compact=true entfernt ausschließlich Folgendes, und nur auf der obersten Ebene der Antwort:

• Im Objekt meta: served_by und die Zeitschlüssel duration_ms, query_time_ms, total_ms, total_time_ms, latency_ms, generation_ms und check_duration_ms. Das Objekt meta selbst wird entfernt, wenn darin nichts anderes übrig bleibt.
• warnings, caveats, notes und errors, wenn sie leere Listen sind.
• request_id, wenn es den Header X-Request-Id wiederholt.

Datenfelder, classification, verschachtelte Objekte und Listenelemente werden nie entfernt. Werden beide Parameter gesendet, läuft compact zuerst und fields danach.

Nur erfolgreiche JSON-Antworten werden umgeformt. Fehlerantworten, CSV-, Text- und Streaming-Antworten sowie dry_run-Schätzungen werden unverändert zurückgegeben. Umgeformte Antworten werden ohne Einrückung gesendet.

Mit einem Idempotency-Key sind fields und compact Teil der Anfrage. Eine Wiederholung mit denselben Werten liefert die gespeicherte, umgeformte Antwort. Wird der Schlüssel mit anderen Werten erneut verwendet, folgt 422 IDEMPOTENCY_KEY_REUSED.

MCP-Tools akzeptieren dieselben optionalen Argumente fields und compact. Pfade ohne Treffer werden im Tool-Ergebnis unter _meta.fields_ignored aufgeführt.

Beispiel

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-Schlüssel (naming)

Die meisten Schlüssel in Antworten sind bereits snake_case, einige Endpunkte liefern jedoch einzelne Schlüssel in camelCase, etwa registrarName in Preisergebnissen, tldTier in Bewertungsfaktoren und eventDate in RDAP-Ereignissen. Fügen Sie naming=snake zum Query-String hinzu oder senden Sie den Header DomScan-Naming: snake, um alle diese Schlüssel in snake_case zu erhalten. Ohne diese Angabe behalten die Antworten ihre bisherigen Schlüssel.

Ein Schlüssel ändert sich nur, wenn er mit einem Kleinbuchstaben beginnt, ausschließlich Buchstaben und Ziffern enthält und mindestens einen Großbuchstaben hat. Jedes neue Wort erhält einen Unterstrich, und der Schlüssel wird in Kleinbuchstaben umgewandelt. Akronyme bleiben zusammen, auch IPv4 und Plurale wie IPs: registrarName wird zu registrar_name, secureDNS wird zu secure_dns, ipv4Address wird zu ipv4_address und nameserverIPs wird zu nameserver_ips.

Schlüssel, die Daten statt Feldnamen sind, behalten ihre exakte Schreibweise, zum Beispiel DNS-Record-Typen wie A und MX, Bewertungen wie A+, Domainnamen, Header-Namen und Technologienamen. Werte werden nie verändert, und verschachtelte Objekte und Listen werden auf jeder Ebene umgewandelt.

Hat ein Objekt bereits den snake_case-Namen, zum Beispiel sowohl fooBar als auch foo_bar, behält foo_bar seinen Wert und fooBar seinen ursprünglichen Namen, sodass nichts verloren geht. Die Reihenfolge der Schlüssel bleibt unverändert.

Der Query-Parameter hat Vorrang vor dem Header, daher schaltet naming=default ein Opt-in per Header für eine einzelne Anfrage ab. Zulässige Werte sind snake und default. Jeder andere Wert liefert 400 INVALID_PARAMETER, bevor die Anfrage ausgeführt wird, sodass nichts berechnet wird. Antworten enthalten Vary: DomScan-Naming.

naming wird vor compact und fields angewendet, schreiben Sie die Pfade in fields daher in snake_case, etwa fields=factors.tld_tier. Fehlerantworten sind bereits snake_case und ändern sich nie, und die Credit-Kosten bleiben gleich.

Bei Verwendung eines Idempotency-Key ist die Wahl der Benennung Teil der Anfrage, unabhängig davon, ob sie über den Parameter oder den Header erfolgt, sodass ein erneuter Versuch dieselben Schlüssel liefert.

MCP-Tools akzeptieren dasselbe optionale Argument naming. MCP-Aufrufe lesen den Header nicht.

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

Aktualitätssteuerung (max_age)

Endpunkte, die aus kürzlich geprüften Daten antworten können, akzeptieren max_age, eine ganze Zahl von Sekunden von 0 bis 2592000 (30 Tage). Daten, die älter als max_age sind, werden vor der Rückgabe erneut geprüft, und max_age=0 prüft immer neu. Ohne max_age behält jeder Endpunkt sein übliches Verhalten.

Jede erfolgreiche Antwort dieser Endpunkte enthält ein cache_age_s auf oberster Ebene: das Alter der verwendeten Daten in Sekunden oder 0, wenn sie neu geprüft wurden. Derselbe Wert wird im Antwort-Header X-Cache-Age gesendet. Enthält eine Antwort mehrere Elemente, etwa eine Verfügbarkeitsprüfung für mehrere Domains, ist es das Alter des ältesten Elements, und Elemente behalten ihr eigenes cache_age_s, wo sie bereits eines hatten.

max_age ändert nie, wie ein Ergebnis klassifiziert wird. Ein Ergebnis, das nicht bestätigt werden konnte, bleibt unknown, egal wie aktuell es ist, und aktuelle Daten werden nie als vorhanden oder nicht vorhanden angezeigt, es sei denn, die ursprüngliche Prüfung hat es bestätigt.

max_age ändert nicht, was eine Anfrage kostet. Eine neue Prüfung und eine Antwort aus aktuellen Daten kosten gleich viele Credits.

Bei /v1/status und /v1/status/bulk sind erzwungene Neuprüfungen (max_age=0) pro Client begrenzt, um die Registries zu schützen. Über dieses Limit hinaus wird die Anfrage so beantwortet, als wäre max_age nicht gesendet worden, und cache_age_s zeigt das Alter der erhaltenen Daten. Ein max_age, das keine ganze Zahl von 0 bis 2592000 ist, liefert 400 INVALID_PARAMETER, bevor die Anfrage ausgeführt wird, sodass nichts berechnet wird.

Endpunkte, die max_age akzeptieren: 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

Ältere Cache-Parameter

Diese Parameter funktionieren weiterhin und sind jetzt veraltete Aliase von max_age. Wenn du zusätzlich max_age sendest, hat max_age Vorrang.

Bei /v1/subdomains behält prefer_cache außerdem sein reines Cache-Verhalten: Ist noch nichts gespeichert, liefert die Anfrage 202 ohne Berechnung und startet die Abfrage im Hintergrund.

MCP-Tools für diese Endpunkte akzeptieren dasselbe optionale Argument max_age, und ihre Ergebnisse enthalten cache_age_s.

Pagination (limit und cursor)

Endpunkte, die lange Listen zurückgeben, akzeptieren limit und cursor, und jede Antwort enthält has_more und next_cursor. Für die nächste Seite wiederholst du die Anfrage mit cursor gleich next_cursor. Auf der letzten Seite ist has_more false und next_cursor null.

Ohne limit liefert jeder Endpunkt dieselbe Anzahl an Elementen wie bisher, bestehende Anfragen bleiben also unverändert. Du kannst limit von Seite zu Seite ändern.

Cursor sind undurchsichtig und signiert. Ein Cursor funktioniert nur für das Konto, das ihn erhalten hat, und für dieselbe Abfrage, etwa dieselbe Domain und dieselben Filter. Ein Cursor, der verändert wurde, zu einem anderen Konto gehört oder mit anderen Filtern gesendet wird, liefert 400 INVALID_CURSOR.

Die Seiten folgen einer stabilen Reihenfolge, sodass zwischen Anfragen hinzugefügte oder entfernte Elemente weder wiederholt noch übersprungen werden. Bei den Verlaufs-Endpunkten beschreiben Zusammenfassungsfelder die Elemente der aktuellen Seite.

Jede Seite ist eine normale Anfrage und kostet die üblichen Credits des Endpunkts, genau wie bisher eine Anfrage mit limit. Kostenlose Endpunkte bleiben kostenlos.

Ältere Parameter funktionieren weiterhin: offset bei /v1/email/blacklist und das numerische pagination.next_cursor bei /v1/certificates.

Beispiel

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

Klassifizierungsstatus

Endpunkte, die melden, ob etwas existiert (Domainregistrierung, Social-Media-Handles, DNS- und E-Mail-Authentifizierungseinträge, security.txt, robots.txt, Sitemaps, Security-Header, Parking, Typosquat-Registrierungen und SSL-Zertifikate), liefern neben ihren bisherigen Feldern ein classification-Objekt. Bestehende Felder behalten Namen und Bedeutung.

• status - present, absent oder unknown. Present und absent werden nur zurückgegeben, wenn die Prüfung exakte, verlässliche Belege geliefert hat.
• reason - Wird nur zurückgegeben, wenn der Status unknown ist. Erklärt, warum keine eindeutige Antwort möglich war.
• evidence - Woher die Antwort stammt: source, method, observed_at und ein optionales detail wie http_404 oder nxdomain.
• checked_at - Wann DomScan die Klassifizierung erstellt hat. Bei Ergebnissen aus dem Cache liegt evidence.observed_at früher.

Gründe für unknown

• blocked - Das Ziel hat den Zugriff verweigert, zum Beispiel mit HTTP 401, 403 oder einer Bot-Abfrage.
• rate_limited - Das Ziel oder die Registry hat uns gebeten, langsamer anzufragen, zum Beispiel mit HTTP 429.
• timeout - Die Prüfung wurde nicht innerhalb ihres Zeitbudgets abgeschlossen.
• ambiguous - Es kam eine Antwort, die aber weder Vorhandensein noch Fehlen belegt, zum Beispiel ein unerwarteter Statuscode oder ein fehlerhafter Eintrag.
• upstream_error - Die Datenquelle ist ausgefallen, zum Beispiel durch einen DNS-Serverfehler oder eine HTTP-5xx-Antwort.
• unsupported - Diese Prüfung ist für die Eingabe nicht verfügbar, zum Beispiel bei einer nicht unterstützten TLD oder einer Plattform ohne zuverlässige Prüfmethode.

{
  "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 und Noten bei unbekannten Prüfungen

Scores zählen eine unbekannte Prüfung nie als fehlend. Der DNS-Sicherheitsscore und die Note für die E-Mail-Authentifizierung lassen unbekannte Prüfungen außen vor, melden sie in checks_unknown und setzen score_confidence auf partial. Sind alle Prüfungen unbekannt, sind Score und Note null. Die SSL-Note und der SSL-Score sind null, wobei grade_reason auf certificate_not_retrieved gesetzt wird, wenn kein Zertifikat gelesen werden konnte, und der Reputationsscore meldet unbekanntes Parking als null statt als nicht geparkt.