Formato de resposta

Formato de resposta

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

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.

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.

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.

Exemplo

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.

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

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.