> 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/pt/docs/response-format # Formato de resposta API da DomScan: Todas as respostas são JSON. Cada resultado de domínio contém estes campos comuns: Todas as respostas são JSON. Cada resultado de domínio contém estes campos comuns: - `domain` - Nome de domínio completo - `available` - Estado booleano de disponibilidade - `source` - "rdap" ou "cache" - `checked_at` - Carimbo temporal ISO 8601 - `error` - Presente se ocorreu um erro ### Metadados de resposta Cada resposta da API inclui um ID de requisição e um valor de atualidade. Quando disponíveis, os cabeçalhos de resposta também mostram créditos solicitados, cobrados, reembolsados e restantes, além do seu plano de limite de taxa, limite, capacidade restante e política. Um valor de atualidade `unknown` significa que não foi possível estabelecer a atualidade dessa resposta. Isso não significa que os dados estejam atuais. ### Seleção de campos e respostas compactas Adicione `fields` ou `compact` à query string de qualquer requisição GET ou POST para receber uma resposta JSON menor. Ambos são opcionais. Nas requisições POST, eles vão na query string, não no corpo. Nenhum dos dois altera o custo em créditos. #### Selecionar campos `fields` aceita caminhos de pontos separados por vírgulas, como `fields=domain,classification.status,records.data`. Quando um caminho atravessa uma lista, ele se aplica a cada item. Os itens mantêm sua posição, e um item sem nenhum campo selecionado vira `{}`. Um valor nulo ao longo de um caminho é mantido como nulo. Envie até 50 caminhos, cada um com até 6 segmentos de 1 a 64 letras, dígitos ou sublinhados. Qualquer outro valor retorna 400 INVALID_PARAMETER antes de a requisição ser executada, então nada é cobrado. Os caminhos sem correspondência na resposta são omitidos e listados no cabeçalho de resposta `X-Fields-Ignored`, até 20 caminhos. #### Respostas compactas `compact=true` remove somente o seguinte, e apenas no nível superior da resposta: - No objeto `meta`: `served_by` e as chaves de tempo `duration_ms`, `query_time_ms`, `total_ms`, `total_time_ms`, `latency_ms`, `generation_ms` e `check_duration_ms`. O próprio objeto `meta` é removido quando não sobra mais nada nele. - `warnings`, `caveats`, `notes` e `errors` quando são listas vazias. - `request_id` quando repete o cabeçalho `X-Request-Id`. Campos de dados, `classification`, objetos aninhados e itens de lista nunca são removidos. Quando os dois parâmetros são enviados, compact é executado primeiro e fields depois. Somente as respostas JSON bem-sucedidas são remodeladas. Respostas de erro, respostas CSV, de texto e em streaming, e estimativas de `dry_run` são retornadas sem alteração. As respostas remodeladas são enviadas sem indentação. Com uma `Idempotency-Key`, `fields` e `compact` fazem parte da requisição. Uma nova tentativa com os mesmos valores retorna a resposta remodelada armazenada. Reutilizar a chave com valores diferentes retorna 422 IDEMPOTENCY_KEY_REUSED. As ferramentas MCP aceitam os mesmos argumentos opcionais `fields` e `compact`. Os caminhos sem correspondência são listados em `_meta.fields_ignored` no resultado da ferramenta. #### Exemplo ```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" } ``` ### Chaves snake_case (naming) A maioria das chaves de resposta já está em snake_case, mas alguns endpoints devolvem certas chaves em camelCase, como `registrarName` nos resultados de preços, `tldTier` nos fatores de avaliação e `eventDate` nos eventos RDAP. Adicione `naming=snake` à query string, ou envie o cabeçalho `DomScan-Naming: snake`, para receber todas essas chaves em snake_case. Sem isso, as respostas mantêm as chaves atuais. Uma chave só muda se começar com uma letra minúscula, contiver apenas letras e dígitos e tiver pelo menos uma letra maiúscula. Cada nova palavra recebe um sublinhado e a chave passa para minúsculas. As siglas permanecem juntas, incluindo `IPv4` e plurais como `IPs`: `registrarName` passa a `registrar_name`, `secureDNS` passa a `secure_dns`, `ipv4Address` passa a `ipv4_address` e `nameserverIPs` passa a `nameserver_ips`. As chaves que são dados e não nomes de campo mantêm a grafia exata, por exemplo tipos de registro DNS como `A` e `MX`, classificações como `A+`, nomes de domínio, nomes de cabeçalhos e nomes de tecnologias. Os valores nunca são alterados, e objetos e listas aninhados são convertidos em todos os níveis. Se um objeto já tiver o nome em snake_case, por exemplo `fooBar` e `foo_bar` ao mesmo tempo, `foo_bar` mantém o seu valor e `fooBar` mantém o nome original, de modo que nada se perde. A ordem das chaves não muda. O parâmetro de consulta prevalece sobre o cabeçalho, então `naming=default` desativa a adesão por cabeçalho numa única requisição. Os valores aceitos são `snake` e `default`. Qualquer outro valor devolve 400 INVALID_PARAMETER antes de a requisição ser executada, portanto nada é cobrado. As respostas incluem `Vary: DomScan-Naming`. `naming` é aplicado antes de `compact` e `fields`, por isso escreva os caminhos de `fields` em snake_case, como `fields=factors.tld_tier`. As respostas de erro já estão em snake_case e nunca mudam, e o custo em créditos é o mesmo. Com uma `Idempotency-Key`, a escolha de nomenclatura faz parte da requisição, venha do parâmetro ou do cabeçalho, portanto uma nova tentativa devolve as mesmas chaves. As ferramentas MCP aceitam o mesmo argumento opcional `naming`. As chamadas MCP não leem o cabeçalho. ```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 } } ``` ### Controle de atualidade (max_age) Os endpoints que podem responder com dados verificados recentemente aceitam `max_age`, um número inteiro de segundos de 0 a 2592000 (30 dias). Dados mais antigos que `max_age` são verificados novamente antes de serem retornados, e `max_age=0` sempre verifica de novo. Sem `max_age`, cada endpoint mantém seu comportamento habitual. Toda resposta bem-sucedida desses endpoints inclui um `cache_age_s` de nível superior: a idade em segundos dos dados usados, ou 0 quando foram verificados de novo. O mesmo valor é enviado no cabeçalho de resposta `X-Cache-Age`. Quando uma resposta contém vários itens, como uma verificação de disponibilidade de vários domínios, é a idade do item mais antigo, e os itens mantêm seu próprio `cache_age_s` onde já tinham um. `max_age` nunca altera como um resultado é classificado. Um resultado que não pôde ser confirmado continua `unknown` por mais recente que seja, e dados recentes nunca são mostrados como presentes ou ausentes, a menos que a verificação original tenha confirmado. `max_age` não altera o custo de uma requisição. Uma verificação nova e uma resposta com dados recentes custam os mesmos créditos. Em `/v1/status` e `/v1/status/bulk`, as verificações novas forçadas (`max_age=0`) são limitadas por cliente para proteger os registros. Acima desse limite, a requisição é respondida como se `max_age` não tivesse sido enviado, e `cache_age_s` mostra a idade do que você recebeu. Um `max_age` que não seja um número inteiro de 0 a 2592000 retorna 400 INVALID_PARAMETER antes de a requisição ser executada, portanto nada é cobrado. Endpoints que aceitam `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` #### Parâmetros de cache anteriores Esses parâmetros continuam funcionando e agora são aliases obsoletos de `max_age`. Se você também enviar `max_age`, `max_age` prevalece. | Parâmetro | Endpoints | 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` | Em `/v1/subdomains`, `prefer_cache` também mantém seu comportamento somente de cache: quando ainda não há nada armazenado, a requisição retorna 202 sem cobrar e inicia a consulta em segundo plano. As ferramentas MCP desses endpoints aceitam o mesmo argumento opcional `max_age`, e seus resultados incluem `cache_age_s`. ### Paginação (limit e cursor) Os endpoints que retornam listas longas aceitam `limit` e `cursor`, e toda resposta inclui `has_more` e `next_cursor`. Para obter a próxima página, repita a requisição com `cursor` igual a `next_cursor`. Na última página, `has_more` é false e `next_cursor` é null. Sem `limit`, cada endpoint retorna o mesmo número de itens de antes, então as requisições existentes não mudam. Você pode alterar `limit` de uma página para outra. Os cursores são opacos e assinados. Um cursor só funciona para a conta que o recebeu e para a mesma consulta, por exemplo o mesmo domínio e os mesmos filtros. Um cursor editado, de outra conta ou enviado com filtros diferentes retorna 400 INVALID_CURSOR. As páginas seguem uma ordem estável, então itens adicionados ou removidos entre requisições não são repetidos nem ignorados. Nos endpoints de histórico, os campos de resumo descrevem os itens da página atual. Cada página é uma requisição normal e custa os créditos habituais do endpoint, exatamente como uma requisição com `limit` antes. Endpoints gratuitos continuam gratuitos. Os parâmetros anteriores continuam funcionando: `offset` em `/v1/email/blacklist` e o `pagination.next_cursor` numérico em `/v1/certificates`. | Endpoint | Tamanho de página padrão | Limite máximo | | --- | --- | --- | | `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 | #### Exemplo ```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..." ``` ### Estado de classificação Os endpoints que indicam se algo existe (registo de domínios, handles de redes sociais, registos DNS e de autenticação de e-mail, security.txt, robots.txt, sitemaps, cabeçalhos de segurança, parking, registos typosquat e certificados SSL) adicionam um objeto `classification` junto dos campos existentes. Os campos existentes mantêm o nome e o significado. - `status` - `present`, `absent` ou `unknown`. Present e absent só são devolvidos quando a verificação obteve evidência exata e fiável. - `reason` - Devolvido apenas quando o estado é `unknown`. Explica por que não foi possível dar uma resposta definitiva. - `evidence` - De onde veio a resposta: `source`, `method`, `observed_at` e um `detail` opcional, como `http_404` ou `nxdomain`. - `checked_at` - Quando o DomScan produziu a classificação. Em resultados em cache, `evidence.observed_at` é anterior. #### Motivos de unknown - `blocked` - O destino recusou o acesso, por exemplo com HTTP 401, 403 ou um desafio anti-bot. - `rate_limited` - O destino ou o registo pediu-nos para abrandar, por exemplo com HTTP 429. - `timeout` - A verificação não terminou dentro do tempo previsto. - `ambiguous` - Chegou uma resposta, mas não provou presença nem ausência, por exemplo um código de estado inesperado ou um registo malformado. - `upstream_error` - A fonte de dados falhou, por exemplo uma falha do servidor DNS ou uma resposta HTTP 5xx. - `unsupported` - Esta verificação não está disponível para a entrada, por exemplo um TLD não suportado ou uma plataforma sem verificador fiável. ```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" } } ``` Uma verificação bloqueada, limitada, expirada ou falhada nunca é comunicada como absent. Trate `unknown` como «tente mais tarde» e não como «não existe», e nunca interprete a ausência como prova de que um nome pode ser reivindicado. #### Pontuações e classificações com verificações desconhecidas As pontuações nunca contam uma verificação desconhecida como em falta. A pontuação de segurança DNS e a classificação de autenticação de e-mail deixam de fora as verificações desconhecidas, indicam-nas em `checks_unknown` e definem `score_confidence` como `partial`. Quando todas as verificações são desconhecidas, a pontuação e a classificação são `null`. A classificação e a pontuação SSL são `null` com `grade_reason` definido como `certificate_not_retrieved` quando não foi possível ler nenhum certificado, e a pontuação de reputação indica o parking desconhecido como `null` em vez de não estacionado.