응답 형식

응답 형식

모든 응답은 JSON입니다. 각 도메인 결과에는 다음 공통 필드가 포함됩니다.

• domain - 전체 도메인 이름
• available - 불리언 가용성 상태
• source - "rdap" 또는 "cache"
• checked_at - ISO 8601 타임스탬프
• error - 오류가 발생한 경우 포함됨

응답 메타데이터

각 API 응답에는 요청 ID와 최신성 값이 포함됩니다. 가능한 경우 응답 헤더에는 요청된, 청구된, 환불된, 남은 크레딧과 함께 사용자의 속도 제한 플랜, 제한, 남은 용량, 정책도 표시됩니다. unknown 최신성 값은 해당 응답의 최신성을 확인할 수 없었다는 의미입니다. 데이터가 최신이라는 뜻은 아닙니다.

필드 선택 및 간결한 응답

모든 GET 또는 POST 요청의 쿼리 문자열에 fields 또는 compact를 추가하면 더 작은 JSON 응답을 받을 수 있습니다. 둘 다 선택 사항입니다. POST 요청에서는 본문이 아니라 쿼리 문자열에 넣습니다. 둘 다 크레딧 비용을 바꾸지 않습니다.

필드 선택

fields는 쉼표로 구분한 점 경로를 받습니다(예: fields=domain,classification.status,records.data). 경로가 목록을 가로지르면 모든 항목에 적용됩니다. 항목의 위치는 유지되며, 선택된 필드가 하나도 없는 항목은 {}가 됩니다. 경로 중간의 null 값은 null로 유지됩니다.

경로는 최대 50개까지 보낼 수 있으며, 각 경로는 영문자, 숫자, 밑줄로 이루어진 1~64자 세그먼트를 최대 6개까지 가질 수 있습니다. 그 외의 값은 요청이 실행되기 전에 400 INVALID_PARAMETER를 반환하므로 요금이 청구되지 않습니다.

응답에서 어디에도 일치하지 않는 경로는 제외되며 X-Fields-Ignored 응답 헤더에 최대 20개까지 나열됩니다.

간결한 응답

compact=true는 다음 항목만 제거하며, 응답의 최상위 수준에 있는 것에 한합니다.

• meta 객체 안의 served_by와 시간 관련 키인 duration_ms, query_time_ms, total_ms, total_time_ms, latency_ms, generation_ms, check_duration_ms. meta 객체에 다른 내용이 남지 않으면 객체 자체도 제거됩니다.
• 빈 목록인 warnings, caveats, notes, errors.
• X-Request-Id 헤더와 같은 값을 반복하는 request_id.

데이터 필드, classification, 중첩 객체, 목록 항목은 절대 제거되지 않습니다. 두 파라미터를 함께 보내면 compact가 먼저, fields가 나중에 실행됩니다.

성공한 JSON 응답만 재구성됩니다. 오류 응답, CSV, 텍스트 및 스트리밍 응답, dry_run 추정치는 그대로 반환됩니다. 재구성된 응답은 들여쓰기 없이 전송됩니다.

Idempotency-Key를 사용하면 fields와 compact는 요청의 일부가 됩니다. 같은 값으로 재시도하면 저장된, 재구성된 응답이 반환됩니다. 다른 값으로 같은 키를 다시 사용하면 422 IDEMPOTENCY_KEY_REUSED가 반환됩니다.

MCP 도구도 동일한 선택적 fields 및 compact 인수를 받습니다. 일치하지 않은 경로는 도구 결과의 _meta.fields_ignored에 나열됩니다.

예시

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 키 (naming)

대부분의 응답 키는 이미 snake_case이지만, 일부 엔드포인트는 가격 결과의 registrarName, 가치 평가 요인의 tldTier, RDAP 이벤트의 eventDate처럼 일부 camelCase 키를 반환합니다. 쿼리 문자열에 naming=snake를 추가하거나 DomScan-Naming: snake 헤더를 보내면 이러한 키가 모두 snake_case로 반환됩니다. 지정하지 않으면 응답은 현재의 키를 그대로 유지합니다.

키가 소문자로 시작하고, 영문자와 숫자만 포함하며, 대문자가 하나 이상 있는 경우에만 변환됩니다. 새로운 단어 앞에는 밑줄이 붙고 키 전체가 소문자로 바뀝니다. IPv4와 같은 약어와 IPs 같은 복수형은 하나로 묶여 유지됩니다. registrarName은 registrar_name, secureDNS는 secure_dns, ipv4Address는 ipv4_address, nameserverIPs는 nameserver_ips가 됩니다.

