Formato della risposta

Formato della risposta

Tutte le risposte sono in formato JSON. Ogni risultato di dominio contiene questi campi comuni:

• domain - Nome di dominio completo
• available - Stato booleano di disponibilità
• source - "rdap" o "cache"
• checked_at - Timestamp ISO 8601
• error - Presente se si è verificato un errore

Metadati della risposta

Ogni risposta API include un ID della richiesta e un valore di aggiornamento. Quando disponibili, gli header della risposta mostrano anche i crediti richiesti, addebitati, rimborsati e rimanenti, oltre al piano, al limite, alla capacità rimanente e alla policy del limite di frequenza. Un valore di aggiornamento unknown indica che non è stato possibile stabilire l’aggiornamento per quella risposta. Non significa che i dati siano aggiornati.

Selezione dei campi e risposte compatte

Aggiungi fields o compact alla query string di qualsiasi richiesta GET o POST per ricevere una risposta JSON più piccola. Entrambi sono facoltativi. Nelle richieste POST vanno nella query string, non nel corpo. Nessuno dei due modifica il costo in crediti.

Selezionare i campi

fields accetta percorsi a punti separati da virgole, come fields=domain,classification.status,records.data. Quando un percorso attraversa una lista, si applica a ogni elemento. Gli elementi mantengono la loro posizione, e un elemento senza alcun campo selezionato diventa {}. Un valore nullo lungo un percorso viene mantenuto come nullo.

Invia fino a 50 percorsi, ciascuno con fino a 6 segmenti di 1-64 lettere, cifre o trattini bassi. Qualsiasi altro valore restituisce 400 INVALID_PARAMETER prima dell'esecuzione della richiesta, quindi non viene addebitato nulla.

I percorsi senza corrispondenza nella risposta vengono omessi ed elencati nell'intestazione di risposta X-Fields-Ignored, fino a 20 percorsi.

Risposte compatte

compact=true rimuove solo quanto segue, e soltanto al livello principale della risposta:

• Nell'oggetto meta: served_by e le chiavi dei tempi duration_ms, query_time_ms, total_ms, total_time_ms, latency_ms, generation_ms e check_duration_ms. L'oggetto meta stesso viene rimosso quando non contiene altro.
• warnings, caveats, notes ed errors quando sono liste vuote.
• request_id quando ripete l'intestazione X-Request-Id.

I campi di dati, classification, gli oggetti annidati e gli elementi di lista non vengono mai rimossi. Quando vengono inviati entrambi i parametri, compact viene eseguito per primo e fields per secondo.

Solo le risposte JSON riuscite vengono rimodellate. Le risposte di errore, le risposte CSV, di testo e in streaming, e le stime dry_run vengono restituite invariate. Le risposte rimodellate vengono inviate senza indentazione.

Con una Idempotency-Key, fields e compact fanno parte della richiesta. Un nuovo tentativo con gli stessi valori restituisce la risposta rimodellata memorizzata. Riutilizzare la chiave con valori diversi restituisce 422 IDEMPOTENCY_KEY_REUSED.

Gli strumenti MCP accettano gli stessi argomenti facoltativi fields e compact. I percorsi senza corrispondenza sono elencati in _meta.fields_ignored nel risultato dello strumento.

Esempio

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

Chiavi snake_case (naming)

La maggior parte delle chiavi di risposta è già in snake_case, ma alcuni endpoint restituiscono alcune chiavi in camelCase, come registrarName nei risultati dei prezzi, tldTier nei fattori di valutazione e eventDate negli eventi RDAP. Aggiungi naming=snake alla query string, oppure invia l'header DomScan-Naming: snake, per ricevere tutte queste chiavi in snake_case. Senza di esso, le risposte mantengono le chiavi attuali.

Una chiave cambia solo se inizia con una lettera minuscola, contiene solo lettere e cifre e ha almeno una lettera maiuscola. Ogni nuova parola riceve un trattino basso e la chiave diventa minuscola. Gli acronimi restano uniti, compresi IPv4 e i plurali come IPs: registrarName diventa registrar_name, secureDNS diventa secure_dns, ipv4Address diventa ipv4_address e nameserverIPs diventa nameserver_ips.

Le chiavi che sono dati e non nomi di campo mantengono la grafia esatta, ad esempio i tipi di record DNS come A e MX, i voti come A+, i nomi di dominio, i nomi degli header e i nomi delle tecnologie. I valori non vengono mai modificati, e gli oggetti e le liste annidati vengono convertiti a ogni livello.

Se un oggetto ha già il nome in snake_case, ad esempio sia fooBar sia foo_bar, foo_bar mantiene il proprio valore e fooBar mantiene il nome originale, così non si perde nulla. L'ordine delle chiavi non cambia.

Il parametro di query prevale sull'header, quindi naming=default disattiva l'attivazione tramite header per una singola richiesta. I valori accettati sono snake e default. Qualsiasi altro valore restituisce 400 INVALID_PARAMETER prima dell'esecuzione della richiesta, quindi non viene addebitato nulla. Le risposte includono Vary: DomScan-Naming.

naming viene eseguito prima di compact e fields, quindi scrivi i percorsi di fields in snake_case, ad esempio fields=factors.tld_tier. Le risposte di errore sono già in snake_case e non cambiano mai, e il costo in crediti resta lo stesso.

Con una Idempotency-Key, la scelta della nomenclatura fa parte della richiesta, che provenga dal parametro o dall'header, quindi un nuovo tentativo restituisce le stesse chiavi.

Gli strumenti MCP accettano lo stesso argomento facoltativo naming. Le chiamate MCP non leggono l'header.

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

Controllo della freschezza (max_age)

