> 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/it/docs/response-format # Formato della risposta API DomScan: Tutte le risposte sono in formato JSON. Ogni risultato di dominio contiene questi campi comuni: 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 ```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" } ``` ### 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. ```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 } } ``` ### 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`. | Parametro | Endpoint | Equivale a | | --- | --- | --- | | `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` | 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`. | Endpoint | Dimensione predefinita della pagina | Limite massimo | | --- | --- | --- | | `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` | Lista completa | 100 | | `GET /v1/watchlist/expiring` | Lista completa | 100 | | `GET /v1/watchlist/available` | Lista completa | 100 | | `GET /v1/brand-monitor` | Lista completa | 100 | | `GET /v1/email/blacklist` | 1000 | 10000 | #### Esempio ```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..." ``` ### 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. ```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" } } ``` Un controllo bloccato, limitato, scaduto o fallito non viene mai segnalato come absent. Considera `unknown` come «riprova più tardi» e non come «non esiste», e non interpretare mai l'assenza come prova che un nome sia rivendicabile. #### 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.