> 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/de/docs/response-format # Antwortformat DomScan-API: Alle Antworten sind JSON. Jedes Domain-Ergebnis enthält diese gemeinsamen Felder: 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 ```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-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. ```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 } } ``` ### 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. | Parameter | Endpunkte | Entspricht | | --- | --- | --- | | `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` | 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`. | Endpunkt | Standard-Seitengröße | Maximales 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` | Gesamte Liste | 100 | | `GET /v1/watchlist/expiring` | Gesamte Liste | 100 | | `GET /v1/watchlist/available` | Gesamte Liste | 100 | | `GET /v1/brand-monitor` | Gesamte Liste | 100 | | `GET /v1/email/blacklist` | 1000 | 10000 | #### Beispiel ```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..." ``` ### 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. ```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" } } ``` Eine blockierte, ratenbegrenzte, abgelaufene oder fehlgeschlagene Prüfung wird nie als absent gemeldet. Verstehen Sie `unknown` als „später erneut versuchen“ und nicht als „nicht vorhanden“, und werten Sie ein Fehlen nie als Beweis dafür, dass ein Name registrierbar ist. #### 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.