필드 이름이 아니라 데이터에 해당하는 키는 철자가 그대로 유지됩니다. 예를 들어 A, MX 같은 DNS 레코드 유형, A+ 같은 등급, 도메인 이름, 헤더 이름, 기술 이름이 여기에 해당합니다. 값은 절대 변경되지 않으며, 중첩된 객체와 목록은 모든 단계에서 변환됩니다.

객체에 이미 snake_case 이름이 있는 경우, 예를 들어 fooBar와 foo_bar가 모두 있으면 foo_bar는 기존 값을 유지하고 fooBar는 원래 이름을 유지하므로 데이터가 손실되지 않습니다. 키 순서도 바뀌지 않습니다.

쿼리 매개변수가 헤더보다 우선하므로, naming=default를 사용하면 헤더로 설정한 옵트인을 한 번의 요청에 한해 해제할 수 있습니다. 허용되는 값은 snake와 default입니다. 그 외의 값은 요청이 실행되기 전에 400 INVALID_PARAMETER를 반환하므로 요금이 부과되지 않습니다. 응답에는 Vary: DomScan-Naming이 포함됩니다.

naming은 compact와 fields보다 먼저 실행되므로, fields 경로는 fields=factors.tld_tier처럼 snake_case로 작성하세요. 오류 응답은 이미 snake_case이며 변경되지 않고, 크레딧 비용도 동일합니다.

Idempotency-Key를 사용하는 경우 naming 선택은 매개변수로 지정했든 헤더로 지정했든 요청의 일부로 취급되므로, 재시도해도 동일한 키가 반환됩니다.

MCP 도구도 동일한 선택적 naming 인수를 받습니다. MCP 호출은 헤더를 읽지 않습니다.

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

최신성 제어 (max_age)

최근에 확인한 데이터로 응답할 수 있는 엔드포인트는 max_age를 지원합니다. 0부터 2592000(30일) 사이의 정수이며 단위는 초입니다. max_age보다 오래된 데이터는 반환하기 전에 다시 확인하고, max_age=0이면 항상 새로 확인합니다. max_age를 보내지 않으면 각 엔드포인트는 기존 동작을 유지합니다.

이 엔드포인트의 모든 성공 응답에는 최상위 필드 cache_age_s가 포함됩니다. 사용된 데이터의 경과 시간(초)이며, 새로 확인한 경우에는 0입니다. 같은 값이 X-Cache-Age 응답 헤더로도 전달됩니다. 여러 도메인의 사용 가능 여부 확인처럼 응답에 여러 항목이 있으면 가장 오래된 항목의 경과 시간이며, 이미 cache_age_s가 있던 항목은 각자의 값을 유지합니다.

max_age는 결과의 분류 방식을 바꾸지 않습니다. 확인하지 못한 결과는 아무리 최근이어도 unknown으로 남으며, 최근 데이터도 원래 확인에서 입증되지 않은 한 존재 또는 부재로 표시되지 않습니다.

max_age는 요청 비용을 바꾸지 않습니다. 새로 확인하든 최근 데이터로 응답하든 크레딧은 동일하게 차감됩니다.

/v1/status와 /v1/status/bulk에서는 레지스트리를 보호하기 위해 강제 최신 확인(max_age=0)이 클라이언트별로 제한됩니다. 한도를 넘으면 max_age를 보내지 않은 것처럼 응답하며, cache_age_s에 받은 데이터의 경과 시간이 표시됩니다. 0부터 2592000 사이의 정수가 아닌 max_age는 요청이 실행되기 전에 400 INVALID_PARAMETER를 반환하므로 요금이 청구되지 않습니다.

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

이전 캐시 파라미터

이 파라미터들은 계속 동작하며, 이제 max_age의 지원 중단 예정 별칭입니다. max_age를 함께 보내면 max_age가 우선합니다.

/v1/subdomains에서는 prefer_cache가 캐시 전용 동작도 그대로 유지합니다. 저장된 데이터가 아직 없으면 요청은 요금을 청구하지 않고 202를 반환하며 백그라운드에서 조회를 시작합니다.