Gli endpoint che possono rispondere con dati verificati di recente accettano max_age, un numero intero di secondi da 0 a 2592000 (30 giorni). I dati più vecchi di max_age vengono verificati di nuovo prima di essere restituiti, e max_age=0 verifica sempre da capo. Senza max_age, ogni endpoint mantiene il suo comportamento abituale.

Ogni risposta riuscita di questi endpoint include un cache_age_s di primo livello: l'età in secondi dei dati usati, oppure 0 se sono stati verificati di nuovo. Lo stesso valore viene inviato nell'header di risposta X-Cache-Age. Quando una risposta contiene più elementi, come una verifica di disponibilità per più domini, è l'età dell'elemento più vecchio, e gli elementi mantengono il proprio cache_age_s dove ne avevano già uno.

max_age non cambia mai il modo in cui un risultato viene classificato. Un risultato che non è stato possibile confermare resta unknown per quanto sia recente, e i dati recenti non vengono mai mostrati come presenti o assenti, a meno che la verifica originale non lo abbia confermato.

max_age non cambia il costo di una richiesta. Una verifica nuova e una risposta basata su dati recenti costano gli stessi crediti.

Su /v1/status e /v1/status/bulk, le verifiche nuove forzate (max_age=0) sono limitate per client per proteggere i registri. Oltre tale limite la richiesta riceve risposta come se max_age non fosse stato inviato, e cache_age_s mostra l'età di ciò che hai ricevuto. Un max_age che non sia un numero intero da 0 a 2592000 restituisce 400 INVALID_PARAMETER prima dell'esecuzione della richiesta, quindi non viene addebitato nulla.

Endpoint che accettano 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/identity-resolution, GET /v1/url-intelligence, GET /v1/agent-readiness, GET /v1/robots, GET /v1/ssl/deep-scan

Parametri di cache precedenti

Questi parametri continuano a funzionare e ora sono alias obsoleti di max_age. Se invii anche max_age, prevale max_age.

Su /v1/subdomains, prefer_cache mantiene anche il suo comportamento solo cache: quando non c'è ancora nulla di memorizzato, la richiesta restituisce 202 senza addebito e avvia la ricerca in background.

Gli strumenti MCP per questi endpoint accettano lo stesso argomento facoltativo max_age, e i loro risultati includono cache_age_s.

Paginazione (limit e cursor)

Gli endpoint che restituiscono liste lunghe accettano limit e cursor, e ogni risposta include has_more e next_cursor. Per ottenere la pagina successiva, ripeti la richiesta con cursor impostato su next_cursor. Nell'ultima pagina has_more è false e next_cursor è null.

Senza limit, ogni endpoint restituisce lo stesso numero di elementi di prima, quindi le richieste esistenti non cambiano. Puoi cambiare limit da una pagina all'altra.

I cursori sono opachi e firmati. Un cursore funziona solo per l'account che lo ha ricevuto e per la stessa query, ad esempio lo stesso dominio e gli stessi filtri. Un cursore modificato, appartenente a un altro account o inviato con filtri diversi restituisce 400 INVALID_CURSOR.

Le pagine seguono un ordine stabile, quindi gli elementi aggiunti o rimossi tra una richiesta e l'altra non vengono ripetuti né saltati. Negli endpoint di cronologia, i campi di riepilogo descrivono gli elementi della pagina corrente.

Ogni pagina è una richiesta normale e costa i crediti abituali dell'endpoint, esattamente come una richiesta con limit prima. Gli endpoint gratuiti restano gratuiti.

I parametri precedenti continuano a funzionare: offset su /v1/email/blacklist e il pagination.next_cursor numerico su /v1/certificates.

Esempio

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

Stato di classificazione

Gli endpoint che indicano se qualcosa esiste (registrazione di domini, handle social, record DNS e di autenticazione email, security.txt, robots.txt, sitemap, header di sicurezza, parcheggio, registrazioni typosquat e certificati SSL) aggiungono un oggetto classification accanto ai campi esistenti. I campi esistenti mantengono nome e significato.

• status - present, absent o unknown. Present e absent vengono restituiti solo quando il controllo ha prodotto prove esatte e autorevoli.
• reason - Restituito solo quando lo stato è unknown. Spiega perché non è stato possibile dare una risposta definitiva.
• evidence - Da dove proviene la risposta: source, method, observed_at e un detail facoltativo come http_404 o nxdomain.
• checked_at - Quando DomScan ha prodotto la classificazione. Per i risultati in cache, evidence.observed_at è precedente.

Motivi di unknown

• blocked - La destinazione ha negato l'accesso, ad esempio con HTTP 401, 403 o una sfida anti-bot.
• rate_limited - La destinazione o il registro ci ha chiesto di rallentare, ad esempio con HTTP 429.
• timeout - Il controllo non è terminato entro il tempo previsto.
• ambiguous - È arrivata una risposta che però non dimostrava né presenza né assenza, ad esempio un codice di stato inatteso o un record malformato.
• upstream_error - La fonte dei dati ha avuto un errore, ad esempio un guasto del server DNS o una risposta HTTP 5xx.
• unsupported - Questo controllo non è disponibile per l'input, ad esempio un TLD non supportato o una piattaforma senza un verificatore affidabile.

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

Punteggi e voti con controlli sconosciuti

I punteggi non contano mai un controllo sconosciuto come mancante. Il punteggio di sicurezza DNS e il voto di autenticazione email escludono i controlli sconosciuti, li indicano in checks_unknown e impostano score_confidence su partial. Quando tutti i controlli sono sconosciuti, punteggio e voto sono null. Il voto e il punteggio SSL sono null con grade_reason impostato su certificate_not_retrieved quando non è stato possibile leggere alcun certificato, e il punteggio di reputazione segnala il parcheggio sconosciuto come null invece di non parcheggiato.