이 엔드포인트용 MCP 도구도 동일한 선택 인수 max_age를 지원하며, 결과에 cache_age_s가 포함됩니다.

페이지네이션 (limit 및 cursor)

긴 목록을 반환하는 엔드포인트는 limit과 cursor를 지원하며, 모든 응답에 has_more와 next_cursor가 포함됩니다. 다음 페이지를 가져오려면 cursor를 next_cursor 값으로 설정해 같은 요청을 다시 보내세요. 마지막 페이지에서는 has_more가 false이고 next_cursor가 null입니다.

limit을 보내지 않으면 각 엔드포인트는 이전과 같은 개수의 항목을 반환하므로 기존 요청은 달라지지 않습니다. 페이지마다 limit을 바꿀 수 있습니다.

커서는 불투명하며 서명되어 있습니다. 커서는 발급받은 계정과 동일한 쿼리(같은 도메인과 필터 등)에서만 동작합니다. 수정된 커서, 다른 계정의 커서, 다른 필터와 함께 보낸 커서는 400 INVALID_CURSOR를 반환합니다.

페이지는 안정적인 순서를 따르므로 요청 사이에 항목이 추가되거나 제거되어도 중복되거나 누락되지 않습니다. 이력 엔드포인트에서 요약 필드는 현재 페이지의 항목을 설명합니다.

각 페이지는 일반 요청이며, 이전에 limit을 사용한 요청과 똑같이 해당 엔드포인트의 기본 크레딧이 차감됩니다. 무료 엔드포인트는 계속 무료입니다.

이전 파라미터도 계속 동작합니다. /v1/email/blacklist의 offset과 /v1/certificates의 숫자형 pagination.next_cursor입니다.

예시

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

분류 상태

무언가가 존재하는지 알려 주는 엔드포인트(도메인 등록, 소셜 핸들, DNS 및 이메일 인증 레코드, security.txt, robots.txt, 사이트맵, 보안 헤더, 파킹, 타이포스쿼트 등록, SSL 인증서)는 기존 필드와 함께 classification 객체를 추가로 반환합니다. 기존 필드의 이름과 의미는 그대로입니다.

• status - present(존재), absent(부재), unknown(알 수 없음) 중 하나입니다. present와 absent는 검사에서 정확하고 신뢰할 수 있는 증거를 얻었을 때만 반환됩니다.
• reason - 상태가 unknown일 때만 반환됩니다. 확정적인 답을 내리지 못한 이유를 설명합니다.
• evidence - 답의 출처 정보입니다. source, method, observed_at와 http_404, nxdomain 같은 선택적 detail이 포함됩니다.
• checked_at - DomScan이 분류를 생성한 시각입니다. 캐시된 결과에서는 evidence.observed_at이 더 이전 시각입니다.

unknown 사유

• blocked - 대상이 접근을 거부했습니다. 예를 들어 HTTP 401, 403 또는 봇 확인 요구가 반환된 경우입니다.
• rate_limited - 대상 또는 레지스트리가 요청 속도를 낮춰 달라고 요청했습니다. 예를 들어 HTTP 429가 반환된 경우입니다.
• timeout - 검사가 제한 시간 안에 끝나지 않았습니다.
• ambiguous - 응답은 도착했지만 존재 여부를 입증하지 못했습니다. 예를 들어 예상치 못한 상태 코드나 형식이 잘못된 레코드입니다.
• upstream_error - 데이터 소스에 장애가 발생했습니다. 예를 들어 DNS 서버 장애나 HTTP 5xx 응답입니다.
• unsupported - 이 입력에는 해당 검사를 사용할 수 없습니다. 예를 들어 지원하지 않는 TLD이거나 신뢰할 만한 확인 수단이 없는 플랫폼입니다.

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

알 수 없는 검사가 있는 점수와 등급

점수는 알 수 없는 검사를 누락으로 계산하지 않습니다. DNS 보안 점수와 이메일 인증 등급은 알 수 없는 검사를 제외하고, 이를 checks_unknown에 보고하며, score_confidence를 partial로 설정합니다. 모든 검사를 알 수 없으면 점수와 등급은 null입니다. 인증서를 읽을 수 없으면 SSL 등급과 점수는 null이 되고 grade_reason은 certificate_not_retrieved로 설정되며, 평판 점수는 파킹 여부를 알 수 없을 때 파킹되지 않음 대신 null을 보고합니다.